# API Reference / Agents Tools
> Every page below, concatenated. Each section gives the page title, its upstream source and its path in this repository.
---
## Skill authoring best practices - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
Path: 04-API-Reference/Agents-Tools/agents-and-tools-agent-skills-best-practices.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fagent-skills%2Fbest-practices)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Skills
# Skill authoring best practices
Copy page
Learn how to write effective Skills that Claude can discover and use successfully.
Copy page
Good Skills are concise, well-structured, and tested with real usage. This guide provides practical authoring decisions to help you write Skills that Claude can discover and use effectively.
For conceptual background on how Skills work, see the [Skills overview](agents-and-tools-agent-skills-overview.md).
## Core principles
### Concise is key
The [context window](../Guides/build-with-claude-context-windows.md) is a public good. Your Skill shares the context window with everything else Claude needs to know, including:
- The system prompt
- Conversation history
- Other Skills' metadata
- Your actual request
Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads SKILL.md only when the Skill becomes relevant, and reads additional files only as needed. However, being concise in SKILL.md still matters: once Claude loads it, every token competes with conversation history and other context.
**Default assumption:** Claude is already very smart
Only add context Claude doesn't already have. Challenge each piece of information:
- "Does Claude really need this explanation?"
- "Can I assume Claude knows this?"
- "Does this paragraph justify its token cost?"
**Good example: Concise** (approximately 50 tokens):
```` shiki
## Extract PDF text
Use pdfplumber for text extraction:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
````
**Bad example: Too verbose** (approximately 150 tokens):
```python
## Extract PDF text
PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but
pdfplumber is recommended because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...
```
The concise version assumes Claude already has information about PDFs and how libraries work.
### Set appropriate degrees of freedom
Match the level of specificity to the task's fragility and variability.
**High freedom** (text-based instructions):
Use when:
- Multiple approaches are valid
- Decisions depend on context
- Heuristics guide the approach
Example:
```python
## Code review process
1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions
```
**Medium freedom** (pseudocode or scripts with parameters):
Use when:
- A preferred pattern exists
- Some variation is acceptable
- Configuration affects behavior
Example:
```` shiki
## Generate report
Use this template and customize as needed:
```python
def generate_report(data, format="markdown", include_charts=True):
# Process data
# Generate output in specified format
# Optionally include visualizations
```
````
**Low freedom** (specific scripts, few or no parameters):
Use when:
- Operations are fragile and error-prone
- Consistency is critical
- A specific sequence must be followed
Example:
```` shiki
## Database migration
Run exactly this script:
```bash
python scripts/migrate.py --verify --backup
```
Do not modify the command or add additional flags.
````
**Analogy:** Think of Claude as a robot exploring a path:
- **Narrow bridge with cliffs on both sides:** There's only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence.
- **Open field with no hazards:** Many paths lead to success. Give general direction and trust Claude to find the best route (high freedom). Example: code reviews where context determines the best approach.
### Test with all models you plan to use
Skills act as additions to models, so effectiveness depends on the underlying model. Test your Skill with all the models you plan to use it with.
**Testing considerations by model:**
- **Claude Haiku** (fast, economical): Does the Skill provide enough guidance?
- **Claude Sonnet** (balanced): Is the Skill clear and efficient?
- **Claude Opus** (powerful reasoning): Does the Skill avoid over-explaining?
What works perfectly for Opus might need more detail for Haiku. If you plan to use your Skill across multiple models, aim for instructions that work well with all of them.
## Skill structure
**YAML Frontmatter:** The SKILL.md frontmatter requires two fields:
`name`:
- Maximum 64 characters
- Must contain only lowercase letters, numbers, and hyphens
- Cannot contain XML tags
- Cannot contain reserved words: "anthropic", "claude"
`description`:
- Must be non-empty
- Maximum 1,024 characters
- Cannot contain XML tags
- Should describe what the Skill does and when to use it
For complete Skill structure details, see the [Skills overview](agents-and-tools-agent-skills-overview.md#skill-structure).
### Naming conventions
Use consistent naming patterns to make Skills easier to reference and discuss. Consider using **gerund form** (verb + -ing) for Skill names, as this clearly describes the activity or capability the Skill provides.
Remember that the `name` field must use lowercase letters, numbers, and hyphens only.
**Good naming examples (gerund form):**
- `processing-pdfs`
- `analyzing-spreadsheets`
- `managing-databases`
- `testing-code`
- `writing-documentation`
**Acceptable alternatives:**
- Noun phrases: `pdf-processing`, `spreadsheet-analysis`
- Action-oriented: `process-pdfs`, `analyze-spreadsheets`
**Avoid:**
- Vague names: `helper`, `utils`, `tools`
- Overly generic: `documents`, `data`, `files`
- Reserved words: `anthropic-helper`, `claude-tools`
- Inconsistent patterns within your skill collection
Consistent naming makes it easier to:
- Reference Skills in documentation and conversations
- Understand what a Skill does at a glance
- Organize and search through multiple Skills
- Maintain a professional, cohesive skill library
### Writing effective descriptions
The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
**Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.
- **Good:** "Processes Excel files and generates reports"
- **Avoid:** "I can help you process Excel files"
- **Avoid:** "You can use this to process Excel files"
**Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it.
Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Claude to know when to select this Skill, while the rest of SKILL.md provides the implementation details.
Effective examples:
**PDF Processing skill:**
```python
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
```
**Excel Analysis skill:**
```python
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
```
**Git Commit Helper skill:**
```python
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
```
Avoid vague descriptions like these:
```python
description: Helps with documents
```
```python
description: Processes data
```
```python
description: Does stuff with files
```
### Progressive disclosure patterns
SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide. For an explanation of how progressive disclosure works, see [How Skills work](agents-and-tools-agent-skills-overview.md#how-skills-work) in the overview.
**Practical guidance:**
- Keep SKILL.md body under 500 lines for optimal performance
- Split content into separate files when approaching this limit
- Use the following patterns to organize instructions, code, and resources effectively
#### Visual overview: From simple to complex
A basic Skill starts with just a SKILL.md file containing metadata and instructions:
As your Skill grows, you can bundle additional content that Claude loads only when needed:
The complete Skill directory structure might look like this:
- `pdf/`
- `SKILL.md`: Main instructions (loaded when triggered)
- `FORMS.md`: Form-filling guide (loaded as needed)
- `reference.md`: API reference (loaded as needed)
- `examples.md`: Usage examples (loaded as needed)
- `scripts/`
- `analyze_form.py`: Utility script (executed, not loaded)
- `fill_form.py`: Form filling script
- `validate.py`: Validation script
#### Pattern 1: High-level guide with references
```` shiki
---
name: pdf-processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
# PDF Processing
## Quick start
Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
## Advanced features
**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
````
Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
#### Pattern 2: Domain-specific organization
For Skills with multiple domains, organize content by domain to avoid loading irrelevant context. When a user asks about sales metrics, Claude only needs to read sales-related schemas, not finance or marketing data. This keeps token usage low and context focused.
- `bigquery-skill/`
- `SKILL.md` (overview and navigation)
- `reference/`
- `finance.md` (revenue, billing metrics)
- `sales.md` (opportunities, pipeline)
- `product.md` (API usage, features)
- `marketing.md` (campaigns, attribution)
SKILL.md
```` shiki
# BigQuery Data Analysis
## Available datasets
**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)
## Quick search
Find specific metrics using grep:
```bash
grep -i "revenue" reference/finance.md
grep -i "pipeline" reference/sales.md
grep -i "api usage" reference/product.md
```
````
#### Pattern 3: Conditional details
Show basic content, link to advanced content:
```python
# DOCX Processing
## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
## Editing documents
For simple edits, modify the XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)
```
Claude reads REDLINING.md or OOXML.md only when the user needs those features.
### Avoid deeply nested references
Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like `head -100` to preview content rather than reading entire files, resulting in incomplete information.
**Keep references one level deep from SKILL.md**. All reference files should link directly from SKILL.md to ensure Claude reads complete files when needed.
**Bad example: Too deep**:
```python
# SKILL.md
See [advanced.md](advanced.md)...
# advanced.md
See [details.md](details.md)...
# details.md
Here's the actual information...
```
**Good example: One level deep**:
```python
# SKILL.md
**Basic usage**: [instructions in SKILL.md]
**Advanced features**: See [advanced.md](advanced.md)
**API reference**: See [reference.md](reference.md)
**Examples**: See [examples.md](examples.md)
```
### Structure longer reference files with table of contents
For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads.
**Example:**
```python
# API Reference
## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples
## Authentication and setup
...
## Core methods
...
```
Claude can then read the complete file or jump to specific sections as needed.
For details on how this filesystem-based architecture enables progressive disclosure, see the [Runtime environment](#runtime-environment) section later in this guide.
## Workflows and feedback loops
### Use workflows for complex tasks
Break complex operations into clear, sequential steps. For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses.
**Example 1: Research synthesis workflow** (for Skills without code):
```` shiki
## Research synthesis workflow
Copy this checklist and track your progress:
```
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
```
**Step 1: Read all source documents**
Review each document in the `sources/` directory. Note the main arguments and supporting evidence.
**Step 2: Identify key themes**
Look for patterns across sources. What themes appear repeatedly? Where do sources agree or disagree?
**Step 3: Cross-reference claims**
For each major claim, verify it appears in the source material. Note which source supports each point.
**Step 4: Create structured summary**
Organize findings by theme. Include:
- Main claim
- Supporting evidence from sources
- Conflicting viewpoints (if any)
**Step 5: Verify citations**
Check that every claim references the correct source document. If citations are incomplete, return to Step 3.
````
This example shows how workflows apply to analysis tasks that don't require code. The checklist pattern works for any complex, multistep process.
**Example 2: PDF form filling workflow** (for Skills with code):
```` shiki
## PDF form filling workflow
Copy this checklist and check off items as you complete them:
```
Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)
```
**Step 1: Analyze the form**
Run: `python scripts/analyze_form.py input.pdf`
This extracts form fields and their locations, saving to `fields.json`.
**Step 2: Create field mapping**
Edit `fields.json` to add values for each field.
**Step 3: Validate mapping**
Run: `python scripts/validate_fields.py fields.json`
Fix any validation errors before continuing.
**Step 4: Fill the form**
Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`
**Step 5: Verify output**
Run: `python scripts/verify_output.py output.pdf`
If verification fails, return to Step 2.
````
Clear steps prevent Claude from skipping critical validation. The checklist helps both Claude and you track progress through multistep workflows.
### Implement feedback loops
**Common pattern:** Run validator → fix errors → repeat
This pattern greatly improves output quality.
**Example 1: Style guide compliance** (for Skills without code):
```python
## Content review process
1. Draft your content following the guidelines in STYLE_GUIDE.md
2. Review against the checklist:
- Check terminology consistency
- Verify examples follow the standard format
- Confirm all required sections are present
3. If issues found:
- Note each issue with specific section reference
- Revise the content
- Review the checklist again
4. Only proceed when all requirements are met
5. Finalize and save the document
```
This shows the validation loop pattern using reference documents instead of scripts. The "validator" is STYLE_GUIDE.md, and Claude performs the check by reading and comparing.
**Example 2: Document editing process** (for Skills with code):
```python
## Document editing process
1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails:
- Review the error message carefully
- Fix the issues in the XML
- Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python ooxml/scripts/pack.py unpacked_dir/ output.docx`
6. Test the output document
```
The validation loop catches errors early.
## Content guidelines
### Avoid time-sensitive information
Don't include information that will become outdated:
**Bad example: Time-sensitive** (will become wrong):
```python
If you're doing this before August 2025, use the old API.
After August 2025, use the new API.
```
**Good example** (use "old patterns" section):
```python
## Current method
Use the v2 API endpoint: `api.example.com/v2/messages`
## Old patterns
Legacy v1 API (deprecated 2025-08)
The v1 API used: `api.example.com/v1/messages`
This endpoint is no longer supported.
```
The old patterns section provides historical context without cluttering the main content.
### Use consistent terminology
Choose one term and use it throughout the Skill:
**Good - Consistent:**
- Always "API endpoint"
- Always "field"
- Always "extract"
**Bad - Inconsistent:**
- Mix "API endpoint", "URL", "API route", "path"
- Mix "field", "box", "element", "control"
- Mix "extract", "pull", "get", "retrieve"
Consistency helps Claude parse and follow instructions.
## Common patterns
### Template pattern
Provide templates for output format. Match the level of strictness to your needs.
**For strict requirements** (such as API responses or data formats):
```` shiki
## Report structure
ALWAYS use this exact template structure:
```markdown
# [Analysis Title]
## Executive summary
[One-paragraph overview of key findings]
## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data
## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
```
````
**For flexible guidance** (when adaptation is useful):
```` shiki
## Report structure
Here is a sensible default format, but use your best judgment based on the analysis:
```markdown
# [Analysis Title]
## Executive summary
[Overview]
## Key findings
[Adapt sections based on what you discover]
## Recommendations
[Tailor to the specific context]
```
Adjust sections as needed for the specific analysis type.
````
### Examples pattern
For Skills where output quality depends on seeing examples, provide input/output pairs just like in regular prompting:
```` shiki
## Commit message format
Generate commit messages following these examples:
**Example 1:**
Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication
Add login endpoint and token validation middleware
```
**Example 2:**
Input: Fixed bug where dates displayed incorrectly in reports
Output:
```
fix(reports): correct date formatting in timezone conversion
Use UTC timestamps consistently across report generation
```
**Example 3:**
Input: Updated dependencies and refactored error handling
Output:
```
chore: update dependencies and refactor error handling
- Upgrade lodash to 4.17.21
- Standardize error response format across endpoints
```
Follow this style: type(scope): brief description, then detailed explanation.
````
Examples convey the desired style and level of detail to Claude more clearly than descriptions alone.
### Conditional workflow pattern
Guide Claude through decision points:
```python
## Document modification workflow
1. Determine the modification type:
**Creating new content?** → Follow "Creation workflow" below
**Editing existing content?** → Follow "Editing workflow" below
2. Creation workflow:
- Use docx-js library
- Build document from scratch
- Export to .docx format
3. Editing workflow:
- Unpack existing document
- Modify XML directly
- Validate after each change
- Repack when complete
```
If workflows become large or complicated with many steps, consider pushing them into separate files and tell Claude to read the appropriate file based on the task at hand.
## Evaluation and iteration
### Build evaluations first
**Create evaluations BEFORE writing extensive documentation.** This ensures your Skill solves real problems rather than documenting imagined ones.
**Evaluation-driven development:**
1. **Identify gaps:** Run Claude on representative tasks without a Skill. Document specific failures or missing context
2. **Create evaluations:** Build three scenarios that test these gaps
3. **Establish baseline:** Measure Claude's performance without the Skill
4. **Write minimal instructions:** Create just enough content to address the gaps and pass evaluations
5. **Iterate:** Execute evaluations, compare against baseline, and refine
This approach ensures you're solving actual problems rather than anticipating requirements that may never materialize.
**Evaluation structure:**
```python
{
"skills": ["pdf-processing"],
"query": "Extract all text from this PDF file and save it to output.txt",
"files": ["test-files/document.pdf"],
"expected_behavior": [
"Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
"Extracts text content from all pages in the document without missing any pages",
"Saves the extracted text to a file named output.txt in a clear, readable format"
]
}
```
This example demonstrates a data-driven evaluation with a simple testing rubric. There is not currently a built-in way to run these evaluations. Users can create their own evaluation system. Evaluations are your source of truth for measuring Skill effectiveness.
### Develop Skills iteratively with Claude
The most effective Skill development process involves Claude itself. Work with one instance of Claude ("Claude A") to create a Skill that is used by other instances ("Claude B"). Claude A helps you design and refine instructions, while Claude B tests them in real tasks. This works because Claude models understand both how to write effective agent instructions and what information agents need.
**Creating a new Skill:**
1. **Complete a task without a Skill:** Work through a problem with Claude A using normal prompting. As you work, you'll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide.
2. **Identify the reusable pattern:** After completing the task, identify what context you provided that would be useful for similar future tasks.
**Example:** If you worked through a BigQuery analysis, you might have provided table names, field definitions, filtering rules (such as "always exclude test accounts"), and common query patterns.
3. **Ask Claude A to create a Skill:** "Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts."
Claude models understand the Skill format and structure natively. You don't need special system prompts or a "writing skills" skill to get Claude to help create Skills. Simply ask Claude to create a Skill and it generates properly structured SKILL.md content with appropriate frontmatter and body content.
4. **Review for conciseness:** Check that Claude A hasn't added unnecessary explanations. Ask: "Remove the explanation about what win rate means - Claude already knows that."
5. **Improve information architecture:** Ask Claude A to organize the content more effectively. For example: "Organize this so the table schema is in a separate reference file. We might add more tables later."
6. **Test on similar tasks:** Use the Skill with Claude B (a fresh instance with the Skill loaded) on related use cases. Observe whether Claude B finds the right information, applies rules correctly, and handles the task successfully.
7. **Iterate based on observation:** If Claude B struggles or misses something, return to Claude A with specifics: "When Claude used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?"
**Iterating on existing Skills:**
The same hierarchical pattern continues when improving Skills. You alternate between:
- **Working with Claude A** (the expert who helps refine the Skill)
- **Testing with Claude B** (the agent using the Skill to perform real work)
- **Observing Claude B's behavior** and bringing insights back to Claude A
1. **Use the Skill in real workflows:** Give Claude B (with the Skill loaded) actual tasks, not test scenarios
2. **Observe Claude B's behavior:** Note where it struggles, succeeds, or makes unexpected choices
**Example observation:** "When I asked Claude B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule."
3. **Return to Claude A for improvements:** Share the current SKILL.md and describe what you observed. Ask: "I noticed Claude B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it's not prominent enough?"
4. **Review Claude A's suggestions:** Claude A might suggest reorganizing to make rules more prominent, using stronger language such as "MUST filter" instead of "always filter," or restructuring the workflow section.
5. **Apply and test changes:** Update the Skill with Claude A's refinements, then test again with Claude B on similar requests
6. **Repeat based on usage:** Continue this observe-refine-test cycle as you encounter new scenarios. Each iteration improves the Skill based on real agent behavior, not assumptions.
**Gathering team feedback:**
1. Share Skills with teammates and observe their usage
2. Ask: Does the Skill activate when expected? Are instructions clear? What's missing?
3. Incorporate feedback to address gaps in your own usage patterns
**Why this approach works:** Claude A understands agent needs, you provide domain expertise, Claude B reveals gaps through real usage, and iterative refinement improves Skills based on observed behavior rather than assumptions.
### Observe how Claude navigates Skills
As you iterate on Skills, pay attention to how Claude actually uses them in practice. Watch for:
- **Unexpected exploration paths:** Does Claude read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought
- **Missed connections:** Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent
- **Overreliance on certain sections:** If Claude repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead
- **Ignored content:** If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions
Iterate based on these observations rather than assumptions. The 'name' and 'description' in your Skill's metadata are particularly critical. Claude uses these when determining whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used.
## Anti-patterns to avoid
### Avoid Windows-style paths
Always use forward slashes in file paths, even on Windows:
- [x] **Good:** `scripts/helper.py`, `reference/guide.md`
- ✗ **Avoid:** `scripts\helper.py`, `reference\guide.md`
Unix-style paths work across all platforms, while Windows-style paths cause errors on Unix systems.
### Avoid offering too many options
Don't present multiple approaches unless necessary:
```` shiki
**Bad example: Too many choices** (confusing):
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."
**Good example: Provide a default** (with escape hatch):
"Use pdfplumber for text extraction:
```python
import pdfplumber
```
For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."
````
## Advanced: Skills with executable code
The following sections focus on Skills that include executable scripts. If your Skill uses only markdown instructions, skip to [Checklist for effective Skills](#checklist-for-effective-skills).
### Solve, don't defer
When writing scripts for Skills, handle error conditions rather than deferring to Claude.
**Good example: Handle errors explicitly:**
```python
def process_file(path):
"""Process a file, creating it if it doesn't exist."""
try:
with open(path) as f:
return f.read()
except FileNotFoundError:
# Create file with default content instead of failing
print(f"File {path} not found, creating default")
with open(path, "w") as f:
f.write("")
return ""
except PermissionError:
# Provide alternative instead of failing
print(f"Cannot access {path}, using default")
return ""
```
**Bad example: Defer to Claude:**
```python
def process_file(path):
# Just fail and let Claude figure it out
return open(path).read()
```
Configuration parameters should also be justified and documented to avoid "voodoo constants" (Ousterhout's law). If you don't know the right value, how will Claude determine it?
**Good example: Self-documenting:**
```python
# HTTP requests typically complete within 30 seconds
# Longer timeout accounts for slow connections
REQUEST_TIMEOUT = 30
# Three retries balances reliability vs speed
# Most intermittent failures resolve by the second retry
MAX_RETRIES = 3
```
**Bad example: Magic numbers:**
```python
TIMEOUT = 47 # Why 47?
RETRIES = 5 # Why 5?
```
### Provide utility scripts
Even if Claude could write a script, pre-made scripts offer advantages:
**Benefits of utility scripts:**
- More reliable than generated code
- Save tokens (no need to include code in context)
- Save time (no code generation required)
- Ensure consistency across uses
The preceding diagram shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and Claude can execute it without loading its contents into context.
**Important distinction:** Make clear in your instructions whether Claude should:
- **Execute the script** (most common): "Run `analyze_form.py` to extract fields"
- **Read it as reference** (for complex logic): "See `analyze_form.py` for the field extraction algorithm"
For most utility scripts, execution is preferred because it's more reliable and efficient. See the following [Runtime environment](#runtime-environment) section for details on how script execution works.
**Example:**
```` shiki
## Utility scripts
**analyze_form.py**: Extract all form fields from PDF
```bash
python scripts/analyze_form.py input.pdf > fields.json
```
Output format:
```json
{
"field_name": {"type": "text", "x": 100, "y": 200},
"signature": {"type": "sig", "x": 150, "y": 500}
}
```
**validate_boxes.py**: Check for overlapping bounding boxes
```bash
python scripts/validate_boxes.py fields.json
# Returns: "OK" or lists conflicts
```
**fill_form.py**: Apply field values to PDF
```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```
````
### Use visual analysis
When inputs can be rendered as images, have Claude analyze them:
```` shiki
## Form layout analysis
1. Convert PDF to images:
```bash
python scripts/pdf_to_images.py form.pdf
```
2. Analyze each page image to identify form fields
3. Claude can see field locations and types visually
````
In this example, you'd need to write the `pdf_to_images.py` script.
Claude's vision capabilities help analyze layouts and structures.
### Create verifiable intermediate outputs
When Claude performs complex, open-ended tasks, it can make mistakes. The "plan-validate-execute" pattern catches errors early by having Claude first create a plan in a structured format, then validate that plan with a script before executing it.
**Example:** Imagine asking Claude to update 50 form fields in a PDF based on a spreadsheet. Without validation, Claude might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly.
**Solution:** Use the workflow pattern shown earlier (PDF form filling), but add an intermediate `changes.json` file that gets validated before applying changes. The workflow becomes: analyze → **create plan file** → **validate plan** → execute → verify.
**Why this pattern works:**
- **Catches errors early:** Validation finds problems before changes are applied
- **Machine-verifiable:** Scripts provide objective verification
- **Reversible planning:** Claude can iterate on the plan without touching originals
- **Clear debugging:** Error messages point to specific problems
**When to use:** Batch operations, destructive changes, complex validation rules, high-stakes operations.
**Implementation tip:** Make validation scripts verbose with specific error messages such as "Field 'signature_date' not found. Available fields: customer_name, order_total, signature_date_signed" to help Claude fix issues.
### Package dependencies
Skills run in the code execution environment with platform-specific limitations:
- **claude.ai:** Can install packages from npm and PyPI and pull from GitHub repositories
- **Claude API:** Has no network access and no runtime package installation
List required packages in your SKILL.md and verify they're available in the [Code execution tool](agents-and-tools-tool-use-code-execution-tool.md) documentation.
### Runtime environment
Skills run in a code execution environment with filesystem access, bash commands, and code execution capabilities. For the conceptual explanation of this architecture, see [The Skills architecture](agents-and-tools-agent-skills-overview.md#the-skills-architecture) in the overview.
**How this affects your authoring:**
**How Claude accesses Skills:**
1. **Metadata pre-loaded:** At startup, the name and description from all Skills' YAML frontmatter are loaded into the system prompt
2. **Files read on-demand:** Claude uses bash Read tools to access SKILL.md and other files from the filesystem when needed
3. **Scripts executed efficiently:** Utility scripts can be executed through bash without loading their full contents into context. Only the script's output consumes tokens
4. **No context penalty for large files:** Reference files, data, or documentation don't consume context tokens until actually read
- **File paths matter:** Claude navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes
- **Name files descriptively:** Use names that indicate content: `form_validation_rules.md`, not `doc2.md`
- **Organize for discovery:** Structure directories by domain or feature
- Good: `reference/finance.md`, `reference/sales.md`
- Bad: `docs/file1.md`, `docs/file2.md`
- **Bundle comprehensive resources:** Include complete API docs, extensive examples, large datasets; no context penalty until accessed
- **Prefer scripts for deterministic operations:** Write `validate_form.py` rather than asking Claude to generate validation code
- **Make execution intent clear:**
- "Run `analyze_form.py` to extract fields" (execute)
- "See `analyze_form.py` for the extraction algorithm" (read as reference)
- **Test file access patterns:** Verify Claude can navigate your directory structure by testing with real requests
**Example:**
- `bigquery-skill/`
- `SKILL.md` (overview, points to reference files)
- `reference/`
- `finance.md` (revenue metrics)
- `sales.md` (pipeline data)
- `product.md` (usage analytics)
When the user asks about revenue, Claude reads SKILL.md, sees the reference to `reference/finance.md`, and calls bash to read just that file. The sales.md and product.md files remain on the filesystem, consuming zero context tokens until needed. This filesystem-based model is what enables progressive disclosure. Claude can navigate and selectively load exactly what each task requires.
For complete details on the technical architecture, see [How Skills work](agents-and-tools-agent-skills-overview.md#how-skills-work) in the Skills overview.
### MCP tool references
If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names to avoid "tool not found" errors.
**Format:** `ServerName:tool_name`
**Example:**
```python
Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.
```
Where:
- `BigQuery` and `GitHub` are MCP server names
- `bigquery_schema` and `create_issue` are the tool names within those servers
Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available.
### Avoid assuming tools are installed
Don't assume packages are available:
```python
**Bad example: Assumes installation**:
"Use the pdf library to process the file."
**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`
Then use it:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```"
```
## Technical notes
### YAML frontmatter requirements
The SKILL.md frontmatter requires `name` and `description` fields with specific validation rules:
- `name`: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved words
- `description`: Maximum 1,024 characters, non-empty, no XML tags
See the [Skills overview](agents-and-tools-agent-skills-overview.md#skill-structure) for complete structure details.
### Token budgets
Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files using the progressive disclosure patterns described earlier. For architectural details, see the [Skills overview](agents-and-tools-agent-skills-overview.md#how-skills-work).
## Checklist for effective Skills
Before sharing a Skill, verify:
### Core quality
- Description is specific and includes key terms
- Description includes both what the Skill does and when to use it
- SKILL.md body is under 500 lines
- Additional details are in separate files (if needed)
- No time-sensitive information (or in "old patterns" section)
- Consistent terminology throughout
- Examples are concrete, not abstract
- File references are one level deep
- Progressive disclosure used appropriately
- Workflows have clear steps
### Code and scripts
- Scripts solve problems rather than defer to Claude
- Error handling is explicit and helpful
- No "voodoo constants" (all values justified)
- Required packages listed in instructions and verified as available
- Scripts have clear documentation
- No Windows-style paths (all forward slashes)
- Validation/verification steps for critical operations
- Feedback loops included for quality-critical tasks
### Testing
- At least three evaluations created
- Tested with Haiku, Sonnet, and Opus
- Tested with real usage scenarios
- Team feedback incorporated (if applicable)
## Next steps
[Get started with Agent Skills](agents-and-tools-agent-skills-quickstart.md)
Create your first Skill
[Use Skills in Claude Code](../../08-Plugins-Skills/skills.md)
Create and manage Skills in Claude Code
[Use Skills with the API](../Guides/build-with-claude-skills-guide.md)
Upload and use Skills programmatically
---
## Claude API skill - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill
Path: 04-API-Reference/Agents-Tools/agents-and-tools-agent-skills-claude-api-skill.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fagent-skills%2Fclaude-api-skill)
SearchCtrlK
Claude API skill
[Overview](agents-and-tools-agent-skills-claude-api-skill.md)
[Console](../Other/playground.md)
Claude API skill
# Claude API skill
Copy page
An open-source Agent Skill that provides Claude with up-to-date API reference material, SDK documentation, and best practices for building applications with the Claude API and Claude Managed Agents.
Copy page
The `claude-api` skill is an open-source [Agent Skill](agents-and-tools-agent-skills-overview.md) that provides Claude with detailed, up-to-date reference material for building applications on two Anthropic surfaces:
- **Messages API:** The primary surface for single requests, streaming chat, tool use, batch processing, prompt caching, structured outputs, and custom agent loops.
- **Claude Managed Agents (beta):** An Anthropic-hosted surface for server-managed stateful agents with Anthropic-hosted tool execution, persistent agent configs, and per-session sandboxes.
It covers eight programming languages for both the Messages API and Managed Agents: Python, TypeScript, C#, Go, Java, PHP, Ruby, and cURL.
The skill comes bundled with [Claude Code](../../02-Claude-Code-CLI/code-home.md) and is also available in the open-source [Anthropic skills repository](https://github.com/anthropics/skills), where you can install it in any environment that supports Agent Skills.
The skill uses [progressive disclosure](agents-and-tools-agent-skills-overview.md#how-skills-work) to keep context efficient: Claude loads only the documentation relevant to your project's language, surface (Messages API or Managed Agents), and the specific task at hand (tool use, streaming, batches, and so on), rather than loading everything at once.
## What the skill provides
When triggered, the skill equips Claude with:
**For the Messages API:**
- **Language-specific SDK documentation:** Installation, quick start, common patterns, and error handling for your project's language
- **Tool use guidance:** Language-specific examples and [conceptual foundations](agents-and-tools-tool-use-overview.md) for function calling, including the beta tool runner where available
- **Streaming patterns:** Implementation details for building chat UIs and handling incremental display
- **Batch processing:** Offline batch processing at 50% cost
- **Prompt caching:** Prefix-stability design, breakpoint placement, and silent-invalidator audit
- **Model migration:** Step-by-step guidance for migrating to newer Claude models (including the breaking changes and behavior shifts on [Claude Opus 5.5](../../20-Models/models-opus-5-5-migration-guide.md#migrating-from-claude-opus-5), [Claude Sonnet 5.5](../../20-Models/models-sonnet-5-5-migration-guide.md#migrating-from-claude-sonnet-5), [Claude Haiku 5.5](../../20-Models/models-haiku-5-5-migration-guide.md), and [Claude Fable 5.1](../../20-Models/models-fable-5-1-migration-guide.md))
- **Preserved thinking migration:** Finding, measuring, and fixing the history edits that invalidate `thinking` blocks, available through the `/claude-api preserved-thinking-migration` subcommand
- **Current model information:** Model IDs, context window sizes, and pricing
- **Common pitfalls:** Detailed guidance on avoiding frequent mistakes when integrating with the API
**For Managed Agents (beta):**
- **Onboarding flow:** An interview-driven walkthrough for setting up a new Managed Agent from scratch, available through the `/claude-api managed-agents-onboard` subcommand
- **Language-specific Managed Agents docs:** Creating persistent agents, starting sessions, streaming events, and handling tool confirmations for Python, TypeScript, C#, Go, Java, PHP, Ruby, and cURL
- **Client patterns:** Lossless stream reconnect, `processed_at` queued/processed gate, interrupt handling, file-mount gotchas, and credential handling
- **Deployment constraints:** Managed Agents is available on the Claude API and [Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md) only (not on Amazon Bedrock, Google Cloud, or Microsoft Foundry). The skill routes other deployments to the Messages API and tool use instead.
## When the skill activates
The skill activates in two ways:
**Automatic activation** occurs when:
- Your code imports an Anthropic SDK (`anthropic` for Python, `@anthropic-ai/sdk` for TypeScript/JavaScript)
- You ask Claude to help build, debug, or optimize something with the Claude API, an Anthropic SDK, or Managed Agents
- You add, modify, or tune a Claude feature in a file (prompt caching, adaptive thinking, compaction, tool use, batch, files, citations, memory) or a model reference
**Manual invocation** by typing `/claude-api` (with optional subcommand or prose) in any environment where the skill is installed.
The skill does not activate for general programming tasks, ML/data-science work, or code that imports other AI SDKs (such as OpenAI).
## Supported languages
The skill detects your project's language automatically by examining project files (for example, `requirements.txt` for Python, `tsconfig.json` for TypeScript, `go.mod` for Go) and loads the appropriate documentation.
| Language | Messages API SDK | Tool runner | Managed Agents |
|------------|------------------|-------------|----------------|
| Python | Yes | Yes (beta) | Yes (beta) |
| TypeScript | Yes | Yes (beta) | Yes (beta) |
| C# | Yes | Yes (beta) | Yes (beta) |
| Go | Yes | Yes (beta) | Yes (beta) |
| Java | Yes | Yes (beta) | Yes (beta) |
| PHP | Yes | Yes (beta) | Yes (beta) |
| Ruby | Yes | Yes (beta) | Yes (beta) |
| cURL | Yes | N/A | Yes (beta) |
If your project uses multiple languages, Claude asks which one applies. For unsupported languages (Rust, Swift, C++), the skill provides cURL/raw HTTP examples.
## How to use the skill
### In Claude Code (bundled)
The skill ships with [Claude Code](../../02-Claude-Code-CLI/code-home.md) and requires no installation. When you ask Claude to help build something with the Claude API, or when your project already imports an Anthropic SDK, the skill activates automatically.
You can also invoke it directly:
Claude Code
Use this skill in Claude Code
Run in
`❯``/claude-api`
For more about how bundled skills work in Claude Code, see the [Claude Code skills documentation](../../08-Plugins-Skills/skills.md#bundled-skills).
### From the skills repository
The skill source is available in the [Anthropic skills repository](https://github.com/anthropics/skills). You can install it using the `npx` command:
```python
npx skills add https://github.com/anthropics/skills --skill claude-api
```
Or ask Claude Code to install it as a [Claude Code plugin](../../08-Plugins-Skills/plugins.md):
Claude Code
Let Claude Code install this for you
Run in
`❯``Install the claude-api plugin from the anthropics/skills plugin marketplace`
### Manual install commands
``` block
/plugin marketplace add anthropics/skills
/plugin install claude-api@anthropic-agent-skills
```
## Migrating to a newer Claude model
The Claude API skill can perform Claude model migrations across a code base. Invoke it directly with the `migrate` subcommand:
Claude Code
Let Claude Code migrate your code for you
Run in
`❯``/claude-api`` migrate this project to the latest Claude Opus model`
You can also pass a specific scope up front to skip the scope-confirmation question:
Claude Code
Let Claude Code migrate your code for you
Run in
`❯``/claude-api`` migrate everything under src/ to the latest Claude Opus model`
Claude Code
Let Claude Code migrate your code for you
Run in
`❯``/claude-api`` migrate apps/api.py and apps/worker.py to the latest Claude Opus model`
When the scope is ambiguous (for example, a bare `/claude-api migrate to claude-opus-5-5`), the skill asks you to choose between the entire working directory, a specific subdirectory, or an explicit file list before editing any files. This applies to both Messages API and Managed Agents callers.
The skill handles:
- **Model ID swaps**, including typed SDK constants (`Model.CLAUDE_OPUS_4_8` → `Model.CLAUDE_OPUS_5_5`) across all supported languages, and classifies each file as a caller, a model definer, or an opaque string reference before editing
- **Cloud platform detection**, preserving platform-specific model ID formats (for example, the `anthropic.` prefix on Amazon Bedrock) and skipping changes for features that are unavailable on partner-operated platforms
- **Breaking parameter changes**, such as removing `temperature`, `top_p`, and `top_k` for Claude Opus 4.8 and Claude Opus 4.7, and converting `thinking: {type: "enabled", budget_tokens: N}` to `thinking: {type: "adaptive"}`
- **Prefill replacement**, converting assistant-message prefill patterns to [structured outputs](../Guides/build-with-claude-structured-outputs.md) where applicable
- **Beta header cleanup**, removing beta headers that the target model doesn't require (for example, `effort-2025-11-24`, `fine-grained-tool-streaming-2025-05-14`, `interleaved-thinking-2025-05-14`) and switching back from `client.beta.messages.create()` to `client.messages.create()`
- **Effort calibration**, recommending an `output_config.effort` starting point for the target model (for example, the default `high` on Claude Opus 5, and `xhigh` for coding and agentic use cases on Claude Opus 4.8 and Claude Opus 4.7)
- **Prompt-behavior tuning**, flagging length-control, tool-triggering, subagent, and instruction-following prompts that may behave differently on the target model
- **Silent default handling**, opting back into thinking summarization (`thinking.display: "summarized"`) when reasoning is surfaced to users on Claude Opus 4.8 and Claude Opus 4.7
- **Refusal fallback configuration**, adding `stop_reason: "refusal"` handling before reading response content and setting up a [fallback retry path](../Guides/build-with-claude-refusals-and-fallback.md) when the target is Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, or Claude Sonnet 5.5 (the server-side `fallbacks` parameter, typically in its `"default"` mode, the SDK refusal-fallback middleware, or a fallback-credit retry), and updating fallback code written against earlier preview shapes
As it edits, the skill explains each change and its motivation inline. On completion, it produces a checklist of items that require manual verification (typically integration tests, length-control prompt tuning, and cost/rate-limit re-baselining).
For the full list of model-specific changes the skill applies, see [Migrating to Claude Opus 5.5 from Claude Opus 5](../../20-Models/models-opus-5-5-migration-guide.md#migrating-from-claude-opus-5), [Migrating to Claude Opus 5.5 from Claude Opus 4.8](../../20-Models/models-opus-5-5-migration-guide.md#migrating-from-claude-opus-4-8), [Migrating to Claude Sonnet 5.5 from Claude Sonnet 5](../../20-Models/models-sonnet-5-5-migration-guide.md#migrating-from-claude-sonnet-5), [Claude Haiku 5.5 migration guide](../../20-Models/models-haiku-5-5-migration-guide.md), and [Claude Fable 5.1 and Claude Mythos 5.1 migration guide](../../20-Models/models-fable-5-1-migration-guide.md).
## Checking an integration for preserved thinking
[Preserved thinking](../Guides/build-with-claude-preserved-thinking.md) keeps a `thinking` block valid only while the `system` prompt, `tools`, and messages before it stay unchanged. To find and fix the places where your code edits that history, open the repository that builds your requests and invoke the `preserved-thinking-migration` subcommand:
Claude Code
Let Claude Code check your code for you
Run in
`❯``/claude-api`` preserved-thinking-migration`
The skill works through five steps:
1. **Scope:** Checks whether your integration is affected, then sends three test requests to confirm that the API reports a deliberate edit.
2. **Find:** Captures a few of your own multi-turn sessions, diffs consecutive requests, and lists each place your code edits the prefix.
3. **Measure:** Replays the sessions with `"drop_block"` and reports which conversations lose `thinking` blocks, at which turn, and why.
4. **Fix:** Replaces one edit at a time with the matching pattern in [Make changes without editing the prefix](../Guides/build-with-claude-preserved-thinking.md#replace-prefix-edits), and measures again after each change.
5. **Report:** Summarizes each cause, the change made for it, and the counts before and after.
If your project has an eval, the skill also compares scores and token usage with and without dropped `thinking` blocks.
The test requests and replays are real Messages API requests, billed at the model's normal rates. Each replay requests only a few output tokens and sets `tool_choice` to `none`, so no tool runs. The skill states the cost and asks for your approval before it sends them.
## Setting up a Managed Agent
To scaffold a new Managed Agent from scratch, invoke the `managed-agents-onboard` subcommand:
Claude Code
Let Claude Code set up your agent for you
Run in
`❯``/claude-api`` managed-agents-onboard`
The skill runs an interview that walks you through the Managed Agents mental model (Agent configs versus Sessions), templates an agent config, configures environments and tools, sets up the session loop, and emits runnable code for your language. The skill also covers the mandatory **Agent (once) → Session (every run)** flow: `model`, `system`, and `tools` live on the agent, never on the session, and agents should be created once and referenced by ID.
Managed Agents requires the `managed-agents-2026-04-01` beta header, which the SDK sets automatically for all `client.beta.agents.*`, `client.beta.environments.*`, `client.beta.sessions.*`, and `client.beta.vaults.*` calls.
## Example usage
Here are examples of tasks the skill helps Claude handle:
**Building a chat application:**
Claude Code
Let Claude Code build this for you
Run in
`❯``Build a streaming chat UI with the Claude API in TypeScript`
**Migrating an existing project:**
Claude Code
Let Claude Code migrate your code for you
Run in
`❯``/claude-api`` migrate this code base to the latest Claude Opus model and re-tune effort`
**Onboarding a new Managed Agent:**
Claude Code
Let Claude Code set up your agent for you
Run in
`❯``/claude-api`` managed-agents-onboard`
In each case, the skill loads the relevant language-specific documentation and guides Claude through the implementation using current API patterns and best practices.
## Next steps
[Agent Skills overview](agents-and-tools-agent-skills-overview.md)
Learn about how Agent Skills work and the progressive disclosure model
[Client SDKs](../Other/cli-sdks-libraries-overview.md)
Browse the official Anthropic SDKs for all supported languages
[Skills repository](https://github.com/anthropics/skills)
Explore the public Anthropic skills repository on GitHub
---
## Skills for enterprise - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise
Path: 04-API-Reference/Agents-Tools/agents-and-tools-agent-skills-enterprise.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fagent-skills%2Fenterprise)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Skills
# Skills for enterprise
Copy page
Governance, security review, evaluation, and organizational guidance for deploying Agent Skills at enterprise scale.
Copy page
This guide is for enterprise admins and architects who need to govern Agent Skills across an organization. It covers how to vet, evaluate, deploy, and manage Skills at scale. For authoring guidance, see [best practices](agents-and-tools-agent-skills-best-practices.md). For architecture details, see the [Skills overview](agents-and-tools-agent-skills-overview.md).
## Security review and vetting
Deploying Skills in an enterprise requires answering two distinct questions:
1. **Are Skills safe in general?** See the [security considerations](agents-and-tools-agent-skills-overview.md#security-considerations) section in the overview for platform-level security details.
2. **How do I vet a specific Skill?** Use the following risk assessment and review checklist.
### Risk tier assessment
Evaluate each Skill against these risk indicators before approving deployment:
| Risk indicator | What to look for | Concern level |
|--------------------------|------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| Code execution | Scripts in the Skill directory (`*.py`, `*.sh`, `*.js`) | High: scripts run with full environment access |
| Instruction manipulation | Directives to ignore safety rules, hide actions from users, or alter Claude's behavior conditionally | High: can bypass security controls |
| MCP server references | Instructions referencing MCP tools (`ServerName:tool_name`) | High: extends access beyond the Skill itself |
| Network access patterns | URLs, API endpoints, `fetch`, `curl`, or `requests` calls | High: potential data exfiltration vector |
| Hardcoded credentials | API keys, tokens, or passwords in Skill files or scripts | High: secrets exposed in Git history and context window |
| Filesystem access scope | Paths outside the Skill directory, broad glob patterns, path traversal (`../`) | Medium: may access unintended data |
| Tool invocations | Instructions directing Claude to use bash, file operations, or other tools | Medium: review what operations are performed |
### Review checklist
Before deploying any Skill from a third party or internal contributor, complete these steps:
1. **Read all Skill directory content.** Review SKILL.md, all referenced markdown files, and any bundled scripts or resources.
2. **Verify script behavior matches stated purpose.** Run scripts in a sandboxed environment and confirm outputs align with the Skill's description.
3. **Check for adversarial instructions.** Look for directives that tell Claude to ignore safety rules, hide actions from users, exfiltrate data through responses, or alter behavior based on specific inputs.
4. **Check for external URL fetches or network calls.** Search scripts and instructions for network access patterns (`http`, `requests.get`, `urllib`, `curl`, `fetch`).
5. **Verify no hardcoded credentials.** Check for API keys, tokens, or passwords in Skill files. Credentials should use environment variables or secure credential stores, never appear in Skill content.
6. **Identify tools and commands the Skill instructs Claude to invoke.** List all bash commands, file operations, and tool references. Consider the combined risk when a Skill uses both file-read and network tools together.
7. **Confirm redirect destinations.** If the Skill references external URLs, verify they point to expected domains.
8. **Verify no data exfiltration patterns.** Look for instructions that read sensitive data and then write, send, or encode it for external transmission, including through Claude's conversational responses.
Never deploy Skills from untrusted sources without a full audit. A malicious Skill can direct Claude to execute arbitrary code, access sensitive files, or transmit data externally. Treat Skill installation with the same rigor as installing software on production systems.
### Skill content scanning
Claude Enterprise organizations can turn on automated security scanning for custom Skills in claude.ai and Claude Cowork. After you turn on **Skill and plugin security scanning** at [claude.ai \> Organization settings \> Skills](https://claude.ai/admin-settings/skills), Skills that members then upload or edit in claude.ai or Cowork are scanned for signs of malicious behavior, such as hidden code execution, sending your data to an outside service, or instructions that tamper with Claude's safeguards. A Skill that fails the scan, or whose scan hasn't finished, is blocked from use. A Skill that passes with a warning stays usable behind a caution notice. If scanning is available to your organization, turn it on. It complements, but doesn't replace, the [review checklist](#review-checklist).
Scanning doesn't cover the Claude API. Skills you upload through the Skills API (`/v1/skills`), including from the Claude Console, aren't scanned, so for API deployments, rely on the review checklist and [version pinning](#versioning-strategy). Scanning also doesn't apply to Skills that were already in your organization when you turned it on, or to organizations with certain data handling configurations, such as customer-managed encryption keys (CMEK), zero data retention (ZDR), or HIPAA readiness. For setup steps, exclusions, and result types, see [Get started with skill and plugin scanning](../../15-Claude-AI-Features/get-started-with-skill-and-plugin-scanning.md) in the Claude Help Center.
## Evaluating Skills before deployment
Skills can degrade agent performance if they trigger incorrectly, conflict with other Skills, or provide poor instructions. Require evaluation before any production deployment.
### What to evaluate
Establish approval gates for these dimensions before deploying any Skill:
| Dimension | What it measures | Example failure |
|-----------------------|-------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| Triggering accuracy | Does the Skill activate for the right queries and stay inactive for unrelated ones? | Skill triggers on every spreadsheet mention, even when the user just wants to discuss data |
| Isolation behavior | Does the Skill work correctly on its own? | Skill references files that don't exist in its directory |
| Coexistence | Does adding this Skill degrade other Skills? | New Skill's description is too broad, stealing triggers from existing Skills |
| Instruction following | Does Claude follow the Skill's instructions accurately? | Claude skips validation steps or uses wrong libraries |
| Output quality | Does the Skill produce correct, useful results? | Generated reports have formatting errors or missing data |
### Evaluation requirements
Require Skill authors to submit evaluation suites with 3–5 representative queries per Skill, covering cases where the Skill should trigger, should not trigger, and ambiguous edge cases. Require testing across the models your organization uses (Haiku, Sonnet, Opus), because Skill effectiveness varies by model.
For detailed guidance on building evaluations, see [evaluation and iteration](agents-and-tools-agent-skills-best-practices.md#evaluation-and-iteration) in best practices. For general evaluation methodology, see [develop test cases](../Test-Evaluate/test-and-evaluate-develop-tests.md).
### Using evaluations for lifecycle decisions
Evaluation results signal when to act:
- **Declining trigger accuracy:** Update the Skill's description or instructions
- **Coexistence conflicts:** Consolidate overlapping Skills or narrow descriptions
- **Consistently low output quality:** Rewrite instructions or add validation steps
- **Persistent failures across updates:** Deprecate the Skill
## Skill lifecycle management
1. 1
### Plan
Identify workflows that are repetitive, error-prone, or require specialized knowledge. Map these to organizational roles and determine which are candidates for Skills.
2. 2
### Create and review
Ensure the Skill author follows [best practices](agents-and-tools-agent-skills-best-practices.md). Require a security review using the [review checklist](#review-checklist). Require an evaluation suite before approval. Establish separation of duties: Skill authors should not be their own reviewers.
3. 3
### Test
Require evaluations in isolation (Skill alone) and alongside existing Skills (coexistence testing). Verify triggering accuracy, output quality, and absence of regressions across your active Skill set before approving for production.
4. 4
### Deploy
Upload through the Skills API for workspace-wide access. See [Using Skills with the API](../Guides/build-with-claude-skills-guide.md) for upload and version management. Document the Skill in your internal registry with purpose, owner, and version.
5. 5
### Monitor
Track usage patterns and collect feedback from users. Rerun evaluations periodically to detect drift or regressions as workflows and models evolve. Usage analytics are not currently available through the Skills API. Implement application-level logging to track which Skills are included in requests.
6. 6
### Iterate or deprecate
Require the full evaluation suite to pass before promoting new versions. Update Skills when workflows change or evaluation scores decline. Deprecate Skills when evaluations consistently fail or the workflow is retired.
## Organizing Skills at scale
### Recall limits
As a general guideline, limit the number of Skills loaded simultaneously to maintain reliable recall accuracy. Each Skill's metadata (name and description) competes for attention in the system prompt. With too many Skills active, Claude may fail to select the right Skill or miss relevant ones entirely. Use your evaluation suite to measure recall accuracy as you add Skills, and stop adding when performance degrades.
Note that API requests support a maximum of 20 Skills for each request (see [Using Skills with the API](../Guides/build-with-claude-skills-guide.md)). If a role requires more Skills than a single request supports, consider consolidating narrow Skills into broader ones or routing requests to different Skill sets based on task type.
### Start specific, consolidate later
Encourage teams to start with narrow, workflow-specific Skills rather than broad, multipurpose ones. As patterns emerge across your organization, consolidate related Skills into role-based bundles.
Use evaluations to decide when to consolidate. Merge narrow Skills into a broader one only when the consolidated Skill's evaluations confirm equivalent performance to the individual Skills it replaces.
**Example progression:**
- Start: `formatting-sales-reports`, `querying-pipeline-data`, `updating-crm-records`
- Consolidate: `sales-operations` (when evals confirm equivalent performance)
### Naming and cataloging
Use consistent naming conventions across your organization. The [naming conventions](agents-and-tools-agent-skills-best-practices.md#naming-conventions) section in best practices provides formatting guidance.
Maintain an internal registry for each Skill with:
- **Purpose:** What workflow the Skill supports
- **Owner:** Team or individual responsible for maintenance
- **Version:** Current deployed version
- **Dependencies:** MCP servers, packages, or external services required
- **Evaluation status:** Last evaluation date and results
### Role-based bundles
Group Skills by organizational role to keep each user's active Skill set focused:
- **Sales team:** CRM operations, pipeline reporting, proposal generation
- **Engineering:** Code review, deployment workflows, incident response
- **Finance:** Report generation, data validation, audit preparation
Each role-based bundle should contain only the Skills relevant to that role's daily workflows.
## Distribution and version control
### Source control
Store Skill directories in Git for history tracking, code review through pull requests, and rollback capability. Each Skill directory (containing SKILL.md and any bundled files) maps naturally to a Git-tracked folder.
### API-based distribution
The Skills API provides workspace-scoped distribution. Skills uploaded through the API are available to all workspace members. See [Using Skills with the API](../Guides/build-with-claude-skills-guide.md) for upload, versioning, and management endpoints.
### Versioning strategy
- **Production:** Pin Skills to specific versions. If you omit `version`, requests use the latest version, so a new version uploaded by anyone in the workspace immediately changes what production agents run. Run the full evaluation suite before promoting a new version. Treat every update as a new deployment requiring full security review.
- **Development and testing:** Use latest versions to validate changes before production promotion.
- **Rollback plan:** Maintain the previous version as a fallback. If a new version fails evaluations in production, revert to the last known-good version immediately.
- **Integrity verification:** Compute checksums of reviewed Skills and verify them at deployment time. Use signed commits in your Skill repository to ensure provenance.
### Cross-surface considerations
Custom Skills do not sync across surfaces. Skills uploaded to the API are not available on claude.ai or in Claude Code, and vice versa. Each surface requires separate uploads and management.
Maintain Skill source files in Git as the single source of truth. If your organization deploys Skills across multiple surfaces, implement your own synchronization process to keep them consistent. For full details, see [cross-surface availability](agents-and-tools-agent-skills-overview.md#cross-surface-availability).
## Next steps
[Agent Skills overview](agents-and-tools-agent-skills-overview.md)
Architecture and platform details
[Best practices](agents-and-tools-agent-skills-best-practices.md)
Authoring guidance for Skill creators
[Using Skills with the API](../Guides/build-with-claude-skills-guide.md)
Upload and manage Skills programmatically
---
## Agent Skills - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
Path: 04-API-Reference/Agents-Tools/agents-and-tools-agent-skills-overview.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fagent-skills%2Foverview)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Skills
# Agent Skills
Copy page
Agent Skills are modular capabilities that extend Claude's functionality. Each Skill packages instructions, metadata, and optional resources (scripts, templates) that Claude uses automatically when relevant.
Copy page
To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
## Why use Skills
Skills are reusable, filesystem-based resources that give Claude domain-specific expertise: workflows, context, and best practices that turn a general-purpose agent into a specialist. Unlike prompts (conversation-level instructions for one-off tasks), Skills load on demand, so you don't have to repeat the same guidance across conversations.
**Key benefits:**
- **Specialize Claude:** Tailor capabilities for domain-specific tasks
- **Reduce repetition:** Create once, use automatically
- **Compose capabilities:** Combine Skills for complex, multistep tasks
For more on the architecture and real-world applications of Agent Skills, see the engineering blog post [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
## Using Skills
Anthropic provides pre-built Agent Skills for common document tasks (PowerPoint, Excel, Word, PDF), and you can create your own custom Skills. Both work the same way: once a Skill is available in your environment, Claude uses it automatically when relevant to your request.
**Pre-built Agent Skills** are available on claude.ai, the Claude API, [Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md), and [Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md). On Microsoft Foundry, Agent Skills require a [Hosted on Anthropic deployment](../Guides/build-with-claude-claude-in-microsoft-foundry.md#additional-features-not-supported-when-hosted-on-azure). See [Available Skills](#available-skills) for the complete list.
**Custom Skills** let you package domain expertise and organizational knowledge. They're available across Claude's products: create them in Claude Code, upload them through the Claude API, or add them in claude.ai settings. On [Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md) and [Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md), upload custom Skills through the Skills API.
**Get started:**
- For pre-built Agent Skills: See the [quickstart tutorial](agents-and-tools-agent-skills-quickstart.md) to start using PowerPoint, Excel, Word, and PDF Skills in the API
- For custom Skills: See the [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction) to learn how to create your own Skills
## How Skills work
Skills use Claude's VM environment to provide capabilities beyond what's possible with prompts alone. Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials, organized like an onboarding guide you'd create for a new team member.
This filesystem-based architecture enables **progressive disclosure:** Claude loads information in stages as needed, rather than consuming context upfront.
Skills can contain three types of content, each loaded at a different time:
### Level 1: Metadata (always loaded)
The Skill's YAML frontmatter provides discovery information:
```python
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
```
Claude loads this metadata at startup and includes it in the system prompt. The `description` is what Claude matches your request against when determining whether to trigger the Skill, so it must say both what the Skill does and when to use it. This lightweight approach means you can install many Skills without context penalty: until a Skill is triggered, only its name and description occupy context.
### Level 2: Instructions (loaded when triggered)
The main body of SKILL.md contains procedural knowledge: workflows, best practices, and guidance:
```` shiki
# PDF Processing
## Quick start
Use pdfplumber to extract text from PDFs:
```python
import pdfplumber
with pdfplumber.open("document.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
For advanced form filling, see [FORMS.md](FORMS.md).
````
When you request something that matches a Skill's description, Claude reads SKILL.md from the filesystem using bash. Only then does this content enter the context window.
### Level 3: Resources and code (loaded as needed)
Skills can bundle additional materials:
- `pdf-processing/`
- `SKILL.md` (main instructions)
- `FORMS.md` (form-filling guide)
- `REFERENCE.md` (detailed API reference)
- `scripts/`
- `fill_form.py` (utility script)
**Instructions:** Additional markdown files (FORMS.md, REFERENCE.md) containing specialized guidance and workflows
**Code:** Executable scripts (fill_form.py, validate.py) that Claude runs using bash, providing deterministic operations without loading their code into context
**Resources:** Reference materials such as database schemas, API documentation, templates, or examples
Claude accesses these files only when referenced. The filesystem model means each content type has different strengths: instructions for flexible guidance, code for reliability, resources for factual lookup.
| Level | When loaded | Token cost | Content |
|---------------------------|-------------------------|-----------------------|----------------------------------------------------------------------------------------------------------------------------|
| **Level 1: Metadata** | Always (at startup) | ~100 tokens per Skill | `name` and `description` from YAML frontmatter |
| **Level 2: Instructions** | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
| **Level 3+: Resources** | As needed | None until accessed | Bundled files. Reference files load into context when read. Scripts run through bash, and only their output enters context |
Progressive disclosure ensures only relevant content occupies the context window at any given time.
### The Skills architecture
Skills run in a code execution environment where Claude has filesystem access, bash commands, and code execution capabilities. Skills exist as directories on a virtual machine, and Claude interacts with them using the same bash commands you'd use to navigate files on your computer.
**How Claude accesses Skill content:**
When a Skill is triggered, Claude uses bash to read SKILL.md from the filesystem, bringing its instructions into the context window. If those instructions reference other files (such as FORMS.md or a database schema), Claude reads those files too using additional bash commands. When instructions mention executable scripts, Claude runs them through bash and receives only the output (the script code itself never enters context).
**What this architecture enables:**
- **On-demand file access:** Claude reads only the files each task needs. A Skill can include dozens of reference files, but if your task only needs the sales schema, that's the one file Claude loads. The rest stay on the filesystem and cost zero tokens.
- **Efficient script execution:** When Claude runs `validate_form.py`, the script's code never loads into the context window. Only its output (such as "Validation passed" or a specific error message) consumes tokens, which makes scripts far more efficient than having Claude generate equivalent code on the fly.
- **No practical limit on bundled content:** Files don't consume context until accessed, so Skills can include comprehensive API documentation, large datasets, or extensive examples. There's no context penalty for bundled content that isn't used.
### Example: Loading a PDF processing Skill
Here's how Claude loads and uses the custom `pdf-processing` Skill from the earlier examples (not the pre-built `pdf` Skill):
1. **Startup:** System prompt includes: `pdf-processing - Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.`
2. **User request:** "Extract the text from this PDF and summarize it"
3. **Claude invokes:** `bash: cat pdf-processing/SKILL.md` → Instructions loaded into context
4. **Claude determines:** Form filling is not needed, so FORMS.md is not read
5. **Claude executes:** Uses instructions from SKILL.md to complete the task
## Where Skills work
Skills are available across Claude's agent products:
Claude Platform on AWS and Microsoft Foundry inherit the same Skills behavior as the Claude API in all following sections, except where [Limitations and constraints](#limitations-and-constraints) says otherwise.
### Claude API
The Claude API supports both pre-built Agent Skills and custom Skills. Both work identically: specify the relevant `skill_id` in the `container` parameter along with the [code execution tool](agents-and-tools-tool-use-code-execution-tool.md).
**Prerequisites:** Using Skills through the API requires the [code execution tool](agents-and-tools-tool-use-code-execution-tool.md), whose container Skills run in.
Use pre-built Agent Skills by referencing their `skill_id` (`pptx`, `xlsx`, `docx`, or `pdf`), or create and upload your own through the Skills API (`/v1/skills` endpoints). Custom Skills are shared workspace-wide: all workspace members can access them.
Skills on the API run in a sandboxed container with no network access and no runtime package installation. See [Limitations and constraints](#limitations-and-constraints) for details.
To learn more, see [Using Agent Skills with the API](../Guides/build-with-claude-skills-guide.md).
### Claude Code
[Claude Code](../../02-Claude-Code-CLI/code-home.md) supports custom Skills. The pre-built document Skills (PowerPoint, Excel, Word, PDF) are not available in Claude Code, though the open-source [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md) comes bundled with it. See the full list of [built-in commands and Skills](../../02-Claude-Code-CLI/commands.md) that ship with Claude Code.
**Custom Skills:** Create Skills as directories with SKILL.md files. Claude discovers and uses them automatically.
Custom Skills in Claude Code are filesystem-based and don't require API uploads: place them in `~/.claude/skills/` (personal) or `.claude/skills/` (project).
To learn more, see [Use Skills in Claude Code](../../08-Plugins-Skills/skills.md).
### claude.ai
[claude.ai](https://claude.ai) supports both pre-built Agent Skills and custom Skills.
**Pre-built Agent Skills:** These Skills are active when you create documents. Claude uses them with no setup required.
**Custom Skills:** Upload your own Skills as zip files through Settings \> Features. Available on Pro, Max, Team, and Enterprise plans with [code execution enabled](../../15-Claude-AI-Features/create-and-edit-files-with-claude.md). Custom Skills are individual to each user. They are not shared organization-wide and cannot be centrally managed by admins.
To learn more about using Skills in claude.ai, see the following resources in the Claude Help Center:
- [What are Skills?](../../02-Claude-Code-CLI/what-are-skills.md)
- [Using Skills in Claude](../../02-Claude-Code-CLI/using-skills-in-claude.md)
- [How to create custom Skills](https://support.claude.com/en/articles/12512198-creating-custom-skills)
- [Teach Claude your way of working using Skills](../../15-Claude-AI-Features/teach-claude-your-way-of-working-using-skills.md)
## Skill structure
Every Skill requires a `SKILL.md` file with YAML frontmatter:
```python
---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
---
# Your Skill Name
## Instructions
[Clear, step-by-step guidance for Claude to follow]
## Examples
[Concrete examples of using this Skill]
```
**Required fields:** `name` and `description`
**Field requirements:**
`name`:
- Maximum 64 characters
- Must contain only lowercase letters, numbers, and hyphens
- Cannot contain XML tags
- Cannot contain reserved words: "anthropic", "claude"
`description`:
- Must be non-empty
- Maximum 1024 characters
- Cannot contain XML tags
The `description` must include both what the Skill does and when Claude should use it. For complete authoring guidance, see [Skill authoring best practices](agents-and-tools-agent-skills-best-practices.md).
## Security considerations
Use Skills only from trusted sources: those you created yourself or obtained from Anthropic. Skills give Claude new capabilities through instructions and code, which also means a malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose.
If you must use a Skill from an untrusted or unknown source, exercise extreme caution and thoroughly audit it before use. Depending on what access Claude has when executing the Skill, malicious Skills could lead to data exfiltration, unauthorized system access, or other security risks.
**Key security considerations:**
- **Audit thoroughly:** Review all files bundled in the Skill: SKILL.md, scripts, images, and other resources. Look for unusual patterns such as unexpected network calls, file access patterns, or operations that don't match the Skill's stated purpose
- **External sources are risky:** Skills that fetch data from external URLs pose particular risk, as fetched content may contain malicious instructions. Even trustworthy Skills can be compromised if their external dependencies change over time
- **Tool misuse:** Malicious Skills can invoke tools (file operations, bash commands, code execution) in harmful ways
- **Data exposure:** Skills with access to sensitive data could be designed to leak information to external systems
- **Treat like installing software:** Be especially careful when integrating Skills into production systems with access to sensitive data or critical operations
For organization-scale governance, vetting, and deployment guidance, see [Skills for enterprise](agents-and-tools-agent-skills-enterprise.md). Claude Enterprise organizations can also turn on [Skill content scanning](agents-and-tools-agent-skills-enterprise.md#skill-content-scanning) for custom Skills uploaded in claude.ai and Claude Cowork. Scanning doesn't cover Skills uploaded through the Skills API or the Claude Console.
## Available Skills
### Pre-built Agent Skills
The following pre-built Agent Skills are available for immediate use:
- **PowerPoint (pptx):** Create presentations, edit slides, analyze presentation content
- **Excel (xlsx):** Create spreadsheets, analyze data, generate reports with charts
- **Word (docx):** Create documents, edit content, format text
- **PDF (pdf):** Generate formatted PDF documents and reports
These Skills are available on the Claude API, [Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md), [Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md), and claude.ai. See the [quickstart tutorial](agents-and-tools-agent-skills-quickstart.md) to start using them in the API.
### Open-source Skills
Anthropic also publishes open-source Skills in the [skills repository](https://github.com/anthropics/skills):
- **[Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md):** Provides Claude with up-to-date API reference material, SDK documentation, and best practices for eight programming languages. Bundled with Claude Code and also available for installation from the skills repository.
### Custom Skills examples
For complete examples of custom Skills, see the [Skills cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction).
## Data retention
Agent Skills is not covered by ZDR arrangements. Skill definitions and execution data are retained according to Anthropic's standard data retention policy.
For ZDR eligibility across all features, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
For audit logging of Skills API operations, see [Audit logging](../Guides/build-with-claude-skills-guide.md#audit-logging) in Using Agent Skills with the API.
## Limitations and constraints
Claude Platform on AWS and Microsoft Foundry follow the same limitations as the Claude API in the following subsections. In addition, on Microsoft Foundry, the [Skill version download endpoint](../Endpoints/beta-skills-versions-download.md) (`GET /v1/skills/{skill_id}/versions/{version}/content`) is not supported.
### Cross-surface availability
**Custom Skills do not sync across surfaces**. Skills uploaded to one surface are not automatically available on others:
- Skills uploaded to claude.ai must be separately uploaded to the API
- Skills uploaded through the API are not available on claude.ai
- Claude Code Skills are filesystem-based and separate from both claude.ai and API
Manage and upload Skills separately for each surface where you want to use them.
### Sharing scope
Skills have different sharing models depending on where you use them:
- **claude.ai:** Individual user only. Each team member must upload separately.
- **Claude API:** Workspace-wide. All workspace members can access uploaded Skills.
- **Claude Code:** Personal (`~/.claude/skills/`) or project-based (`.claude/skills/`). Can also be shared through Claude Code Plugins.
claude.ai does not support centralized admin management or org-wide distribution of custom Skills.
### Runtime environment constraints
The exact runtime environment available to your Skill depends on the product surface where you use it.
- **claude.ai:**
- **Varying network access:** Depending on user/admin settings, Skills may have full, partial, or no network access. For more details, see the [Create and Edit Files](../../15-Claude-AI-Features/create-and-edit-files-with-claude.md#h_6b7e833898) support article.
- **Claude API:**
- **No network access:** Skills cannot make external API calls or access the internet.
- **No runtime package installation:** Only pre-installed packages are available. You cannot install new packages during execution.
- **Pre-configured dependencies only:** Check the [Code execution tool](agents-and-tools-tool-use-code-execution-tool.md) documentation for the list of available packages.
- **Claude Code:**
- **Full network access:** Skills have the same network access as any other program on the user's computer.
- **Global package installation discouraged:** Skills should only install packages locally to avoid interfering with the user's computer.
Plan your Skills to work within these constraints.
## Next steps
[Get started with Agent Skills in the API](agents-and-tools-agent-skills-quickstart.md)
Learn how to use Agent Skills to create documents with the Claude API in under 10 minutes.
[Using Agent Skills with the API](../Guides/build-with-claude-skills-guide.md)
Learn how to use Agent Skills to extend Claude's capabilities through the API.
[Use Skills in Claude Code](../../08-Plugins-Skills/skills.md)
Create and manage custom Skills in Claude Code.
[Skill authoring best practices](agents-and-tools-agent-skills-best-practices.md)
Learn how to write effective Skills that Claude can discover and use successfully.
---
## Get started with Agent Skills in the API - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart
Path: 04-API-Reference/Agents-Tools/agents-and-tools-agent-skills-quickstart.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fagent-skills%2Fquickstart)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Skills
# Get started with Agent Skills in the API
Copy page
Learn how to use Agent Skills to create documents with the Claude API in under 10 minutes.
Copy page
This tutorial shows you how to use Agent Skills to create a PowerPoint presentation. You'll learn how to enable Skills, make a request, and access the generated file.
## Prerequisites
- A [Claude API key](../Other/playground.md) from the Claude Console, or a logged-in [ant CLI](../Other/cli-sdks-libraries-cli-authentication.md)
- A [client SDK](../Other/cli-sdks-libraries-overview.md) for your language, or `curl` and `jq`
- Basic familiarity with making API requests
## Agent Skills overview
Pre-built Agent Skills extend Claude's capabilities with specialized expertise for tasks such as creating documents, analyzing data, and processing files. Anthropic provides the following pre-built Agent Skills in the API:
- **PowerPoint (pptx):** Create and edit presentations
- **Excel (xlsx):** Create and analyze spreadsheets
- **Word (docx):** Create and edit documents
- **PDF (pdf):** Generate PDF documents
To create custom Skills, see the [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction) for examples of building your own Skills with domain-specific expertise.
## Step 1: List available Skills
First, check what Skills are available. Use the Skills API to list all Anthropic-managed Skills. Each language tab is an excerpt from one continuous script, with any imports and client setup at the top:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
# List Anthropic-managed Skills
skills = client.skills.list(source="anthropic")
for skill in skills.data:
print(f"{skill.id}: {skill.display_name}")
```
You see the following Skills: `pptx`, `xlsx`, `docx`, and `pdf`.
This API returns each Skill's metadata: its name and description. Claude loads this metadata at startup to determine which Skills are available. This is the first level of **progressive disclosure**, where Claude discovers Skills without loading their full instructions yet.
## Step 2: Create a presentation
Use the PowerPoint Skill to create a presentation about renewable energy. Specify Skills using the `container` parameter in the Messages API:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
# Create a message with the PowerPoint Skill
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
container={
"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Create a presentation about renewable energy with 5 slides",
}
],
tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
)
print(f"stop_reason={response.stop_reason}, blocks={len(response.content)}")
```
The request includes the following parts:
- **`model`:** A [model that supports the code execution tool](agents-and-tools-tool-use-code-execution-tool.md#compatibility)
- **`container.skills`:** Specifies which Skills Claude can use
- **`type: "anthropic"`:** Indicates this is an Anthropic-managed Skill
- **`skill_id: "pptx"`:** The PowerPoint Skill identifier
- **`version: "latest"`:** The Skill version set to the most recently published
- **`tools`:** Enables code execution (required for Skills)
The examples use the `code_execution_20260521` tool version, and the Step 3 code parses the result types that current tool versions return. Skills also work with older [code execution tool](agents-and-tools-tool-use-code-execution-tool.md) versions such as `code_execution_20250825`: any current code execution tool version satisfies the Skills requirement. If you use a different version, use the tool `type` listed on the code execution tool page.
When you make this request, Claude automatically matches your task to the relevant Skill. Because you asked for a presentation, Claude determines the PowerPoint Skill is relevant and loads its full instructions: the second level of progressive disclosure. Then Claude runs the Skill's code to create your presentation.
## Step 3: Download the created file
The presentation was created in the code execution container and saved as a file. The Step 2 `response` includes a file reference with a file ID. Extract the file ID and download the file with the Files API. The example saves it to your system temp directory:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
# Extract the file ID. The code execution tool runs the Skill's code through
# its Bash sub-tool, and generated files appear as bash_code_execution_output
# items inside the bash_code_execution_tool_result block.
file_id = None
for block in response.content:
if block.type == "bash_code_execution_tool_result":
if block.content.type == "bash_code_execution_result":
for output in block.content.content:
file_id = output.file_id
if file_id:
# Download the file and save it
output_path = Path(tempfile.gettempdir()) / "renewable_energy.pptx"
file_content = client.files.download(file_id=file_id)
file_content.write_to_file(output_path)
print(f"Presentation saved to {output_path}")
```
For complete details on working with generated files, see [Retrieve generated files](agents-and-tools-tool-use-code-execution-tool.md#retrieve-generated-files) in the code execution tool documentation.
## Try more examples
Try these variations:
### Create a spreadsheet
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Create a quarterly sales tracking spreadsheet with sample data",
}
],
tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
)
```
### Create a Word document
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
container={
"skills": [{"type": "anthropic", "skill_id": "docx", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Write a 2-page report on the benefits of renewable energy",
}
],
tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
)
```
### Generate a PDF
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
container={
"skills": [{"type": "anthropic", "skill_id": "pdf", "version": "latest"}]
},
messages=[
{
"role": "user",
"content": "Generate a PDF invoice template",
}
],
tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
)
```
## Next steps
[Skill authoring best practices](agents-and-tools-agent-skills-best-practices.md)
Learn how to write effective Skills that Claude can discover and use successfully.
[Using Agent Skills with the API](../Guides/build-with-claude-skills-guide.md)
Learn how to use Agent Skills to extend Claude's capabilities through the API.
[Create custom Skills](../Endpoints/skills-create.md)
Upload your own Skills for specialized tasks.
[Use Skills in Claude Code](../../08-Plugins-Skills/skills.md)
Learn about Skills in Claude Code.
[Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction)
Explore example Skills and implementation patterns.
---
## Not Found - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/how-tool-use-works
Path: 04-API-Reference/Agents-Tools/agents-and-tools-how-tool-use-works.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [CLI, SDKs, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fhow-tool-use-works)
# Page not found
The requested page could not be found.
---
## MCP connector - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/mcp-connector
Path: 04-API-Reference/Agents-Tools/agents-and-tools-mcp-connector.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-connector)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)MCP
MCP connector
[Beta](../Guides/build-with-claude-overview.md#feature-availability)
[Beta header](../Endpoints/beta-headers.md)
mcp-client-2025-11-20
[ZDR](../Other/manage-claude-api-and-data-retention.md)
Not eligible
# MCP connector
Copy page
Connect to remote MCP servers directly from the Messages API without an MCP client, and allowlist, denylist, or configure individual tools.
Copy page
Claude's Model Context Protocol (MCP) connector feature enables you to connect to remote MCP servers directly from the Messages API without a separate MCP client.
The previous version of this feature (`mcp-client-2025-04-04`) is deprecated. See [Deprecated version: mcp-client-2025-04-04](#deprecated-version-mcp-client-2025-04-04).
## Key features
- **Direct API integration:** Connect to MCP servers without implementing an MCP client
- **Tool calling support:** Access MCP tools through the Messages API
- **Flexible tool configuration:** Enable all tools, allowlist specific tools, or denylist unwanted tools
- **Per-tool configuration:** Configure individual tools with custom settings
- **OAuth authentication:** Support for OAuth Bearer tokens for authenticated servers
- **Multiple servers:** Connect to multiple MCP servers in a single request
## When Claude uses MCP tools
Once an MCP server is connected, Claude calls its tools when the user's request maps to a tool's described capability, either explicitly ("search Jira for open bugs") or implicitly ("what's blocking the release?" with a Jira server attached).
Claude does **not** call an MCP tool for general knowledge questions about a connected service. Asking "how do Notion databases work?" with a Notion server attached is answered directly; asking "what's in my Projects database?" triggers the tool.
You can steer how readily Claude calls MCP tools through your system prompt. See [When Claude uses tools](agents-and-tools-tool-use-overview.md#when-claude-uses-tools) for general guidance and example phrasings.
## Limitations
- Of the feature set of the [MCP specification](https://modelcontextprotocol.io/introduction#explore-mcp), only [tool calls](https://modelcontextprotocol.io/docs/concepts/tools) are currently supported.
- The server must be publicly exposed through HTTP (supports both Streamable HTTP and SSE transports). Local STDIO servers cannot be connected directly.
## Using the MCP connector in the Messages API
The MCP connector uses two components:
1. **MCP server definition** (`mcp_servers` array): Defines server connection details (URL, authentication)
2. **MCP toolset** (`tools` array): Configures which tools to enable and how to configure them
### Basic example
This example enables all tools from an MCP server with default configuration:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1000,
messages=[{"role": "user", "content": "What tools do you have available?"}],
mcp_servers=[
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
}
],
tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
betas=["mcp-client-2025-11-20"],
)
print(response)
```
## MCP server configuration
Each MCP server in the `mcp_servers` array defines the connection details:
```python
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
```
### Field descriptions
| Property | Type | Required | Description |
|-----------------------|--------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `type` | string | Yes | Currently only "url" is supported. |
| `url` | string | Yes | The URL of the MCP server. Must start with https://. |
| `name` | string | Yes | A unique identifier for this MCP server. Must be referenced by exactly one MCPToolset in the `tools` array. |
| `authorization_token` | string | No | OAuth authorization token if required by the MCP server. See [Authentication](#authentication) for how to obtain one, or the [MCP specification](../../06-MCP-Tools/Spec-Archive/2025-11-25-basic-authorization.md) for protocol details. |
## MCP toolset configuration
The MCPToolset lives in the `tools` array and configures which tools from the MCP server are enabled and how they should be configured.
### Basic structure
```python
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"default_config": {
"enabled": true,
"defer_loading": false
},
"configs": {
"specific_tool_name": {
"enabled": true,
"defer_loading": true
}
}
}
```
### Field descriptions
| Property | Type | Required | Description |
|-------------------|--------|----------|-----------------------------------------------------------------------------------------------------------------------|
| `type` | string | Yes | Must be "mcp_toolset". |
| `mcp_server_name` | string | Yes | Must match a server name defined in the `mcp_servers` array. |
| `default_config` | object | No | Default configuration applied to all tools in this set. Individual tool configs in `configs` override these defaults. |
| `configs` | object | No | Per-tool configuration overrides. Keys are tool names, values are configuration objects. |
| `cache_control` | object | No | [Prompt caching](../Guides/build-with-claude-prompt-caching.md) cache breakpoint configuration for this toolset. |
With the `mcp-client-2026-09-15` beta header, an MCPToolset also accepts `tools`, a pinned copy of the server's tool list. See [Pin an MCP server's tool list](#pin-mcp-tool-list).
### Tool configuration options
Each tool (whether configured in `default_config` or in `configs`) supports the following fields:
| Property | Type | Default | Description |
|-----------------|---------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| `enabled` | boolean | `true` | Whether this tool is enabled. |
| `defer_loading` | boolean | `false` | If true, tool description is not sent to the model initially. Used with [Tool search tool](agents-and-tools-tool-use-tool-search-tool.md). |
For the full directory of Anthropic-provided tools and optional properties such as `defer_loading`, see the [Tool reference](agents-and-tools-tool-use-tool-reference.md). To search across large tool sets, see [Tool search tool](agents-and-tools-tool-use-tool-search-tool.md).
### Configuration merging
Configuration values merge with this precedence (highest to lowest):
1. Tool-specific settings in `configs`
2. Set-level `default_config`
3. System defaults
Example:
```python
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": false
}
}
}
```
Results in:
- `search_events`: `enabled: false` (from configs), `defer_loading: true` (from default_config)
- All other tools: `enabled: true` (system default), `defer_loading: true` (from default_config)
## Common configuration patterns
### Enable all tools with default configuration
The simplest pattern: enable all tools from a server:
```python
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp"
}
```
### Allowlist: enable only specific tools
Set `enabled: false` as the default, then explicitly enable specific tools:
```python
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false
},
"configs": {
"search_events": {
"enabled": true
},
"create_event": {
"enabled": true
}
}
}
```
### Denylist: disable specific tools
Enable all tools by default, then explicitly disable unwanted tools. Denylisting write or destructive tools is recommended when building read-only assistants, or when you want a human confirmation step before state changes:
```python
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"configs": {
"delete_all_events": {
"enabled": false
},
"share_calendar_publicly": {
"enabled": false
}
}
}
```
### Mixed: allowlist with per-tool configuration
Combine allowlisting with custom configuration for each tool:
```python
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false,
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": true,
"defer_loading": false
},
"list_events": {
"enabled": true
}
}
}
```
In this example:
- `search_events` is enabled with `defer_loading: false`
- `list_events` is enabled with `defer_loading: true` (inherited from default_config)
- All other tools are disabled
## Validation rules
The API enforces these validation rules:
- **Server must exist:** The `mcp_server_name` in an MCPToolset must match a server defined in the `mcp_servers` array
- **Server must be used:** Every MCP server defined in `mcp_servers` must be referenced by exactly one MCPToolset
- **Unique toolset per server:** Each MCP server can only be referenced by one MCPToolset
- **Unknown tool names:** If a tool name in `configs` doesn't exist on the MCP server, a backend warning is logged but no error is returned (MCP servers may have dynamic tool availability)
## Response content types
When Claude uses MCP tools, the response includes two new content block types:
### MCP tool use block
```python
{
"type": "mcp_tool_use",
"id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"name": "echo",
"server_name": "example-mcp",
"input": { "param1": "value1", "param2": "value2" }
}
```
### MCP tool result block
```python
{
"type": "mcp_tool_result",
"tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"is_error": false,
"content": [
{
"type": "text",
"text": "Hello"
}
]
}
```
## Pin an MCP server's tool list (beta)
An MCP server can change its tools at any time. The `mcp-client-2026-09-15` beta header records the tool list each server returns and lets you pin it, so a server that changes its tools doesn't change what Claude sees partway through a conversation. It includes everything `mcp-client-2025-11-20` does, so send it in place of that header. It's available on the Claude API.
When the API asks an MCP server for its tools while producing a response, the response starts with an `mcp_tool_listing` block for that server, one block for each server it asked:
```python
{
"type": "mcp_tool_listing",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": "echo",
"description": "Returns the text it receives.",
"input_schema": {
"type": "object",
"properties": { "text": { "type": "string" } },
"required": ["text"]
}
}
]
}
```
If your code reads `content[0]`, skip these blocks. Send the assistant message back unchanged, `mcp_tool_listing` blocks included, and keep sending `mcp-client-2026-09-15` on every request that carries one. Later requests then use the recorded list for that server instead of asking it again.
To pin a list yourself, copy a block's `tools` into the `tools` field of that server's MCPToolset. The API then doesn't ask the server for its tools, and the toolset's tools are exactly those entries, with `default_config` and `configs` applied:
```python
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": "echo",
"description": "Returns the text it receives.",
"input_schema": {
"type": "object",
"properties": { "text": { "type": "string" } },
"required": ["text"]
}
}
]
}
```
Each entry in `tools` holds the tool's `name` as the server lists it (without the server name), its `description`, and its `input_schema`.
The following example sends one request with an unpinned toolset, copies the returned list into the toolset's `tools` field, and sends the request again. The second response has no `mcp_tool_listing` block, because the API doesn't ask the server:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
from anthropic.types.beta import (
BetaMessageParam,
BetaRequestMCPServerURLDefinitionParam,
)
client = anthropic.Anthropic()
mcp_servers: list[BetaRequestMCPServerURLDefinitionParam] = [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
},
]
messages: list[BetaMessageParam] = [
{"role": "user", "content": "What tools do you have available?"},
]
# First request: the toolset isn't pinned, so the API asks the server for
# its tools and the response starts with an mcp_tool_listing block.
first = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
betas=["mcp-client-2026-09-15"],
mcp_servers=mcp_servers,
tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
messages=messages,
)
listing = next(block for block in first.content if block.type == "mcp_tool_listing")
print([tool.name for tool in listing.tools])
# Pin the list: copy the block's tools into the toolset. The API uses
# exactly these entries and doesn't ask the server again.
second = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
betas=["mcp-client-2026-09-15"],
mcp_servers=mcp_servers,
tools=[
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": tool.name,
"description": tool.description,
"input_schema": tool.input_schema,
}
for tool in listing.tools
],
},
],
messages=messages,
)
# With a pinned toolset, the response has no mcp_tool_listing block.
print([block.type for block in second.content])
```
With the `inline-tools-2026-09-15` beta header as well, you can add an MCP server partway through a conversation. See [Add an MCP server mid-conversation](../Guides/build-with-claude-mid-conversation-system-messages.md#add-an-mcp-server-mid-conversation-beta).
## Multiple MCP servers
You can connect to multiple MCP servers by including multiple server definitions in `mcp_servers` and a corresponding MCPToolset for each in the `tools` array:
```python
{
"model": "claude-opus-5-5",
"max_tokens": 1000,
"messages": [
{
"role": "user",
"content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
}
],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example1.com/sse",
"name": "mcp-server-1",
"authorization_token": "TOKEN1"
},
{
"type": "url",
"url": "https://mcp.example2.com/sse",
"name": "mcp-server-2",
"authorization_token": "TOKEN2"
}
],
"tools": [
{
"type": "mcp_toolset",
"mcp_server_name": "mcp-server-1"
},
{
"type": "mcp_toolset",
"mcp_server_name": "mcp-server-2",
"default_config": {
"defer_loading": true
}
}
]
}
```
With many tools available, Claude selects based on tool names and descriptions. Clear, specific tool descriptions improve selection accuracy. For large tool sets (dozens of tools across several servers), consider enabling [`defer_loading`](#tool-configuration-options) with the [Tool search tool](agents-and-tools-tool-use-tool-search-tool.md) so only relevant tools are surfaced per query.
## Authentication
For MCP servers that require OAuth authentication, you'll need to obtain an access token. The MCP connector beta supports passing an `authorization_token` parameter in the MCP server definition. API consumers are expected to handle the OAuth flow and obtain the access token prior to making the API call, and to refresh the token as needed.
### Obtaining an access token for testing
The MCP inspector can guide you through the process of obtaining an access token for testing purposes.
1. Run the inspector with the following command. You need Node.js installed on your machine.
``` shiki
npx @modelcontextprotocol/inspector
```
2. In the sidebar on the left, for **Transport type**, select either **SSE** or **Streamable HTTP**.
3. Enter the URL of the MCP server.
4. In the right area, click **Open Auth Settings** after **Need to configure authentication?**.
5. Click **Quick OAuth Flow** and authorize on the OAuth screen.
6. Follow the steps in the **OAuth Flow Progress** section of the inspector and click **Continue** until you reach **Authentication complete**.
7. Copy the `access_token` value.
8. Paste it into the `authorization_token` field in your MCP server configuration.
### Using the access token
Once you've obtained an access token using either of the preceding OAuth flows, you can use it in your MCP server configuration:
```python
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "authenticated-server",
"authorization_token": "YOUR_ACCESS_TOKEN_HERE"
}
]
}
```
For detailed explanations of the OAuth flow, refer to the [Authorization section](../../06-MCP-Tools/Spec-Archive/2025-11-25-basic-authorization.md) in the MCP specification.
## Client-side MCP helpers
If you manage your own MCP client connection (for example, with local stdio servers, MCP prompts, or MCP resources), the SDK provides helper functions that convert between MCP types and Claude API types. This eliminates manual conversion code when using an MCP SDK for your language (for example, the [TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)) alongside the Anthropic SDK.
Use the [`mcp_servers` API parameter](#using-the-mcp-connector-in-the-messages-api) when you have remote servers accessible by URL and only need tool support. Use the client-side helpers when you need local servers, prompts, resources, or more control over the connection with the base SDK.
### Installation
Install both the Anthropic SDK and the MCP SDK:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
The MCP helpers are included in the `mcp` extra, which requires Python 3.10 or later:
```python
pip install "anthropic[mcp]"
```
### Available helpers
Import the helpers for your language:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
from anthropic.lib.tools.mcp import (
async_mcp_tool,
mcp_message,
mcp_resource_to_content,
mcp_resource_to_file,
)
```
| Helper | Description |
|-------------------------------------|------------------------------------------------------------------------------------------|
| `async_mcp_tool(tool, mcp_client)` | Converts MCP tools to Claude API tools for use with `client.beta.messages.tool_runner()` |
| `mcp_message(message)` | Converts MCP prompt messages to Claude API message format |
| `mcp_resource_to_content(resource)` | Converts an MCP resource to a Claude API content block |
| `mcp_resource_to_file(resource)` | Converts an MCP resource to a file object for upload |
### Use MCP tools
Convert MCP tools for use with the SDK's [tool runner](agents-and-tools-tool-use-tool-runner.md), which handles tool execution automatically:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client
client = AsyncAnthropic()
async def main() -> None:
# Connect to an MCP server
server_params = StdioServerParameters(command="mcp-server")
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as mcp_client:
await mcp_client.initialize()
# List tools and convert them for the Claude API
tools_result = await mcp_client.list_tools()
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "What tools do you have available?"},
],
tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
)
final_message = await runner.until_done()
print(final_message)
asyncio.run(main())
```
### Use MCP prompts
Convert MCP prompt messages into Claude API message format:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
from anthropic.lib.tools.mcp import mcp_message
prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[mcp_message(message) for message in prompt.messages],
)
print(response)
```
### Use MCP resources
Convert MCP resources into content blocks to include in messages, or into file objects for upload:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
from anthropic.lib.tools.mcp import (
mcp_resource_to_content,
mcp_resource_to_file,
)
# As a content block in a message
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
mcp_resource_to_content(resource),
{"type": "text", "text": "Summarize this document"},
],
}
],
)
print(response)
# As a file upload
file_resource = await mcp_client.read_resource(
uri="file:///path/to/data.json",
)
uploaded = await client.files.upload(
file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)
```
### Error handling
The conversion functions fail with `UnsupportedMCPValueError` if an MCP value isn't supported by the Claude API (thrown, or in Go returned as an error). This can happen with unsupported content types, MIME types, or resource links (resolve resource links with your MCP client before converting).
## Batch requests
You can include `mcp_servers` in [Message Batches API](../Guides/build-with-claude-batch-processing.md) requests. MCP tool calls through the Batches API are priced the same as those in regular Messages API requests.
## Data retention
The MCP connector is not covered by ZDR arrangements. Data exchanged with MCP servers, including tool definitions and execution results, is retained according to Anthropic's standard data retention policy.
For ZDR eligibility across all features, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
## Migration guide
If you're using the deprecated `mcp-client-2025-04-04` beta header, follow this guide to migrate to the new version.
### Key changes
1. **New beta header:** Change from `mcp-client-2025-04-04` to `mcp-client-2025-11-20`
2. **Tool configuration moved:** Tool configuration now lives in the `tools` array as MCPToolset objects, not in the MCP server definition
3. **More flexible configuration:** New pattern supports allowlisting, denylisting, and per-tool configuration
### Migration steps
**Before (deprecated):**
```python
{
"model": "claude-opus-5-5",
"max_tokens": 1000,
"messages": [
// ...
],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example.com/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["tool1", "tool2"]
}
}
]
}
```
**After (current):**
```python
{
"model": "claude-opus-5-5",
"max_tokens": 1000,
"messages": [
// ...
],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example.com/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
],
"tools": [
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"default_config": {
"enabled": false
},
"configs": {
"tool1": {
"enabled": true
},
"tool2": {
"enabled": true
}
}
}
]
}
```
### Common migration patterns
| Old pattern | New pattern |
|---------------------------------------------|-----------------------------------------------------------------------------------------|
| No `tool_configuration` (all tools enabled) | MCPToolset with no `default_config` or `configs` |
| `tool_configuration.enabled: false` | MCPToolset with `default_config.enabled: false` |
| `tool_configuration.allowed_tools: [...]` | MCPToolset with `default_config.enabled: false` and specific tools enabled in `configs` |
## Deprecated version: mcp-client-2025-04-04
This version is deprecated. Migrate to `mcp-client-2025-11-20` using the preceding [migration guide](#migration-guide).
The previous version of the MCP connector included tool configuration directly in the MCP server definition:
```python
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["example_tool_1", "example_tool_2"]
}
}
]
}
```
### Deprecated field descriptions
| Property | Type | Description |
|------------------------------------|---------|--------------------------------------------------------------------|
| `tool_configuration` | object | **Deprecated:** Use MCPToolset in the `tools` array instead |
| `tool_configuration.enabled` | boolean | **Deprecated:** Use `default_config.enabled` in MCPToolset |
| `tool_configuration.allowed_tools` | array | **Deprecated:** Use allowlist pattern with `configs` in MCPToolset |
## Compatibility
Supported platforms
- Claude APIBeta
- Claude Platform on AWSBeta
- Microsoft FoundryBeta
---
## Architecture and components - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts
Path: 04-API-Reference/Agents-Tools/agents-and-tools-mcp-tunnels-concepts.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Fconcepts)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
[Overview](agents-and-tools-mcp-tunnels-overview.md)[Architecture and components](agents-and-tools-mcp-tunnels-concepts.md)[Quickstart](agents-and-tools-mcp-tunnels-quickstart.md)[Manage in the Console](agents-and-tools-mcp-tunnels-console.md)[Deploy with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md)[Deploy with Docker Compose](agents-and-tools-mcp-tunnels-deploy-compose.md)[Security](agents-and-tools-mcp-tunnels-security.md)[Troubleshooting](agents-and-tools-mcp-tunnels-troubleshooting.md)[Reference](agents-and-tools-mcp-tunnels-reference.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)MCP tunnels
# Architecture and components
Copy page
Canonical names for the parts of an MCP tunnel deployment, the two credential-provisioning modes, and the connection model.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
This page defines the terms used throughout the [MCP tunnels](agents-and-tools-mcp-tunnels-overview.md) documentation. Several components appear under different names in configuration files, container images, and prose; the following tables give one canonical name for each and list the aliases you may encounter.
## Components
| Term | Definition | Also appears as |
|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Tunnel stack** | The two containers you run inside your network to attach to a tunnel: the proxy and cloudflared. One stack serves one tunnel and can be replicated across hosts for availability. With programmatic access, the setup component runs alongside the stack to provision credentials. | the stack, the MCP tunnel stack, the tunnel deployment, your deployment |
| **Proxy** | Anthropic's routing component. Terminates inner TLS, validates that upstream IPs fall within an allowed range, and routes each request to an upstream MCP server based on hostname. | `mcp-proxy` (image name, Compose service name, and Helm container name), `mcp-gateway` (container-internal config path `/etc/mcp-gateway/config.yaml` and Helm `gateway.config.*` values prefix) |
| **cloudflared** | Cloudflare's open-source tunnel connector. Initiates the outbound-only connections from your network to the tunnel edge and carries encrypted traffic between the edge and the proxy. Not related to a Managed Agent. | the outbound connector, the tunnel connector |
| **Setup component** | The `setup` binary, shipped inside the `mcp-proxy` image. With programmatic access it authenticates over Workload Identity Federation, fetches the tunnel token, generates a CA and server certificate, and registers the CA with Anthropic. Also provides `renew-cert`. | setup Job (the Helm pre-install hook), `setup` service (the Compose profile), setup hook, setup binary, setup CLI |
| **Tunnel edge** | The Cloudflare edge servers that cloudflared dials out to (IP ranges `198.41.192.0/19` and `2606:4700:a0::/44`, port 7844 TCP and UDP). The tunnel that runs over them is provisioned and controlled by Anthropic; Cloudflare operates the underlying network. | the edge, the Anthropic-operated tunnel edge |
| **Inner TLS** | A second TLS handshake carried inside the tunnel's plaintext WebSocket stream, between Anthropic's backend and your proxy. The proxy presents a server certificate signed by a CA you registered on the tunnel. Because only you hold the private key, the transport provider cannot read request or response payloads. | the inner TLS handshake |
| **Upstream MCP server** | An MCP server running in your private network that the proxy routes to. Each upstream is exposed as one subdomain under your tunnel domain. | upstream, routed MCP server, tunneled MCP server |
## Credential provisioning
The tunnel stack needs two credentials at runtime: the **tunnel token**, which authenticates cloudflared's outbound connection, and a **server certificate** signed by a CA registered on the tunnel, which the proxy presents during the inner TLS handshake. There are two ways to supply them, presented throughout this guide as a pair of tabs.
| Mode | How credentials reach the stack | Helm chart name | Tab label |
|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|---------------------------------|
| **Programmatic access** | The setup component authenticates to the Tunnels API through [Workload Identity Federation](../Other/manage-claude-workload-identity-federation.md), fetches the tunnel token, generates a CA and server certificate locally, and registers the CA. No long-lived secret is copied by hand. Requires a federation rule with the `workspace:manage_tunnels` scope. | Managed mode (`setup.enabled: true`, the default) | **With programmatic access** |
| **Manual** | You copy the tunnel token from the Claude Console, generate a CA and server certificate yourself (for example with `openssl`), register the CA in the Console, and supply the token and certificate to the stack as secrets. No setup component runs. | External mode (`setup.enabled: false`) | **Without programmatic access** |
These modes are also referred to as **the programmatic flow** and **the manual flow** in the deploy guides.
## Connection model
Two directions are at work in a tunnel, and they point opposite ways:
- **Connection direction:** cloudflared dials **outbound** from your network to the tunnel edge. Your firewall sees only egress on port 7844; no inbound port is opened.
- **Request direction:** once that connection is established, MCP requests travel **from Anthropic toward your network** over it, through cloudflared to the proxy, and on to the upstream MCP server.
The phrase "outbound-only" describes the connection, not the requests carried over it.
Inner TLS spans Anthropic's backend and your proxy. cloudflared and the tunnel edge sit between them on the wire but see only ciphertext; the proxy is the first place inside your network where MCP request payloads are readable.
## See also
- [MCP tunnels](agents-and-tools-mcp-tunnels-overview.md) for the security model and shared-responsibility table.
- [MCP tunnels reference](agents-and-tools-mcp-tunnels-reference.md) for proxy configuration fields, certificate requirements, and the setup component.
---
## Manage tunnels in the Console - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console
Path: 04-API-Reference/Agents-Tools/agents-and-tools-mcp-tunnels-console.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Fconsole)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
[Overview](agents-and-tools-mcp-tunnels-overview.md)[Architecture and components](agents-and-tools-mcp-tunnels-concepts.md)[Quickstart](agents-and-tools-mcp-tunnels-quickstart.md)[Manage in the Console](agents-and-tools-mcp-tunnels-console.md)[Deploy with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md)[Deploy with Docker Compose](agents-and-tools-mcp-tunnels-deploy-compose.md)[Security](agents-and-tools-mcp-tunnels-security.md)[Troubleshooting](agents-and-tools-mcp-tunnels-troubleshooting.md)[Reference](agents-and-tools-mcp-tunnels-reference.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)MCP tunnels
# Manage tunnels in the Console
Copy page
Create tunnels, register CA certificates, retrieve the tunnel token, and attach tunneled MCP servers to agents from the Claude Console.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
This page covers the Console side of an MCP tunnels deployment: creating a tunnel, registering your CA certificate, retrieving the tunnel token, and attaching the [upstream MCP servers](agents-and-tools-mcp-tunnels-concepts.md#components) to an agent. [Deploy MCP tunnels with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md) and [Deploy MCP tunnels with Docker Compose](agents-and-tools-mcp-tunnels-deploy-compose.md) cover running the [tunnel stack](agents-and-tools-mcp-tunnels-concepts.md#components) inside your network.
## Prerequisites
- **One or more MCP servers** running in your private network. The tunnel routes traffic to them; it does not host them. See [Remote MCP servers](agents-and-tools-remote-mcp-servers.md) for examples you can deploy.
- **A Console role with the Manage tunnels permission**, so you can create and archive tunnels, rotate the token, and manage certificates. Organization admins and owners have it by default; custom roles and per-account grants can also include it. Roles without it have read-only access to the **MCP tunnels** page and tunnel details.
- **A way for your stack to authenticate to the Tunnels API.** Choose one:
- **[Programmatic access](agents-and-tools-mcp-tunnels-concepts.md#credential-provisioning) (recommended).** Set up [Workload Identity Federation](../Other/manage-claude-workload-identity-federation.md) during tunnel creation so your stack mints short-lived API tokens from your identity provider, fetches the tunnel token, and generates and registers a CA certificate automatically. Requires permission to manage federation rules, a registered OIDC issuer, and a federation rule with the `workspace:manage_tunnels` scope.
- **[Manual](agents-and-tools-mcp-tunnels-concepts.md#credential-provisioning).** Skip programmatic access. After creating the tunnel, [get the tunnel token](#get-the-connection-details), generate and [register a CA certificate](#add-a-ca-certificate) yourself, and supply the token and your server certificate to your tunnel stack as secrets.
## Create a tunnel
1. 1
### Open the MCP tunnels page
In the Claude Console, go to the [MCP tunnels](https://platform.claude.com/settings/workspaces/default/mcp-tunnels) page (`platform.claude.com/settings/workspaces/default/mcp-tunnels`). Tunnels are workspace-scoped; the new tunnel belongs to the workspace currently selected in the Console. Select the workspace you want in the workspace picker in the sidebar.
2. 2
### Name the tunnel
Click **New tunnel** and enter a name in the **Create tunnel** dialog. The name is required and identifies the tunnel in the list, on the detail page, and in the agent MCP server picker. A domain of the form `abcd1234.tunnel.anthropic.com` is assigned automatically.
3. 3
### Optionally set up programmatic access
If your role can manage federation rules, a **Set up programmatic access** toggle appears (off by default). If not, the Console shows a notice in its place and your tunnel stack uses the manual flow instead. The rest of the create flow is the same either way.
Programmatic access relies on [Workload Identity Federation](../Other/manage-claude-workload-identity-federation.md); read that page first if federation issuers, rules, and service accounts are unfamiliar. To turn the toggle on you need:
1. **A registered OIDC issuer** for the identity provider your stack presents tokens from (such as a Kubernetes cluster, AWS IAM, Google Cloud, or GitHub Actions). Register one on the **Issuers** tab of the [Workload identity](https://platform.claude.com/settings/workload-identity-federation) page (`platform.claude.com/settings/workload-identity-federation`) in the Claude Console if your organization doesn't have one.
2. **A federation rule with the `workspace:manage_tunnels` scope.** Turning on the toggle reveals a **Federation rule** picker. Choose an existing rule with that scope, or click **Create federation rule** to create one inline.
3. **The rule's service account added to this workspace.** The Tunnels API authorizes against the service account's workspace memberships. If you're creating the tunnel in a workspace other than the organization's default, [add the service account to that workspace](../Other/manage-claude-workspaces.md#role-inheritance) and pass the workspace ID at deploy time (`api.wif.workspaceId` for Helm, `ANTHROPIC_WORKSPACE_ID` for Compose).
Skipping this step is fully supported; both deploy guides have a **Without programmatic access** tab.
4. 4
### Create the tunnel
Click **Create tunnel**. The Console provisions the tunnel and opens the detail page.
5. 5
### Record the deployment identifiers
Both deploy paths need:
- The **tunnel ID** (`tnl_...`), shown on the tunnel detail page.
- The **tunnel domain** (`abcd1234.tunnel.anthropic.com`), shown on the tunnel detail page. Used as the proxy's `tunnel_domain` and in the server certificate's SAN.
What else you need depends on the [credential-provisioning mode](agents-and-tools-mcp-tunnels-concepts.md#credential-provisioning):
| With programmatic access | Without programmatic access |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| The **federation rule ID** (`fdrl_...`) of the rule you selected. The rule is org-level, not stored on the tunnel; find it on the **Rules** tab of the [Workload identity](https://platform.claude.com/settings/workload-identity-federation?tab=rules) page (`platform.claude.com/settings/workload-identity-federation?tab=rules`) in the Claude Console. | The **tunnel token**, revealed with the eye icon next to **Token** on the detail page. Treat it as a secret. See [Get the connection details](#get-the-connection-details). |
| The **organization ID** (a UUID), shown on the [Organization](../Other/playground.md) page (`platform.claude.com/settings/organization`) in the Claude Console. | A **CA certificate** that you generate and [register on the tunnel](#add-a-ca-certificate). |
With programmatic access, your stack fetches the tunnel token through the Tunnels API, generates the CA and server certificate locally (the private key never leaves your environment), and registers only the CA's public certificate with Anthropic. You're still responsible for securing the private keys and renewing the server certificate before it expires.
Your organization can have up to 10 active tunnels. Creating a tunnel does not establish any connectivity; that happens once your stack dials in with the tunnel token and a CA certificate is registered.
## Get the connection details
Open the tunnel. The detail page shows a **Connection** section with the domain and token and a **Certificates** section.
| Field | Description |
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Domain** | Copy the assigned `abcd1234.tunnel.anthropic.com` value. Your proxy's routes are subdomains of this domain. |
| **Token** | Click the eye icon (**Show token**) to fetch the tunnel token, then use the copy icon to copy it into your tunnel stack's secret store. Click **Rotate token** to invalidate the current token and issue a new one. |
Every reveal and rotation is recorded in your organization's [Compliance API](../Other/manage-claude-compliance-api.md) activity log. Rotation does not sever cloudflared connections that are already established, so you can rotate, redeploy with the new value, and let the old connections drain.
## Add a CA certificate
Anthropic verifies [inner TLS](agents-and-tools-mcp-tunnels-concepts.md#components) to your [proxy](agents-and-tools-mcp-tunnels-concepts.md#components) against the CA certificates you register on the tunnel. A tunnel with no active certificates cannot accept connections, and does not appear in the agent MCP server picker until one is registered.
1. 1
### Find the Certificates section
On the tunnel's detail page, scroll to the **Certificates** section and click **Add certificate**.
2. 2
### Provide the certificate
Click **Choose file** to select a `.pem`, `.crt`, or `.cer` file, drag the file onto the text area, or paste the PEM block directly. The modal rejects private-key material and content that isn't a `-----BEGIN CERTIFICATE-----` block. The file must be 8 kB or smaller.
3. 3
### Add the certificate
Click **Add certificate**. The fingerprint and expiry appear in the certificate list, and the slot count on the section header increments.
A tunnel holds up to two active certificates so you can rotate without downtime: register the new certificate alongside the old one, redeploy your proxy with the new key pair, confirm traffic is flowing, then click **Revoke** on the old certificate's row. Revoked certificates remain visible in the list with a **Revoked** badge.
## Deploy the tunnel stack
The tunnel exists in the Console, but no traffic flows until the tunnel stack is running inside your network and dialed in with the tunnel token. Follow one of the deploy guides:
[Deploy with Docker Compose](agents-and-tools-mcp-tunnels-deploy-compose.md)
Run the tunnel stack on a single host. Both programmatic-access and manual flows.
[Deploy with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md)
Run the tunnel stack on a Kubernetes cluster. Both programmatic-access and manual flows.
## Use the tunnel in an agent
Once your stack is running and has one or more MCP servers configured, attach an upstream MCP server to a Managed Agent session. To call the same servers from the Messages API instead, see [Use the tunneled MCP servers](agents-and-tools-mcp-tunnels-overview.md#use-the-tunneled-mcp-servers).
The picker only shows tunnels with at least one active certificate. A tunnel that still shows **Needs certificate** in the **MCP tunnels** list does not appear in the dropdown; register a CA certificate first. The picker is also workspace-scoped: it lists tunnels in the same workspace as the session, not other workspaces.
1. 1
### Open the Create session dialog
In the Claude Console, go to the [Sessions](../Other/playground.md) page (`platform.claude.com/sessions`) and click **Create session**.
2. 2
### Define an inline agent
In the agent picker, choose **Create new agent** so you can edit the MCP server list directly.
3. 3
### Add the MCP server
Click **+ MCP Server** and open the dropdown. Tunnels created in the current workspace appear at the top of the list, above the public connector catalog. Select the tunnel that fronts the server you want to reach.
4. 4
### Supply the routing
The card shows two optional fields: **Subdomain** (prefixed to the tunnel domain) and **Path** (appended after it). Fill in one or both, depending on how your proxy's routes are configured. The **Resolves to** line shows the full MCP server URL that the agent connects to.
The tunnel carries traffic; it does not authenticate to the upstream MCP server. Configure OAuth or bearer auth on the MCP server the same way as for any other MCP server.
## Archive a tunnel
Archiving immediately stops the tunnel from accepting connections and is permanent.
In the Claude Console, go to the [MCP tunnels](https://platform.claude.com/settings/workspaces/default/mcp-tunnels) page (`platform.claude.com/settings/workspaces/default/mcp-tunnels`). In the workspace picker in the sidebar, select the workspace that holds the tunnel. Open the row menu for the tunnel and choose **Archive**. Archived tunnels remain visible when you filter the list by **Archived** or **All**.
## Next steps
[Deploy with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md)
Install on a Kubernetes cluster using the Anthropic Helm chart.
[Security](agents-and-tools-mcp-tunnels-security.md)
Hardening guidance, credential rotation, and breach response.
---
## Deploy MCP tunnels with Docker Compose - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose
Path: 04-API-Reference/Agents-Tools/agents-and-tools-mcp-tunnels-deploy-compose.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Fdeploy-compose)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
[Overview](agents-and-tools-mcp-tunnels-overview.md)[Architecture and components](agents-and-tools-mcp-tunnels-concepts.md)[Quickstart](agents-and-tools-mcp-tunnels-quickstart.md)[Manage in the Console](agents-and-tools-mcp-tunnels-console.md)[Deploy with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md)[Deploy with Docker Compose](agents-and-tools-mcp-tunnels-deploy-compose.md)[Security](agents-and-tools-mcp-tunnels-security.md)[Troubleshooting](agents-and-tools-mcp-tunnels-troubleshooting.md)[Reference](agents-and-tools-mcp-tunnels-reference.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)MCP tunnels
# Deploy MCP tunnels with Docker Compose
Copy page
Install the MCP tunnel stack on a VM using Docker Compose.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
This guide deploys the [tunnel stack](agents-and-tools-mcp-tunnels-concepts.md#components) as hardened containers on a single host. The same configuration can be replicated across multiple hosts for availability.
## Before you begin
You need:
- **A tunnel.** With programmatic access, the [setup component](agents-and-tools-mcp-tunnels-concepts.md#components) creates one for you when you don't supply a tunnel ID; to attach to an existing tunnel instead, [create it in the Console](agents-and-tools-mcp-tunnels-console.md#create-a-tunnel) and record the tunnel ID (`tnl_...`). Manual provisioning always starts from a Console-created tunnel.
- **A way for the host to authenticate to the Tunnels API.**
- **Programmatic access (recommended).** Turn on **Set up programmatic access** when creating the tunnel so the setup component can authenticate through Workload Identity Federation. If you're letting the setup component create the tunnel, create the federation rule directly on the [Workload identity](https://platform.claude.com/settings/workload-identity-federation) page (`platform.claude.com/settings/workload-identity-federation`) in the Claude Console instead. Record the federation rule ID (`fdrl_...`) and your organization ID.
- **Manual.** Skip programmatic access. You'll [get the tunnel token from the Console](agents-and-tools-mcp-tunnels-console.md#get-the-connection-details), generate a CA and server certificate yourself, and [register the CA in the Console](agents-and-tools-mcp-tunnels-console.md#add-a-ca-certificate).
- **A host with Docker and Docker Compose** installed. The manual flow also requires `openssl` (1.1.1 or later).
- **Outbound network connectivity** from the host to `api.anthropic.com` (443 TCP) and the [tunnel edge](agents-and-tools-mcp-tunnels-concepts.md#components) (7844 TCP and UDP). See the full [network requirements](agents-and-tools-mcp-tunnels-overview.md#network-requirements).
- **One or more MCP servers** running and reachable from the host on the addresses you'll configure under `routes`. If you don't have one yet, [use the sample server](#optional-use-a-sample-mcp-server).
## Optional: Use a sample MCP server
If you don't have an MCP server available for testing, use this minimal one:
```python
mkdir -p mcp-tunnel
cat > mcp-tunnel/hello_server.py <<'EOF'
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)
@mcp.tool()
def hello(name: str = "world") -> str:
"""Say hello to someone."""
return f"Hello, {name}!"
if __name__ == "__main__":
mcp.run(transport="streamable-http")
EOF
```
The following Install steps `cd` into `mcp-tunnel/` and note where to add the corresponding service and route.
## Install
This guide provides one reference approach using Docker Compose. You are responsible for adapting it to meet your organization's security requirements.
With programmatic access
Without programmatic access
With programmatic access
This path requires the host to have an OIDC identity provider (such as a cloud VM metadata server or SPIFFE). If it doesn't, use the **Without programmatic access** tab instead.
The setup component uses Workload Identity Federation to fetch the tunnel token, generate a CA and server certificate, and register the CA with Anthropic.
1. 1
### Prepare the deployment directory
``` shiki
mkdir -p mcp-tunnel/{config,data}
cd mcp-tunnel
sudo chown 65532:65532 data
```
The containers run as the non-root UID `65532` and need write access to `data/`.
2. 2
### Write docker-compose.yaml
The compose file pins images by SHA-256 digest, runs every container as non-root with a read-only filesystem, drops all Linux capabilities, and disables privilege escalation.
``` shiki
cat > docker-compose.yaml <<'EOF'
services:
setup:
image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013
entrypoint: ["/setup"]
command:
- init
- --api-url=https://api.anthropic.com
- --output=dir:/data
- --token-version=1
environment:
- TUNNEL_ID
- ANTHROPIC_FEDERATION_RULE_ID
- ANTHROPIC_ORGANIZATION_ID
- ANTHROPIC_WORKSPACE_ID
- ANTHROPIC_IDENTITY_TOKEN
volumes:
- ./data:/data
user: "65532:65532"
read_only: true
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
profiles: ["setup"]
cloudflared:
image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
command: tunnel --no-autoupdate run --url http://localhost:8080
environment:
- TUNNEL_TOKEN
# Share the proxy's netns so localhost:8080 reaches it.
network_mode: "service:mcp-proxy"
restart: unless-stopped
user: "65532:65532"
read_only: true
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
stop_grace_period: 30s
logging:
options:
max-size: "10m"
max-file: "3"
mcp-proxy:
image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013
volumes:
- ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
- ./data:/data:ro
restart: unless-stopped
user: "65532:65532"
read_only: true
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
stop_grace_period: 30s
logging:
options:
max-size: "10m"
max-file: "3"
EOF
```
If you're using the [sample MCP server](#optional-use-a-sample-mcp-server), append it as a service:
``` shiki
cat >> docker-compose.yaml <<'EOF'
hello-mcp:
image: python:3.13-slim
working_dir: /app
volumes:
- ./hello_server.py:/app/hello_server.py:ro
command: sh -c "pip install --quiet mcp && python hello_server.py"
restart: unless-stopped
EOF
```
3. 3
### Provision the tunnel
Set the identifiers. Leave `TUNNEL_ID` unset to have the setup component create a tunnel; set it to attach to an existing tunnel from the [Console](agents-and-tools-mcp-tunnels-console.md#create-a-tunnel):
``` shiki
# export TUNNEL_ID=tnl_... # set to attach to an existing tunnel
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
```
If your federation rule is scoped to a workspace other than your organization's default, also set `ANTHROPIC_WORKSPACE_ID=wrkspc_...`; the setup component uses the default workspace otherwise. An auto-created tunnel is created in that workspace.
Set `ANTHROPIC_IDENTITY_TOKEN` to an OIDC JWT from this host's identity provider. Follow the [WIF guide for your provider](../Other/manage-claude-workload-identity-federation.md#identity-providers) to register the issuer, set the rule's subject, and mint the token; the rule's audience must match the audience you request when minting.
Run the setup component:
``` shiki
docker compose run --rm setup
```
`setup init` is idempotent over `data/`: re-running it reuses the tunnel ID and CA already stored there and never creates a second tunnel. A new CA is generated and registered only when `data/` is empty or `TUNNEL_ID` has changed; in that case the cap of two active certificates applies, so revoke one in the Console first if both slots are filled.
See [Setup component authentication failures](agents-and-tools-mcp-tunnels-troubleshooting.md#setup-component-authentication-failures) if it errors.
Retrieve your tunnel domain and export it for later steps:
``` shiki
export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain)
echo "$TUNNEL_DOMAIN"
```
Workload Identity Federation tokens are short-lived (1 hour by default) and expire automatically; there is nothing to revoke after setup completes.
4. 4
### Write the proxy config
`tunnel_domain` is **required**: the [proxy](agents-and-tools-mcp-tunnels-concepts.md#components) uses it to strip the domain suffix from incoming hostnames before looking up the subdomain in `routes`. `routes` is a flat map from subdomain to upstream URL, not a list.
``` shiki
cat > config/mcp-proxy.yaml <` per the [certificate requirements](agents-and-tools-mcp-tunnels-reference.md#certificate-requirements).
``` shiki
# Self-signed CA. Explicit extensions so it satisfies the certificate
# requirements regardless of distro openssl.cnf defaults.
openssl req -x509 -newkey rsa:2048 -nodes \
-keyout data/ca.key -out data/ca.crt \
-days 3650 -subj "/CN=mcp-tunnel-ca" \
-addext "basicConstraints=critical,CA:TRUE" \
-addext "keyUsage=critical,keyCertSign,cRLSign" \
-addext "subjectKeyIdentifier=hash"
# Extension file for the server certificate. Using -extfile (instead of
# -copy_extensions, which is OpenSSL 3.0+ only) keeps this working on
# OpenSSL 1.1.x.
cat > data/tls.ext < config/mcp-proxy.yaml < docker-compose.yaml <<'EOF'
services:
cloudflared:
image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
# --url is required: no ingress rules are pushed in the manual flow,
# so without it cloudflared 503s every request.
command: tunnel --no-autoupdate run --url http://localhost:8080
environment:
- TUNNEL_TOKEN
# Share the proxy's netns so localhost:8080 reaches it.
network_mode: "service:mcp-proxy"
restart: unless-stopped
user: "65532:65532"
read_only: true
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
stop_grace_period: 30s
logging:
options:
max-size: "10m"
max-file: "3"
mcp-proxy:
image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013
volumes:
- ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
- ./data:/data:ro
restart: unless-stopped
user: "65532:65532"
read_only: true
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
stop_grace_period: 30s
logging:
options:
max-size: "10m"
max-file: "3"
EOF
```
If you're using the [sample MCP server](#optional-use-a-sample-mcp-server), append it as a service:
``` shiki
cat >> docker-compose.yaml <<'EOF'
hello-mcp:
image: python:3.13-slim
working_dir: /app
volumes:
- ./hello_server.py:/app/hello_server.py:ro
command: sh -c "pip install --quiet mcp && python hello_server.py"
restart: unless-stopped
EOF
```
6. 6
### Start the deployment
``` shiki
docker compose up -d
```
The compose file reads `TUNNEL_TOKEN` from the host environment with no default, so the export must be repeated in every fresh shell and after a reboot.
For a multi-VM deployment, copy the `mcp-tunnel/` directory to each host, set `TUNNEL_TOKEN`, and run `docker compose up -d`. In the programmatic flow `TUNNEL_TOKEN` is `$(sudo cat data/tunnel-token)`; in the manual flow it's the value you copied from the Console. The same tunnel token and certificates work across all replicas.
## Verify the deployment
Verify end to end by calling an [upstream MCP server](agents-and-tools-mcp-tunnels-concepts.md#components) from Anthropic's side: see [Use the tunneled MCP servers](agents-and-tools-mcp-tunnels-overview.md#use-the-tunneled-mcp-servers). With the [sample MCP server](#optional-use-a-sample-mcp-server), the routed URL is `https://echo./mcp`. If verification fails, see [Troubleshooting](agents-and-tools-mcp-tunnels-troubleshooting.md).
## Upgrades
Run the commands in this section from inside the `mcp-tunnel/` deployment directory.
### Rotate the tunnel token
With programmatic access, increment `--token-version` in the `setup` service command, set the Workload Identity Federation identifiers, mint a fresh OIDC JWT, and re-run the setup component:
```python
# Edit docker-compose.yaml: increment the integer in the setup service's
# --token-version argument (for example, --token-version=1 to
# --token-version=2). The setup binary refuses to rotate when the value
# hasn't changed.
# export TUNNEL_ID=tnl_... # set only if you set it during install
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
# export ANTHROPIC_WORKSPACE_ID=wrkspc_... # if your rule is workspace-scoped
# Re-mint ANTHROPIC_IDENTITY_TOKEN per the WIF provider guide for your
# environment (it will have expired since install).
export ANTHROPIC_IDENTITY_TOKEN=...
docker compose run --rm setup
export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
docker compose up -d cloudflared
```
The `--token-version` argument is edited in `docker-compose.yaml` rather than passed on the command line so the new value persists for future runs of the setup component. The setup component authenticates with Workload Identity Federation; there is no API token to revoke.
Without programmatic access, click **Rotate token** on the tunnel detail page in the Console, then update the `TUNNEL_TOKEN` environment variable on each host and restart cloudflared (`docker compose up -d cloudflared`).
Clicking **Rotate token** invalidates the current token immediately. Between that moment and updating `TUNNEL_TOKEN` on every host and restarting cloudflared, any host whose cloudflared restarts (crash, host reboot) cannot reconnect. Update each host promptly after rotating.
### Certificate renewal
You're responsible for monitoring expiry and renewing the server certificate before it expires.
With programmatic access:
```python
docker compose run --rm setup renew-cert --output=dir:/data
```
The CLI arguments replace the `setup` service's `command` (the `init` arguments) but keep its `entrypoint`, so this runs `/setup renew-cert --output=dir:/data`.
Pass `--renew-before=720h` to make the command a no-op when more than 30 days of validity remain. This makes it safe to run on a fixed schedule.
Without programmatic access, sign a new server certificate with your existing CA (the CA registered in the Console doesn't change) and replace `data/tls.crt`. Set `TUNNEL_DOMAIN` first if you're running this from a fresh shell.
```python
export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
openssl req -new -key data/tls.key -out /tmp/server.csr \
-subj "/CN=${TUNNEL_DOMAIN}"
openssl x509 -req -in /tmp/server.csr \
-CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
-out data/tls.crt -days 90 \
-extfile data/tls.ext
```
In either flow the proxy polls `tls.cert_file` and reloads it automatically, so no restart is required.
## Next steps
[Use the tunneled MCP servers](agents-and-tools-mcp-tunnels-overview.md#use-the-tunneled-mcp-servers)
Attach an upstream MCP server to a Managed Agent or the Messages API.
[Security](agents-and-tools-mcp-tunnels-security.md)
Hardening guidance, credential rotation, and breach response.
[Troubleshooting](agents-and-tools-mcp-tunnels-troubleshooting.md)
Diagnose connectivity, TLS, and routing issues.
---
## Deploy MCP tunnels with Helm - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm
Path: 04-API-Reference/Agents-Tools/agents-and-tools-mcp-tunnels-deploy-helm.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Fdeploy-helm)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
[Overview](agents-and-tools-mcp-tunnels-overview.md)[Architecture and components](agents-and-tools-mcp-tunnels-concepts.md)[Quickstart](agents-and-tools-mcp-tunnels-quickstart.md)[Manage in the Console](agents-and-tools-mcp-tunnels-console.md)[Deploy with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md)[Deploy with Docker Compose](agents-and-tools-mcp-tunnels-deploy-compose.md)[Security](agents-and-tools-mcp-tunnels-security.md)[Troubleshooting](agents-and-tools-mcp-tunnels-troubleshooting.md)[Reference](agents-and-tools-mcp-tunnels-reference.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)MCP tunnels
# Deploy MCP tunnels with Helm
Copy page
Install the tunnel stack on a Kubernetes cluster using the Anthropic Helm chart.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
The Anthropic Helm chart installs the [tunnel stack](agents-and-tools-mcp-tunnels-concepts.md#components) as a single Deployment and attaches it to your tunnel: one the chart's setup hook creates for you, or an existing tunnel you created in the [Console](agents-and-tools-mcp-tunnels-console.md#create-a-tunnel).
## Before you begin
You need:
- **A tunnel.** With programmatic access, the chart's setup hook creates one for you when you don't supply a tunnel ID; to attach to an existing tunnel instead, [create it in the Console](agents-and-tools-mcp-tunnels-console.md#create-a-tunnel) and record the tunnel ID (`tnl_...`). Manual provisioning always starts from a Console-created tunnel; you'll also need its tunnel token and tunnel domain.
- **A way for the chart to authenticate to the Tunnels API.**
- **[Programmatic access](agents-and-tools-mcp-tunnels-concepts.md#credential-provisioning) (recommended).** The [setup component](agents-and-tools-mcp-tunnels-concepts.md#components) authenticates through Workload Identity Federation, fetches the tunnel token, generates a CA, registers it with Anthropic, and stores everything in a Secret. You'll need a federation rule scoped to `workspace:manage_tunnels`.
- **[Manual](agents-and-tools-mcp-tunnels-concepts.md#credential-provisioning).** Skip programmatic access. You'll [get the tunnel token from the Console](agents-and-tools-mcp-tunnels-console.md#get-the-connection-details), generate a CA and server certificate yourself, [register the CA in the Console](agents-and-tools-mcp-tunnels-console.md#add-a-ca-certificate), and supply the credentials to the cluster as Secrets.
- **A Kubernetes cluster** you can deploy to with `helm` and `kubectl`. The **Without programmatic access** tab also uses `openssl` (1.1.1 or later).
- **Outbound network connectivity** from the cluster to `api.anthropic.com` (443 TCP) and the [tunnel edge](agents-and-tools-mcp-tunnels-concepts.md#components) (7844 TCP and UDP). See the full [network requirements](agents-and-tools-mcp-tunnels-overview.md#network-requirements).
- **One or more MCP servers** running and reachable from the cluster on the addresses you'll configure under `gateway.config.routes`. If you don't have one yet, [use the sample server](#optional-use-a-sample-mcp-server).
## Optional: Use a sample MCP server
If you don't have an MCP server available for testing, use this minimal one:
```python
kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel apply -f - <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
name: hello-mcp-src
data:
hello_server.py: |
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)
@mcp.tool()
def hello(name: str = "world") -> str:
"""Say hello to someone."""
return f"Hello, {name}!"
if __name__ == "__main__":
mcp.run(transport="streamable-http")
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: hello-mcp
spec:
replicas: 1
selector:
matchLabels: { app: hello-mcp }
template:
metadata:
labels: { app: hello-mcp }
spec:
containers:
- name: hello-mcp
image: python:3.13-slim
command: ["sh", "-c", "pip install --quiet mcp && python /app/hello_server.py"]
volumeMounts:
- { name: src, mountPath: /app }
ports:
- { containerPort: 9000 }
volumes:
- name: src
configMap: { name: hello-mcp-src }
---
apiVersion: v1
kind: Service
metadata:
name: hello-mcp
spec:
selector: { app: hello-mcp }
ports:
- { port: 9000, targetPort: 9000 }
EOF
```
The Install steps that follow note where to add the corresponding route.
## Install
With programmatic access
Without programmatic access
With programmatic access
The setup component exchanges the cluster's projected ServiceAccount token through your federation rule, fetches the tunnel token, generates a CA and server certificate, and registers the CA with Anthropic. A daily CronJob renews the server certificate as needed, so you don't handle any secrets by hand.
1. 1
### Set up Workload Identity Federation for the cluster
Follow [Use WIF with Kubernetes](../Other/manage-claude-wif-providers-kubernetes.md) to register your cluster's OIDC issuer and create a federation rule. The setup component runs under its own ServiceAccount in the release namespace; the exact name follows Helm's `fullname` convention, so for any release name other than `mcp-tunnel`, run `helm template ... | grep -A2 'kind: ServiceAccount'` to confirm it before creating the rule. The rest of this guide assumes release name `mcp-tunnel` in namespace `mcp-tunnel`, where the ServiceAccount is `mcp-tunnel-setup`.
| Field | Value |
|----------|------------------------------------------------------|
| Subject | `system:serviceaccount:mcp-tunnel:mcp-tunnel-setup` |
| Audience | `api.anthropic.com` (the chart's default; no scheme) |
| Scope | `workspace:manage_tunnels` |
The chart's default audience is `api.anthropic.com` with no scheme, but the Console's federation-rule form suggests `https://api.anthropic.com`. The two must match byte-for-byte or authentication fails. Either set the rule's audience to `api.anthropic.com`, or set `api.wif.audience` in `values.yaml` to `https://api.anthropic.com`.
If the tunnel is in a workspace other than the organization's default, also [add the rule's service account to that workspace](../Other/manage-claude-workspaces.md#role-inheritance) (the Tunnels API authorizes against the service account's workspace memberships).
Note the rule's ID (`fdrl_...`); you'll set it as `api.wif.federationRuleId`.
The daily certificate-renewal CronJob uses a separate ServiceAccount (also derived from the Helm `fullname`) but does not call the Tunnels API; it renews the certificate locally and only needs Kubernetes RBAC, which the chart grants. The federation rule does not need to cover it.
2. 2
### Fetch the default values
``` shiki
helm show values \
oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
--version 2.0.2 > values.yaml
```
3. 3
### Configure tunnel attachment and routes
Edit `values.yaml` and set the `api.wif.*` keys with the federation rule ID and organization ID, plus a `routes` entry for each [upstream MCP server](agents-and-tools-mcp-tunnels-concepts.md#components):
values.yaml
``` shiki
api:
wif:
federationRuleId: "fdrl_..."
organizationId: "00000000-0000-0000-0000-000000000000"
# Set when the tunnel is in a non-default workspace and the
# rule's service account is a member of that workspace.
# workspaceId: "wrkspc_..."
tunnel:
# Leave empty to have the setup hook create a tunnel during install.
# Set to attach to an existing tunnel from the Console.
id: ""
# Increment to rotate the tunnel token on the next upgrade.
# See the "Rotate the tunnel token" section.
tokenVersion: "1"
gateway:
config:
routes:
docs: http://docs-mcp.internal:8080
search: http://search-mcp.internal:8080
```
With these routes, Claude reaches the servers at `docs.` and `search.`. Some managed Kubernetes distributions allocate the Service CIDR outside the standard private ranges; if your routes target in-cluster Services, add `gateway.config.upstream.allowed_ips` here per [Upstream IP validation](agents-and-tools-mcp-tunnels-troubleshooting.md#upstream-ip-validation).
If you're using the [sample MCP server](#optional-use-a-sample-mcp-server), set `routes` to `echo: http://hello-mcp:9000` instead.
4. 4
### Review the rendered manifests
Render the chart and review the output according to your organization's vetting practices:
``` shiki
helm template mcp-tunnel \
oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
--version 2.0.2 \
-n mcp-tunnel \
-f values.yaml > rendered.yaml
```
5. 5
### Install
``` shiki
helm install mcp-tunnel \
oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
--version 2.0.2 \
--namespace mcp-tunnel --create-namespace \
-f values.yaml
```
The setup component runs as a Helm pre-install hook Job, so `helm install` blocks until it completes. On success Helm deletes the Job automatically. If `helm install` fails with a hook error, see [Setup component authentication failures](agents-and-tools-mcp-tunnels-troubleshooting.md#setup-component-authentication-failures).
When `tunnel.id` is empty, the setup component creates the tunnel in the workspace your federation rule targets (the organization's default workspace unless you set `api.wif.workspaceId`) and stores its ID and domain in the `mcp-tunnel` Secret. Find the domain you'll need for [verification](#verify-the-deployment) on the tunnel's detail page, which you open from the [MCP tunnels](https://platform.claude.com/settings/workspaces/default/mcp-tunnels) page (`platform.claude.com/settings/workspaces/default/mcp-tunnels`) in the Console. In the workspace picker in the sidebar, select the workspace that holds the tunnel. You can also read the domain from the Secret:
``` shiki
kubectl -n mcp-tunnel get secret mcp-tunnel \
-o jsonpath='{.data.tunnel-domain}' | base64 -d
```
Re-running the setup component (during [upgrades](#upgrades) or [token rotation](#rotate-the-tunnel-token)) reuses the tunnel ID stored in this Secret; it never creates a second tunnel.
The `api.wif.*` values are identifiers, not secrets, so storing them in Helm release-history Secrets is not a risk. The sensitive data at rest is the `mcp-tunnel` Secret the setup component creates, which holds the tunnel token and TLS private keys. Apply your organization's standard practices for protecting Kubernetes Secrets to this namespace.
Without programmatic access
In this mode (`setup.enabled: false`) the chart makes no API calls; the setup component does not run and there is no cert-renew CronJob. Use this path if you'd rather not set up Workload Identity Federation.
1. 1
### Get the tunnel token and domain
[Create the tunnel](agents-and-tools-mcp-tunnels-console.md#create-a-tunnel) and [get the tunnel token from the Console](agents-and-tools-mcp-tunnels-console.md#get-the-connection-details).
Record the tunnel domain from the detail page. You'll set it as `gateway.config.tunnel_domain`.
2. 2
### Generate a CA and server certificate
The proxy listens on plain WebSocket, with [inner TLS](agents-and-tools-mcp-tunnels-concepts.md#components) carried inside that stream using the certificate you generate here. The server certificate's SAN must include `*.` per the [certificate requirements](agents-and-tools-mcp-tunnels-reference.md#certificate-requirements).
``` shiki
export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
mkdir -p mcp-tunnel/data
cd mcp-tunnel
# Self-signed CA. Explicit extensions so it satisfies the certificate
# requirements regardless of distro openssl.cnf defaults.
openssl req -x509 -newkey rsa:2048 -nodes \
-keyout data/ca.key -out data/ca.crt \
-days 3650 -subj "/CN=mcp-tunnel-ca" \
-addext "basicConstraints=critical,CA:TRUE" \
-addext "keyUsage=critical,keyCertSign,cRLSign" \
-addext "subjectKeyIdentifier=hash"
# Extension file for the server certificate. Using -extfile (instead of
# -copy_extensions, which is OpenSSL 3.0+ only) keeps this working on
# OpenSSL 1.1.x.
cat > data/tls.ext < values.yaml
```
5. 5
### Configure values for manual provisioning
Edit `values.yaml` and set the following keys:
values.yaml
``` shiki
setup:
enabled: false
external:
tunnelTokenSecretName: mcp-tunnel-token # must contain key: tunnel-token
serverCertSecretName: mcp-tunnel-cert # must contain keys: tls.crt, tls.key
gateway:
config:
# Required when setup.enabled is false. Replace the placeholder with
# the $TUNNEL_DOMAIN value you exported earlier. When setup.enabled
# is true the chart injects this from the Secret as a -tunnel-domain
# flag instead.
tunnel_domain: YOUR_TUNNEL_DOMAIN_HERE
routes:
docs: http://docs-mcp.internal:8080
search: http://search-mcp.internal:8080
```
Some managed Kubernetes distributions allocate the Service CIDR outside the standard private ranges; if your routes target in-cluster Services, add `gateway.config.upstream.allowed_ips` here per [Upstream IP validation](agents-and-tools-mcp-tunnels-troubleshooting.md#upstream-ip-validation).
If you're using the [sample MCP server](#optional-use-a-sample-mcp-server), set `routes` to `echo: http://hello-mcp:9000` instead.
6. 6
### Review the rendered manifests
``` shiki
helm template mcp-tunnel \
oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
--version 2.0.2 \
-n mcp-tunnel \
-f values.yaml > rendered.yaml
```
7. 7
### Install
``` shiki
helm install mcp-tunnel \
oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
--version 2.0.2 \
--namespace mcp-tunnel --create-namespace \
-f values.yaml
```
## Verify the deployment
Verify end to end from Anthropic's side: use `https://./` in a Managed Agent session or a Messages API request, where `` is a key from `gateway.config.routes` and `` is whatever the upstream MCP server serves at. With the [sample MCP server](#optional-use-a-sample-mcp-server), that's `https://echo./mcp`. See [Use the tunneled MCP servers](agents-and-tools-mcp-tunnels-overview.md#use-the-tunneled-mcp-servers) for the request shapes.
If that fails, check the pod logs (`kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy` and `-c cloudflared`) and consult [Troubleshooting](agents-and-tools-mcp-tunnels-troubleshooting.md).
## Optional configuration
### Restrict egress with NetworkPolicy
Ingress to the proxy pod is denied by default (`networkPolicy.ingress.enabled: true`). To additionally restrict pod egress, set `networkPolicy.egress.enabled: true` and populate `networkPolicy.egress.mcpServers` with pod label selectors or CIDR ranges that cover your upstream MCP servers. Egress from cloudflared to the tunnel edge is allowed separately through `networkPolicy.egress.cloudflaredEgressCIDRs`.
### Tune the proxy
Fields under `gateway.config.*` pass through to the proxy configuration file. Common adjustments include `upstream.allowed_ips`, `log_level`, and `upstream.tls`. See the [proxy configuration](agents-and-tools-mcp-tunnels-reference.md#proxy-configuration) reference for the full field list. The chart always sets `listen_addr`, `tls.cert_file`, and `tls.key_file`; setting them in `gateway.config` has no effect.
### Supply your own OIDC token
By default the chart projects a Kubernetes ServiceAccount token for the setup component. To use a token from a different identity provider (such as [SPIFFE](../Other/manage-claude-wif-providers-spiffe.md), Vault, or a cloud-SDK sidecar), mount it with `setup.extraVolumes` and `setup.extraVolumeMounts`. Then point `api.wif.tokenFile` at the mount path. The chart sets `ANTHROPIC_IDENTITY_TOKEN_FILE` to that path, and the setup component reads the token from there.
## Upgrades
Always pass `--version` to `helm upgrade` so you don't pull a newer chart unexpectedly.
### Upgrade from chart 1.x
Chart 2.0.0 moves the tunnel ID from `api.wif.tunnelId` to `tunnel.id`. Before upgrading, edit your `values.yaml`: move the `tnl_...` value to `tunnel.id` and remove `api.wif.tunnelId`. Leaving `tunnel.id` unset is safe (the setup component reuses the tunnel ID already stored in the `mcp-tunnel` Secret on re-run), but the explicit move keeps your `values.yaml` accurate. Also update your federation rule's scope from `org:manage_tunnels` to `workspace:manage_tunnels` in the Console.
### Change configuration
For routine changes such as routes, replica count, or NetworkPolicy:
```python
helm upgrade mcp-tunnel \
oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
--version 2.0.2 \
-n mcp-tunnel \
-f values.yaml
```
Maintain a complete `values.yaml` rather than relying on `--reuse-values`. Helm's deep-merge behavior can silently fail to remove deleted routes.
### Rotate the tunnel token
With programmatic access, increment `tunnel.tokenVersion` in `values.yaml` and upgrade with `--set setup.force=true`. The setup component only re-runs on upgrades when forced:
```python
helm upgrade mcp-tunnel \
oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
--version 2.0.2 \
-n mcp-tunnel \
-f values.yaml \
--set setup.force=true
```
The setup component authenticates with Workload Identity Federation; there is no API token to revoke.
Without programmatic access, click **Rotate token** on the tunnel detail page in the Console, then update the `mcp-tunnel-token` Secret:
```python
kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \
--from-literal=tunnel-token='eyJ...' --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel rollout restart deploy/mcp-tunnel
```
Clicking **Rotate token** invalidates the current token immediately. Until the Secret is updated and the rollout completes, any pod that restarts with the old token (eviction, node drain, OOM) cannot reconnect. Update the Secret promptly after rotating; for stricter availability requirements, use programmatic access so the chart handles the rotation atomically.
### Certificate renewal
The chart provides automation, but you remain responsible for monitoring expiry and confirming renewal completes.
With programmatic access, certificate renewal is automatic. The chart deploys a CronJob (named after the Helm `fullname`, suffixed `-cert-renew`) that runs `setup renew-cert` daily (at `serverCert.cronSchedule`, default `0 0 * * *` UTC). The job is a no-op unless the certificate is within `serverCert.renewBefore` of expiry (default 30 days). Renewal is local: the job signs a fresh certificate with the CA already stored in the Secret, makes no API calls, and only needs the Kubernetes RBAC the chart grants. The proxy hot-reloads the certificate from the Secret mount, so no Deployment restart is needed.
Without programmatic access there is no CronJob. From inside the `mcp-tunnel/` directory you kept after install, sign a fresh server certificate with the existing CA (do not regenerate the CA):
```python
export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
openssl req -new -key data/tls.key -out /tmp/server.csr \
-subj "/CN=${TUNNEL_DOMAIN}"
openssl x509 -req -in /tmp/server.csr \
-CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
-out data/tls.crt -days 90 -extfile data/tls.ext
kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \
--from-file=tls.crt=data/tls.crt --from-file=tls.key=data/tls.key \
--dry-run=client -o yaml | kubectl apply -f -
```
The proxy hot-reloads the certificate from the Secret mount.
## Next steps
[Use the tunneled MCP servers](agents-and-tools-mcp-tunnels-overview.md#use-the-tunneled-mcp-servers)
Attach an upstream MCP server to a Managed Agent or the Messages API.
[Security](agents-and-tools-mcp-tunnels-security.md)
Hardening guidance, credential rotation, and breach response.
[Troubleshooting](agents-and-tools-mcp-tunnels-troubleshooting.md)
Diagnose connectivity, TLS, and routing issues.
---
## MCP tunnels - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview
Path: 04-API-Reference/Agents-Tools/agents-and-tools-mcp-tunnels-overview.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Foverview)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
[Overview](agents-and-tools-mcp-tunnels-overview.md)[Architecture and components](agents-and-tools-mcp-tunnels-concepts.md)[Quickstart](agents-and-tools-mcp-tunnels-quickstart.md)[Manage in the Console](agents-and-tools-mcp-tunnels-console.md)[Deploy with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md)[Deploy with Docker Compose](agents-and-tools-mcp-tunnels-deploy-compose.md)[Security](agents-and-tools-mcp-tunnels-security.md)[Troubleshooting](agents-and-tools-mcp-tunnels-troubleshooting.md)[Reference](agents-and-tools-mcp-tunnels-reference.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)MCP tunnels
# MCP tunnels
Copy page
Securely connect Claude to MCP servers running in your private network without opening inbound ports or exposing services to the public internet.
Copy page
MCP tunnels let you connect Claude to Model Context Protocol (MCP) servers that run inside your private network. Traffic flows over an outbound-only connection, so you don't need to open inbound firewall ports, expose services to the public internet, or allowlist Anthropic's IP ranges on your origin.
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them. They are provided "as-is" without any uptime, support, or continuity commitment, and they depend on a third-party network provider (Cloudflare) that makes no availability commitment for the underlying transport. Anthropic may modify or discontinue MCP tunnels at any time.
For Zero Data Retention and HIPAA BAA eligibility, see [API and data retention](../Other/manage-claude-api-and-data-retention.md#feature-eligibility).
## How it works
The [tunnel stack](agents-and-tools-mcp-tunnels-concepts.md#components) is two components that run inside your network:
- **[cloudflared](agents-and-tools-mcp-tunnels-concepts.md#components):** Cloudflare's open-source tunnel connector. It initiates outbound-only connections to the [tunnel edge](agents-and-tools-mcp-tunnels-concepts.md#components) and carries encrypted traffic from Anthropic to your proxy.
- **[Proxy](agents-and-tools-mcp-tunnels-concepts.md#components):** Anthropic's routing component. It terminates [inner TLS](agents-and-tools-mcp-tunnels-concepts.md#components), validates that upstream IPs fall within an allowed range, and routes each request to the correct [upstream MCP server](agents-and-tools-mcp-tunnels-concepts.md#components) based on hostname.
Each MCP server you expose gets a hostname under your tunnel domain (for example, `docs.`). You attach these hostnames to a Managed Agent session in the Claude Console, or pass them to the Messages API through the [MCP connector](agents-and-tools-mcp-connector.md).
## Prerequisites
Before deploying, make sure you have:
- A deployment target: a Kubernetes cluster, or a VM with Docker and Docker Compose.
- A tunnel. Create one in the Claude Console (see [Create a tunnel](agents-and-tools-mcp-tunnels-console.md#create-a-tunnel)) or through the API; the Helm chart's setup hook can also create one for you during install.
- A way for your stack to authenticate to the Tunnels API. Choose one:
- **[Programmatic access](agents-and-tools-mcp-tunnels-concepts.md#credential-provisioning) (recommended).** Set up [Workload Identity Federation](../Other/manage-claude-workload-identity-federation.md) when you create the tunnel. Your stack mints short-lived API tokens from your identity provider, fetches the tunnel token, and generates and registers a CA certificate automatically. Requires permission to manage federation rules, a registered OIDC issuer, and a federation rule with the `workspace:manage_tunnels` scope.
- **[Manual](agents-and-tools-mcp-tunnels-concepts.md#credential-provisioning).** Supply static credentials yourself: the tunnel token from the Console and a server certificate signed by a CA you register there. See [Get the connection details](agents-and-tools-mcp-tunnels-console.md#get-the-connection-details) and [Add a CA certificate](agents-and-tools-mcp-tunnels-console.md#add-a-ca-certificate).
- One or more MCP servers running in your private network. See [Remote MCP servers](agents-and-tools-remote-mcp-servers.md) for examples.
- Outbound connectivity as listed under [Network requirements](#network-requirements).
### Network requirements
| Component | Destination | Port / protocol | Used during |
|-----------------|------------------------------------------------------|------------------|---------------------------------|
| Setup component | `api.anthropic.com` | 443 TCP | Provisioning and token rotation |
| cloudflared | Tunnel edge (`198.41.192.0/19`, `2606:4700:a0::/44`) | 7844 TCP and UDP | Runtime |
| Proxy | Your upstream MCP servers | As configured | Runtime |
## Security model
### Security layers
Three independent layers protect every request:
| Layer | Protects against |
|-----------------------------------------------------------------------------|--------------------------------------------------------------------------|
| Outer mTLS between Anthropic and the transport provider, with IP validation | Unauthorized clients reaching the tunnel |
| Inner TLS from Anthropic's back end to your proxy | Payload inspection by the transport provider or any network intermediary |
| OAuth on each MCP server | Unauthorized use of MCP tools by authenticated tunnel traffic |
The tunnel transport runs on Cloudflare's network. Because the proxy terminates inner TLS using a certificate that only you hold, Cloudflare cannot read request or response payloads. Anthropic does not connect to a tunnel until a CA certificate is registered, so payloads are always encrypted when they cross Cloudflare's network. Cloudflare does receive connection metadata; see [What the transport provider can observe](#what-the-transport-provider-can-observe).
### Shared responsibility model
| Anthropic handles | Your organization handles |
|---------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
| Tunnel access control | All content and traffic that transits your tunnel, and compliance with applicable third-party acceptable-use policies (including Cloudflare's) |
| Validating your CA certificate before connecting to your proxy | Adherence to the deployment guidance on these pages |
| Ensuring Claude only sends requests to tunnels owned by your organization | Securing tunnel tokens and TLS private keys |
| | Managing the server certificate and renewing it before it expires |
| | Configuring OAuth on each MCP server |
| | Restricting network access for the proxy and MCP servers |
| | Notifying Anthropic if you suspect a breach |
If an attacker obtains your tunnel token **and** one of your TLS private keys, they could impersonate your proxy and read MCP request payloads. Treat both as high-value secrets. See [MCP tunnels security](agents-and-tools-mcp-tunnels-security.md) for hardening guidance.
### What the transport provider can observe
Cloudflare provides the outbound transport. It cannot read MCP request or response payloads, but it does receive the following connection metadata:
- the egress IP address of the host running cloudflared
- a cloudflared host fingerprint
- connection timing and byte-volume
- the `*.tunnel.anthropic.com` subdomain assigned to your tunnel
Anthropic's agreement with Cloudflare restricts Cloudflare's use of this telemetry. Cloudflare acts as a subprocessor for this research preview.
## Deploy a tunnel
If you're new to MCP tunnels, start with the quickstart to get a working tunnel locally before configuring a production deployment.
[Quickstart](agents-and-tools-mcp-tunnels-quickstart.md)
The shortest path to a working tunnel: Docker Compose with a sample MCP server.
[Deploy with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md)
Install on a Kubernetes cluster using the Anthropic Helm chart.
[Deploy with Docker Compose](agents-and-tools-mcp-tunnels-deploy-compose.md)
Install on a VM using Docker Compose.
Choosing between them:
- **Deployment target**
- **Helm** when deploying to Kubernetes.
- **Docker Compose** for a single host or local testing.
- **Authentication for setup**
- **Programmatic access** (through Workload Identity Federation) when you have an OIDC identity provider such as a Kubernetes cluster, cloud IAM, or SPIFFE.
- **Manual credentials** when you don't, or when you're testing.
## Use the tunneled MCP servers
Once your tunnel is active (it has an active CA certificate and your tunnel stack is connected), the upstream MCP servers are reachable from Claude Managed Agents and the Messages API.
MCP tunnels created through the Console are not available as connectors in claude.ai.
In both cases, the tunnel carries encrypted traffic to your MCP server but does not authenticate to it. If the upstream MCP server requires its own authentication (OAuth, bearer token), supply it the same way you would for any other MCP server; it is independent of the tunnel.
### Managed Agents (Console)
1. On the [Sessions](../Other/playground.md) page (`platform.claude.com/sessions`) in the Claude Console, create a session and choose **Create new agent** so you can edit the MCP server list.
2. Click **+ MCP Server** and open the dropdown. Tunnels in the session's workspace that have at least one active certificate appear at the top of the list, above the public connector catalog.
3. Select the tunnel and supply the **Subdomain** that your proxy routes to a specific MCP server, and the **Path** the upstream MCP server expects. The **Resolves to** line shows the exact URL.
### Messages API
Pass the upstream MCP server's URL in the `mcp_servers` array, the same way as any other remote MCP server. The request body and `anthropic-beta` header follow the standard [MCP connector](agents-and-tools-mcp-connector.md) format; only the `url` is tunnel-specific. The following example uses the MCP connector's `mcp-client` beta header, which is separate from the `mcp-tunnels` beta used by the [Tunnels API](agents-and-tools-mcp-tunnels-reference.md). Make the request in the workspace the tunnel was created in by using an API key for that workspace or, if your key has access to multiple workspaces, by setting the [`anthropic-workspace-id` header](../Other/manage-claude-authentication.md#select-a-workspace) to that workspace.
The URL's host is `.`. The path depends on your upstream MCP server, not the tunnel: FastMCP's `streamable-http` transport serves at `/mcp`, and other servers may use `/` or a custom path (check the server's documentation). The proxy forwards the path untouched.
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1000,
messages=[{"role": "user", "content": "Use the hello tool to greet tunnel."}],
mcp_servers=[
{
"type": "url",
"url": "https://echo.YOUR_TUNNEL_DOMAIN_HERE/mcp",
"name": "echo",
}
],
tools=[{"type": "mcp_toolset", "mcp_server_name": "echo"}],
betas=["mcp-client-2025-11-20"],
)
print(response)
```
For authenticating to the upstream MCP server (`authorization_token`) and other `mcp_servers` options, see [MCP connector](agents-and-tools-mcp-connector.md).
## Next steps
[Security](agents-and-tools-mcp-tunnels-security.md)
Hardening guidance, credential rotation, and breach response.
[Troubleshooting](agents-and-tools-mcp-tunnels-troubleshooting.md)
Diagnose connectivity, TLS, and routing issues.
[Reference](agents-and-tools-mcp-tunnels-reference.md)
Proxy config fields, the Tunnels API, certificate requirements, and the setup component.
[MCP connector](agents-and-tools-mcp-connector.md)
Use tunneled servers from the Messages API.
---
## MCP tunnels quickstart - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/quickstart
Path: 04-API-Reference/Agents-Tools/agents-and-tools-mcp-tunnels-quickstart.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Fquickstart)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
[Overview](agents-and-tools-mcp-tunnels-overview.md)[Architecture and components](agents-and-tools-mcp-tunnels-concepts.md)[Quickstart](agents-and-tools-mcp-tunnels-quickstart.md)[Manage in the Console](agents-and-tools-mcp-tunnels-console.md)[Deploy with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md)[Deploy with Docker Compose](agents-and-tools-mcp-tunnels-deploy-compose.md)[Security](agents-and-tools-mcp-tunnels-security.md)[Troubleshooting](agents-and-tools-mcp-tunnels-troubleshooting.md)[Reference](agents-and-tools-mcp-tunnels-reference.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)MCP tunnels
# MCP tunnels quickstart
Copy page
Connect Claude to a private MCP server using a local Docker Compose deployment.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
This quickstart takes you from zero to Claude calling a private MCP server through a tunnel. It uses Docker Compose with [manual](agents-and-tools-mcp-tunnels-concepts.md#credential-provisioning) credential provisioning, which is the shortest path for local testing. For production deployments, see [Deploy with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md) or [Deploy with Docker Compose](agents-and-tools-mcp-tunnels-deploy-compose.md).
## What you'll build
A two-container [tunnel stack](agents-and-tools-mcp-tunnels-concepts.md#components) (the [proxy](agents-and-tools-mcp-tunnels-concepts.md#components) and [cloudflared](agents-and-tools-mcp-tunnels-concepts.md#components)) plus a sample MCP server running alongside it. When everything is running, the sample server is reachable from Claude at `https://echo./mcp` even though nothing is listening on a public port.
## What you need
- [Docker and Docker Compose](https://docs.docker.com/get-docker/) on a machine with outbound internet access.
- A role in the [Claude Console](../Other/playground.md) that can manage MCP tunnels. See the [Console guide prerequisites](agents-and-tools-mcp-tunnels-console.md#prerequisites).
- [OpenSSL](https://openssl-library.org/source/) 1.1.1 or later. Preinstalled on macOS and most Linux distributions; on Windows, install it separately (the `openssl` binary must be on your `PATH`).
1. 1
### Create a tunnel
In the Claude Console, go to the [MCP tunnels](https://platform.claude.com/settings/workspaces/default/mcp-tunnels) page (`platform.claude.com/settings/workspaces/default/mcp-tunnels`). Each tunnel belongs to one workspace. Select the workspace you want in the workspace picker in the sidebar. Click **New tunnel** and give it a name. Leave **Set up programmatic access** off; this quickstart uses manual credential provisioning.
After it's created, open the tunnel. Copy two values from the **Connection** section:
- **Domain** (looks like `abcd1234.tunnel.anthropic.com`)
- **Token** (click the eye icon, then copy)
2. 2
### Set up the deployment directory
macOS / Linux
Windows (PowerShell)
macOS / Linux
``` shiki
mkdir -p mcp-tunnel/{config,data}
cd mcp-tunnel
export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE # from step 1
export TUNNEL_TOKEN='eyJ...' # from step 1
```
Windows (PowerShell)
``` shiki
New-Item -ItemType Directory -Force -Path mcp-tunnel/config, mcp-tunnel/data | Out-Null
Set-Location mcp-tunnel
$env:TUNNEL_DOMAIN = "YOUR_TUNNEL_DOMAIN_HERE" # from step 1
$env:TUNNEL_TOKEN = "eyJ..." # from step 1
```
3. 3
### Generate a CA and server certificate
The proxy terminates [inner TLS](agents-and-tools-mcp-tunnels-concepts.md#components) using a certificate signed by a CA you control. Generate both:
macOS / Linux
Windows (PowerShell)
macOS / Linux
``` shiki
openssl req -x509 -newkey rsa:2048 -nodes \
-keyout data/ca.key -out data/ca.crt \
-days 3650 -subj "/CN=mcp-tunnel-ca" \
-addext "basicConstraints=critical,CA:TRUE" \
-addext "keyUsage=critical,keyCertSign,cRLSign" \
-addext "subjectKeyIdentifier=hash"
cat > data/tls.ext < hello_server.py <<'EOF'
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)
@mcp.tool()
def hello(name: str = "world") -> str:
"""Say hello to someone."""
return f"Hello, {name}!"
if __name__ == "__main__":
mcp.run(transport="streamable-http")
EOF
```
Windows (PowerShell)
``` shiki
@'
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)
@mcp.tool()
def hello(name: str = "world") -> str:
"""Say hello to someone."""
return f"Hello, {name}!"
if __name__ == "__main__":
mcp.run(transport="streamable-http")
'@ | Set-Content -NoNewline -Encoding ascii -Path hello_server.py
```
5. 5
### Write the proxy config and compose file
macOS / Linux
Windows (PowerShell)
macOS / Linux
``` shiki
cat > config/mcp-proxy.yaml < docker-compose.yaml <<'EOF'
services:
mcp-proxy:
image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013
volumes:
- ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
- ./data:/data:ro
restart: unless-stopped
cloudflared:
image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
command: tunnel --no-autoupdate run --url http://localhost:8080
environment:
- TUNNEL_TOKEN
network_mode: "service:mcp-proxy"
restart: unless-stopped
hello-mcp:
image: python:3.13-slim
working_dir: /app
volumes:
- ./hello_server.py:/app/hello_server.py:ro
command: sh -c "pip install --quiet mcp && python hello_server.py"
restart: unless-stopped
EOF
```
Windows (PowerShell)
``` shiki
@"
listen_addr: ":8080"
tunnel_domain: $env:TUNNEL_DOMAIN
tls:
cert_file: /data/tls.crt
key_file: /data/tls.key
routes:
echo: http://hello-mcp:9000
"@ | Set-Content -NoNewline -Encoding ascii -Path config/mcp-proxy.yaml
@'
services:
mcp-proxy:
image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013
volumes:
- ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
- ./data:/data:ro
restart: unless-stopped
cloudflared:
image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
command: tunnel --no-autoupdate run --url http://localhost:8080
environment:
- TUNNEL_TOKEN
network_mode: "service:mcp-proxy"
restart: unless-stopped
hello-mcp:
image: python:3.13-slim
working_dir: /app
volumes:
- ./hello_server.py:/app/hello_server.py:ro
command: sh -c "pip install --quiet mcp && python hello_server.py"
restart: unless-stopped
'@ | Set-Content -NoNewline -Encoding ascii -Path docker-compose.yaml
```
6. 6
### Start it
macOS / Linux
Windows (PowerShell)
macOS / Linux
``` shiki
docker compose up -d
docker compose logs mcp-proxy | grep "route configured"
docker compose logs cloudflared | grep "Registered tunnel connection"
```
Windows (PowerShell)
``` shiki
docker compose up -d
docker compose logs mcp-proxy | Select-String "route configured"
docker compose logs cloudflared | Select-String "Registered tunnel connection"
```
You should see one `route configured` line for `echo` and four `Registered tunnel connection` lines. The containers take a few seconds to start; rerun the log commands if they come back empty.
7. 7
### Call it from Claude
In the Console, go to the [Sessions](../Other/playground.md) page (`platform.claude.com/sessions`) and create a session. In the agent picker choose **Create new agent**, give the agent a name, and keep the pre-filled model. Click **+ MCP Server**, select your tunnel, set **Subdomain** to `echo` and **Path** to `mcp`. Then ask:
> Use the hello tool to greet tunnel.
You should see a tool call followed by its result.
## Next steps
The tunnel is verified end to end. To swap in your own MCP server, add it to `docker-compose.yaml` (or run it on the same Docker network), add a route for it in `config/mcp-proxy.yaml`, then restart the proxy (`docker compose restart mcp-proxy`).
For production deployments:
[Deploy with Docker Compose](agents-and-tools-mcp-tunnels-deploy-compose.md)
Hardened single-host deployment, with or without programmatic access.
[Deploy with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md)
Kubernetes deployment with automatic credential management.
---
## MCP tunnels reference - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference
Path: 04-API-Reference/Agents-Tools/agents-and-tools-mcp-tunnels-reference.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Freference)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
[Overview](agents-and-tools-mcp-tunnels-overview.md)[Architecture and components](agents-and-tools-mcp-tunnels-concepts.md)[Quickstart](agents-and-tools-mcp-tunnels-quickstart.md)[Manage in the Console](agents-and-tools-mcp-tunnels-console.md)[Deploy with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md)[Deploy with Docker Compose](agents-and-tools-mcp-tunnels-deploy-compose.md)[Security](agents-and-tools-mcp-tunnels-security.md)[Troubleshooting](agents-and-tools-mcp-tunnels-troubleshooting.md)[Reference](agents-and-tools-mcp-tunnels-reference.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)MCP tunnels
# MCP tunnels reference
Copy page
Proxy configuration fields, the Tunnels REST API, certificate requirements, and the setup component.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
## Proxy configuration
The [proxy](agents-and-tools-mcp-tunnels-concepts.md#components) reads its configuration from `/etc/mcp-gateway/config.yaml` (Compose) or the rendered ConfigMap (Helm, populated from `gateway.config.*`).
| Field | Description | Default |
|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| `listen_addr` | Address and port to listen on. | Required |
| `log_level` | Logging verbosity: `debug`, `info`, `warn`, or `error`. | `info` |
| `shutdown_timeout` | How long to wait for in-flight requests during graceful shutdown. | `30s` |
| `tunnel_domain` | Base domain assigned to the tunnel. When set, route lookup strips this suffix from incoming hostnames so `routes` keys can be bare subdomains (`wiki`). When empty, `routes` keys must be exact full hostnames. | Required when `routes` keys are bare subdomains |
| `tls.cert_file` | Path to the server TLS certificate. | Required |
| `tls.key_file` | Path to the server TLS private key. | Required |
| `routes` | Map of subdomain or full hostname to upstream URL. See [Route matching](#route-matching). | Required |
| `upstream.allowed_ips` | IPv4 CIDR ranges or single addresses the proxy is permitted to connect to. Mutually exclusive with `disable_ip_validation`. | RFC1918 private ranges |
| `upstream.disable_ip_validation` | Disable upstream IP validation entirely. Mutually exclusive with `allowed_ips`. | `false` |
| `upstream.tls.ca_file` | CA bundle for validating upstream TLS. | None |
| `upstream.tls.include_system_cas` | Also trust the system CA bundle for upstream TLS. | `false` |
For `https://` upstream routes, set at least one of `upstream.tls.ca_file` or `upstream.tls.include_system_cas`; otherwise the proxy has no trust anchor for the upstream certificate.
### Route matching
`routes` is a flat string map (`map[string]string`), not a list. The proxy looks up the incoming hostname by exact match first, then by stripping the `tunnel_domain` suffix and matching the remaining subdomain. The match considers only the hostname; the request path and query string are forwarded to the [upstream MCP server](agents-and-tools-mcp-tunnels-concepts.md#components) unchanged.
Each upstream value must be exactly `scheme://host:port`. The port is mandatory. Including a path is rejected at config load with `invalid upstream (must be scheme://host:port)`.
## Tunnels API
The Tunnels REST API lives at `/v1/tunnels` and supports creating, listing, and archiving tunnels, registering CA certificates, and revealing or rotating the tunnel token. See the [Tunnels API reference](../Endpoints/http-beta-tunnels-list.md) for all endpoints, request and response schemas, and examples.
The previous Admin API surface at `/v1/organizations/tunnels` (beta header `mcp-tunnels-2026-05-19`, scope `org:manage_tunnels`) continues to work during a migration window and remains documented in the [Admin API reference](../Admin/beta-organization-mcp-tunnels.md) with a deprecation notice. To migrate, update the path to `/v1/tunnels`, the beta header to `mcp-tunnels-2026-06-22`, and your WIF token scope to `workspace:manage_tunnels`.
All MCP tunnels endpoints require a bearer token with the `workspace:manage_tunnels` scope obtained through [Workload Identity Federation](../Other/manage-claude-workload-identity-federation.md). Admin API keys are not accepted.
Required headers on every request:
| Header | Value |
|---------------------|--------------------------------------------|
| `Authorization` | `Bearer ` (the WIF-exchanged token) |
| `anthropic-version` | `2023-06-01` |
| `anthropic-beta` | `mcp-tunnels-2026-06-22` |
## Certificate requirements
The [setup component](agents-and-tools-mcp-tunnels-concepts.md#components) generates compliant certificates automatically. These requirements apply only if you issue certificates through your own PKI.
### CA certificate
Upload with `POST /v1/tunnels/{tunnel_id}/certificates`. A tunnel can hold up to two active CA certificates at a time, which allows zero-downtime rotation.
- PEM-encoded, single certificate, up to 8 kB.
- `BasicConstraints` extension present with `CA:TRUE`, marked critical.
- `SubjectKeyIdentifier` extension present.
- `KeyUsage` includes `keyCertSign`.
- Within its validity period.
- RSA 2048-bit or larger, or ECDSA P-256 or larger, with a SHA-256 or stronger signature.
### Server certificate
Presented by the proxy during [inner TLS](agents-and-tools-mcp-tunnels-concepts.md#components).
- Signed directly by a registered CA (no intermediates).
- `AuthorityKeyIdentifier` extension present and matching the CA's `SubjectKeyIdentifier`.
- Subject Alternative Name includes a DNS name matching `.`. A wildcard `*.` covers all routes.
- If the `ExtendedKeyUsage` extension is present, it includes `serverAuth`.
- Within its validity period.
- RSA 2048-bit or larger, or ECDSA P-256 or larger, with a SHA-256 or stronger signature.
The setup component generates an ECDSA P-256 CA with five-year validity and an RSA 4096-bit server certificate with a wildcard SAN and 90-day validity.
## Setup component
The setup component ships inside the `mcp-proxy` image as the `setup` binary. Run it with `docker compose run --rm setup ` (Compose) or rely on the chart's hooks and CronJobs (Helm).
### `setup init`
Attaches to an existing tunnel (or creates one when no tunnel ID is supplied), then generates a CA and server certificate, registers the CA, retrieves the tunnel token, and writes all outputs to the destination.
| Flag | Description | Default |
|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| `--api-url` | Claude API base URL. Also read from `API_URL`. | Required |
| `--tunnel-id` | Tunnel ID to attach to (`tnl_...`). Also read from `TUNNEL_ID`. When omitted, a new tunnel is created; a tunnel ID already stored in the output is reused on re-runs. | None (create a tunnel) |
| `--output` | Output destination: `dir:/path` or `k8s-secret:NAME`. The Helm chart passes `k8s-secret:`. | `k8s-secret:mcp-tunnel` (auto-detected when running in a Kubernetes pod; required otherwise) |
| `--cert-duration` | Server certificate validity period. | `2160h` (90 days) |
| `--token-version` | Change-detection string. A new value triggers token rotation on re-run. The Helm chart and the Compose example both pass `1` as the initial value. | None |
The command authenticates through [Workload Identity Federation](../Other/manage-claude-workload-identity-federation.md). It reads `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_WORKSPACE_ID` (optional), and exactly one of `ANTHROPIC_IDENTITY_TOKEN_FILE` or `ANTHROPIC_IDENTITY_TOKEN`. See the [WIF reference](../Other/manage-claude-wif-reference.md) for the current semantics of these variables; the setup component derives the service account from the federation rule, so it does not require `ANTHROPIC_SERVICE_ACCOUNT_ID` separately.
### `setup renew-cert`
Issues a new server certificate signed by the stored CA. Makes no API calls.
| Flag | Description | Default |
|-------------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| `--output` | Output destination: `dir:/path` or `k8s-secret:NAME`. The Helm chart passes `k8s-secret:`. | `k8s-secret:mcp-tunnel` (auto-detected when running in a Kubernetes pod; required otherwise) |
| `--cert-duration` | New certificate validity period. | `2160h` (90 days) |
| `--renew-before` | Skip renewal if the existing certificate has more than this duration remaining. | `0` (always renew) |
Setting `--renew-before=720h` makes the command a no-op when more than 30 days of validity remain, so it's safe to run on a fixed schedule.
---
## MCP tunnels security - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/security
Path: 04-API-Reference/Agents-Tools/agents-and-tools-mcp-tunnels-security.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Fsecurity)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
[Overview](agents-and-tools-mcp-tunnels-overview.md)[Architecture and components](agents-and-tools-mcp-tunnels-concepts.md)[Quickstart](agents-and-tools-mcp-tunnels-quickstart.md)[Manage in the Console](agents-and-tools-mcp-tunnels-console.md)[Deploy with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md)[Deploy with Docker Compose](agents-and-tools-mcp-tunnels-deploy-compose.md)[Security](agents-and-tools-mcp-tunnels-security.md)[Troubleshooting](agents-and-tools-mcp-tunnels-troubleshooting.md)[Reference](agents-and-tools-mcp-tunnels-reference.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)MCP tunnels
# MCP tunnels security
Copy page
Hardening guidance, credential rotation, breach response, and teardown for MCP tunnel deployments.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
The tunnel architecture provides strong defaults (outbound-only connectivity, end-to-end encryption, and IP validation), but the overall security of your [tunnel stack](agents-and-tools-mcp-tunnels-concepts.md#components) also depends on how you configure and operate it. This page covers recommended hardening, breach response, and how to decommission a tunnel.
## Best practices
- **Require OAuth on every MCP server.** Configure each [upstream MCP server](agents-and-tools-mcp-tunnels-concepts.md#components) to require OAuth as described in the [MCP authorization spec](../../06-MCP-Tools/Spec-Archive/2025-11-25-basic-authorization.md). OAuth provides defense in depth on top of the tunnel's transport authentication and enables user-level authorization at the data layer.
- **Enable SSO for your organization.** Tunnels, federation rules, and service accounts are managed in the Claude Console. SSO enforces your identity provider's session controls on the admins who can change them.
- **Restrict `upstream.allowed_ips`.** Use the smallest CIDR ranges that cover your MCP servers. This is the [proxy](agents-and-tools-mcp-tunnels-concepts.md#components)'s primary SSRF defense.
- **Monitor logs.** Alert on warnings, errors, and unusual traffic patterns from the tunnel stack.
- **Rotate credentials.** Rotate the server certificate and tunnel token on a regular schedule, and immediately if you suspect compromise.
- **Keep images updated.** Track new proxy releases and pin images by SHA-256 digest.
- **Limit network reach.** The proxy and [cloudflared](agents-and-tools-mcp-tunnels-concepts.md#components) should only be able to reach the destinations listed in the [network requirements](agents-and-tools-mcp-tunnels-overview.md#network-requirements). Use NetworkPolicy (Kubernetes) or host firewall rules (Compose).
- **Limit MCP server scope.** Each server should expose only the tools and data required for its purpose.
- **Protect credentials at rest.** Apply your organization's secrets-management practices to private keys and tunnel tokens.
## Respond to a suspected breach
If you believe your tunnel token, TLS keys, or proxy host has been compromised:
1. 1
### Stop the tunnel stack
Helm
Docker Compose
Helm
``` shiki
helm uninstall mcp-tunnel -n mcp-tunnel
```
Docker Compose
``` shiki
docker compose down --timeout 0
```
2. 2
### Detach the upstream MCP servers
Remove the upstream MCP servers from any Managed Agent sessions that use them, and stop passing their URLs in the `mcp_servers` block of Messages API requests.
3. 3
### Archive the tunnel
Archiving invalidates the tunnel token and detaches the domain. In the Console, [archive the tunnel](agents-and-tools-mcp-tunnels-console.md#archive-a-tunnel) from the **MCP tunnels** list. To archive over the API instead, see [Archive a tunnel](../Endpoints/http-beta-tunnels-archive.md).
4. 4
### Contact Anthropic
Report the suspected compromise to Anthropic support.
5. 5
### Rotate downstream credentials
Re-provision a fresh tunnel and rotate any OAuth tokens that the affected MCP servers issued.
6. 6
### Review logs before restoring service
Inspect proxy, cloudflared, and MCP server logs for the window of suspected compromise before bringing the new tunnel online.
## Tear down a tunnel
Follow these steps to decommission a tunnel and remove all stored credentials.
1. 1
### Stop the tunnel stack
Helm
Docker Compose
Helm
``` shiki
helm uninstall mcp-tunnel -n mcp-tunnel
```
Docker Compose
``` shiki
docker compose down
```
2. 2
### Archive the tunnel
In the Console, [archive the tunnel](agents-and-tools-mcp-tunnels-console.md#archive-a-tunnel) from the **MCP tunnels** list.
3. 3
### Remove stored credentials
Helm
Docker Compose
Helm
With programmatic access, the setup component created a single Secret named after the release. Without programmatic access, you created `mcp-tunnel-token` and `mcp-tunnel-cert` yourself. Delete whichever apply:
``` shiki
kubectl -n mcp-tunnel delete secret \
mcp-tunnel mcp-tunnel-token mcp-tunnel-cert \
--ignore-not-found
```
Docker Compose
Private keys and certificates live in `data/`. The tunnel token lives in `data/tunnel-token` (programmatic flow) or in your shell environment (manual flow). The `config/` directory and `docker-compose.yaml` contain no secrets; keep them if you plan to re-provision, or remove them as well.
``` shiki
sudo rm -rf data
```
---
## Troubleshoot MCP tunnels - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting
Path: 04-API-Reference/Agents-Tools/agents-and-tools-mcp-tunnels-troubleshooting.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmcp-tunnels%2Ftroubleshooting)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
[Overview](agents-and-tools-mcp-tunnels-overview.md)[Architecture and components](agents-and-tools-mcp-tunnels-concepts.md)[Quickstart](agents-and-tools-mcp-tunnels-quickstart.md)[Manage in the Console](agents-and-tools-mcp-tunnels-console.md)[Deploy with Helm](agents-and-tools-mcp-tunnels-deploy-helm.md)[Deploy with Docker Compose](agents-and-tools-mcp-tunnels-deploy-compose.md)[Security](agents-and-tools-mcp-tunnels-security.md)[Troubleshooting](agents-and-tools-mcp-tunnels-troubleshooting.md)[Reference](agents-and-tools-mcp-tunnels-reference.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)MCP tunnels
# Troubleshoot MCP tunnels
Copy page
Diagnose connectivity, TLS, IP validation, and OAuth routing issues in a tunnel stack.
Copy page
MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
A request through the tunnel can fail at one of three layers; diagnose them in order: the outbound connection to the [tunnel edge](agents-and-tools-mcp-tunnels-concepts.md#components), the [inner TLS](agents-and-tools-mcp-tunnels-concepts.md#components) from Anthropic to your [proxy](agents-and-tools-mcp-tunnels-concepts.md#components), then routing and IP validation toward the [upstream MCP server](agents-and-tools-mcp-tunnels-concepts.md#components).
## Quick reference
| Symptom | Cause | Fix |
|-------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| Tunnel doesn't appear in the agent **+ MCP Server** picker | The picker only lists tunnels in the session's workspace that have at least one active certificate. | Register a CA certificate, or open the session in the workspace the tunnel was created in. |
| Caller sees HTTP 500; [cloudflared](agents-and-tools-mcp-tunnels-concepts.md#components) logs `No ingress rules were defined` | cloudflared has no local target. | Add `--url http://localhost:8080` and `network_mode: "service:mcp-proxy"` to the cloudflared service. |
| Proxy logs `no route for host` | `tunnel_domain` doesn't match the assigned domain, or `config.yaml` was edited without restarting. | Set `tunnel_domain` to the exact domain shown on the tunnel detail page, then restart the proxy (`docker compose restart mcp-proxy`). |
| Proxy logs `IP validation failed: is not a private address` | Upstream MCP server resolves outside RFC1918. | See [Upstream IP validation](#upstream-ip-validation). |
| Proxy exits with `cannot unmarshal !!seq into map[string]string` | `routes` is a YAML list. | Use `routes: { name: http://host:port }`. |
| Proxy exits with `open /data/tls.key: permission denied` | The key is `0600`; the proxy container runs non-root. | `chmod 644 data/tls.key`. |
| `curl https://:8080` fails with `wrong version number` | Expected; the listener is plaintext WebSocket. TLS happens inside the WS stream. | Verify through a [Managed Agent or the Messages API](agents-and-tools-mcp-tunnels-overview.md#use-the-tunneled-mcp-servers) instead. |
The following sections cover failures that need more than a one-line fix.
## OAuth fails behind a source-IP allowlist
OAuth flows fail when your authorization server's source-IP allowlist blocks Anthropic's backend from reaching `/token`, `/register`, and the discovery endpoints. If you'd rather not allowlist Anthropic's egress ranges, you can route the backend-to-backend OAuth calls through the tunnel while keeping the browser-facing `/authorize` endpoint on your existing public hostname.
1. 1
### Add a proxy route for the authorization server
``` shiki
routes:
mcp: http://your-mcp-server:8080
auth: http://your-auth-server:8080
```
Restart the proxy after editing `routes` (`docker compose restart mcp-proxy`, or `helm upgrade`).
2. 2
### Serve split-endpoint discovery metadata
Your authorization server's `/.well-known/oauth-authorization-server` response should point `authorization_endpoint` at your existing allowlisted hostname and everything else at the tunnel:
``` shiki
{
"issuer": "https://auth.",
"authorization_endpoint": "https:///authorize",
"token_endpoint": "https://auth./token",
"registration_endpoint": "https://auth./register",
"code_challenge_methods_supported": ["S256"]
}
```
3. 3
### Point the MCP server at the tunnel issuer
Your MCP server's `/.well-known/oauth-protected-resource` response should reference the tunnel hostname as its authorization server:
``` shiki
{
"resource": "https://mcp.",
"authorization_servers": ["https://auth."]
}
```
With this configuration, the user's browser hits `/authorize` on your existing hostname (which your allowlist already permits), while Anthropic's backend reaches `/token`, `/register`, and the discovery documents through the tunnel.
## Setup component authentication failures
The [setup component](agents-and-tools-mcp-tunnels-concepts.md#components) (Helm Job or Compose `setup` service) authenticates to the Tunnels API by exchanging an OIDC JWT through your federation rule. When the exchange fails, see [Troubleshoot a failed exchange](../Other/manage-claude-wif-reference.md#troubleshoot-a-failed-exchange) in the Workload Identity Federation reference; the failure modes (subject, audience, issuer, JWKS, lifetime) are the same.
Tunnels-specific causes:
- The chart's default audience is `api.anthropic.com` (no scheme). If your rule's audience is `https://api.anthropic.com`, set `api.wif.audience` to match.
- A `403` from the Tunnels API after a successful exchange means the rule's scope doesn't include `workspace:manage_tunnels`, or the rule's service account isn't a member of the tunnel's workspace. Set the scope and add the service account to the workspace.
On Helm, the setup component runs as a pre-install hook Job. On failure, the Job is left behind for inspection (`kubectl logs job/mcp-tunnel-setup -n mcp-tunnel`). Helm doesn't manage hook resources, so delete it before retrying:
```python
helm uninstall mcp-tunnel -n mcp-tunnel
kubectl -n mcp-tunnel delete job mcp-tunnel-setup
```
## Tunnel won't connect
Check the cloudflared logs first. Common causes:
- The `TUNNEL_TOKEN` is missing, expired, or copied incorrectly.
- A firewall is blocking outbound TCP/UDP on port 7844 to the tunnel edge.
cloudflared may also log warnings about UDP receive buffer sizes; this is a QUIC tuning hint, not an error.
## Certificate errors
When Anthropic rejects the proxy's certificate during inner TLS, the proxy logs `tls handshake failed`. Verify that:
- The server certificate has not expired.
- The certificate's Subject Alternative Name matches `*.`.
- The signing CA is registered with Anthropic for this tunnel.
See the [certificate requirements](agents-and-tools-mcp-tunnels-reference.md#certificate-requirements) for the full validation rules.
## Upstream IP validation
For SSRF protection, the proxy only dials addresses in the RFC1918 private ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) by default. Only IPv4 is supported for the proxy-to-upstream connection. (The cloudflared-to-edge egress range in [Network requirements](agents-and-tools-mcp-tunnels-overview.md#network-requirements) is a different hop.)
If the proxy logs `IP validation failed: is not a private address`, the upstream hostname resolved outside that set. On Kubernetes, some managed distributions allocate the Service CIDR outside RFC1918; if `kubectl get svc kubernetes -n default -o jsonpath='{.spec.clusterIP}'` returns an address outside the private ranges, look up your cluster's Service CIDR and add it.
If the address is legitimate, add the narrowest covering CIDR to `upstream.allowed_ips`. Setting `allowed_ips` **replaces** the RFC1918 default rather than extending it, so include the private ranges your other upstream MCP servers use:
config/mcp-proxy.yaml
```python
upstream:
allowed_ips:
- 10.0.0.0/8
- 172.16.0.0/12
- 192.168.0.0/16
- 127.0.0.0/8 # loopback, for local testing only
```
Avoid `0.0.0.0/0` outside of local testing; it disables SSRF protection entirely.
---
## Not Found - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/memory-tool
Path: 04-API-Reference/Agents-Tools/agents-and-tools-memory-tool.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [CLI, SDKs, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fmemory-tool)
# Page not found
The requested page could not be found. These pages are close:
- [Memory tool](agents-and-tools-tool-use-memory-tool.md)Let Claude store and retrieve information across conversations by implementing the memory tool's file operations in your application.
- [Tool use with Claude](agents-and-tools-tool-use-overview.md)Connect Claude to external tools and APIs. See where tools execute, when Claude calls them, and which tool fits your task.
- [Tool reference](agents-and-tools-tool-use-tool-reference.md)Directory of Anthropic-provided server tools, client tools, and client toolsets, plus reference for optional tool definition properties.
---
## Remote MCP servers - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/remote-mcp-servers
Path: 04-API-Reference/Agents-Tools/agents-and-tools-remote-mcp-servers.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fremote-mcp-servers)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)MCP
# Remote MCP servers
Copy page
Connect Claude to third-party remote MCP servers through the MCP connector API. Browse example servers and review the steps to connect.
Copy page
Several companies have deployed remote MCP servers that developers can connect to by using the Anthropic MCP connector API. These servers expand the capabilities available to developers and end users by providing remote access to various services and tools through the MCP protocol.
The remote MCP servers listed below are third-party services designed to work with the Claude API. These servers are not owned, operated, or endorsed by Anthropic. Users should only connect to remote MCP servers they trust and should review each server's security practices and terms before connecting.
## Connecting to remote MCP servers
To connect to a remote MCP server:
1. Review the documentation for the specific server you want to use.
2. Ensure you have the necessary authentication credentials.
3. Follow the server-specific connection instructions provided by each company.
For more information about using remote MCP servers with the Claude API, see [MCP connector](agents-and-tools-mcp-connector.md).
Once connected, remote MCP tools follow the same triggering behavior as any other tool. See [When Claude uses MCP tools](agents-and-tools-mcp-connector.md#when-claude-uses-mcp-tools).
## Remote MCP server examples
[Ticket Tailor(opens in new tab)](https://help.tickettailor.com/en/articles/11892797-how-to-connect-ticket-tailor-to-your-favourite-ai-agent)
Event platform for managing tickets, orders & more
URL
``` inline-block
https://mcp.tickettailor.ai/mcp
```
[Linear(opens in new tab)](https://linear.app/docs/mcp)
Manage issues, projects & team workflows in Linear
URL
``` inline-block
https://mcp.linear.app/mcp
```
[Hugging Face(opens in new tab)](https://huggingface.co/settings/mcp)
Access the Hugging Face Hub and thousands of Gradio Apps
URL
``` inline-block
https://huggingface.co/mcp?login&gradio=none
```
[Blockscout(opens in new tab)](https://github.com/blockscout/mcp-server)
Access and analyze blockchain data
URL
``` inline-block
https://mcp.blockscout.com/mcp
```
[Close(opens in new tab)](https://help.close.com/v1/docs/en/mcp-server)
Connect Claude to Close CRM to securely access and act on your sales data
URL
``` inline-block
https://mcp.close.com/mcp
```
[Cloudflare Developer Platform(opens in new tab)](https://www.support.cloudflare.com/)
Build applications with compute, storage, and AI
URL
``` inline-block
https://bindings.mcp.cloudflare.com/mcp
```
[Egnyte(opens in new tab)](https://developers.egnyte.com/docs/Remote_MCP_Server)
Securely access and analyze Egnyte content
URL
``` inline-block
https://mcp-server.egnyte.com/mcp
```
[Figma(opens in new tab)](https://help.figma.com/hc/en-us/articles/32132100833559)
Generate diagrams and better code from Figma context
URL
``` inline-block
https://mcp.figma.com/mcp
```
[Guru(opens in new tab)](https://help.getguru.com/docs/connecting-gurus-mcp-server)
Search and interact with your company knowledge
URL
``` inline-block
https://mcp.api.getguru.com/mcp
```
[Jotform(opens in new tab)](https://www.jotform.com/developers/mcp/)
Create forms & analyze submissions inside Claude
URL
``` inline-block
https://mcp.jotform.com/mcp-app
```
[monday.com(opens in new tab)](https://developer.monday.com/apps/docs/mondaycom-mcp-integration)
Manage projects, boards, and workflows in monday.com
URL
``` inline-block
https://mcp.monday.com/mcp
```
[Notion(opens in new tab)](https://developers.notion.com/docs/mcp)
Connect your Notion workspace to search, update, and power workflows across tools
URL
``` inline-block
https://mcp.notion.com/mcp
```
[PayPal(opens in new tab)](https://mcp.paypal.com/)
Access PayPal payments platform
URL
``` inline-block
https://mcp.paypal.com/mcp
```
[Stripe(opens in new tab)](https://docs.stripe.com/mcp)
Payment processing and financial infrastructure tools
URL
``` inline-block
https://mcp.stripe.com
```
[Supabase(opens in new tab)](https://supabase.com/docs/guides/getting-started/mcp)
Manage databases, authentication, and storage
URL
``` inline-block
https://mcp.supabase.com/mcp
```
[Vercel(opens in new tab)](https://vercel.com/docs/mcp/vercel-mcp)
Analyze, debug, and manage projects and deployments
URL
``` inline-block
https://mcp.vercel.com/
```
[Wix(opens in new tab)](https://dev.wix.com/docs/sdk/articles/use-the-wix-mcp/about-the-wix-mcp)
Manage and build sites and apps on Wix
URL
``` inline-block
https://mcp.wix.com/mcp
```
[Coupler.io(opens in new tab)](https://help.coupler.io/article/592-coupler-local-mcp-server)
Access business data from hundreds of sources
URL
``` inline-block
https://mcp.coupler.io/mcp/
```
[Dice(opens in new tab)](https://www.dice.com/about/mcp)
Find active tech jobs on Dice
URL
``` inline-block
https://mcp.dice.com/mcp
```
[Miro(opens in new tab)](https://developers.miro.com/docs/miro-mcp)
Access and create new content on Miro boards
URL
``` inline-block
https://mcp.miro.com/
```
[Port IO(opens in new tab)](https://docs.port.io/ai-interfaces/port-mcp-server/overview-and-installation)
Search your context lake and safely run actions
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.port.io/ai-interfaces/port-mcp-server/overview-and-installation/?mcp-setup=claude®ion=eu#installing-port-mcp)
[Aiwyn Tax (formerly Column Tax)(opens in new tab)](https://docs.columntax.com/page/aiwyn-tax-mcp-server)
Estimate your federal & state taxes with Aiwyn's tax engine
URL
``` inline-block
https://mcp.columnapi.com/mcp
```
[Circleback(opens in new tab)](https://circleback.ai/docs/mcp)
Search and access context from meetings
URL
``` inline-block
https://app.circleback.ai/api/mcp
```
[Clarify(opens in new tab)](https://docs.clarify.ai/en/articles/13367278-clarify-mcp)
Query your CRM. Create records. Ask anything.
URL
``` inline-block
https://api.clarify.ai/mcp
```
[Clarity AI(opens in new tab)](https://clarity-sfdr20-mcp.pro.clarity.ai/)
Simulate fund classifications under proposed SFDR 2.0
URL
``` inline-block
https://clarity-sfdr20-mcp.pro.clarity.ai/mcp
```
[Day AI(opens in new tab)](https://day.ai/mcp)
Know everything about your prospects & customers with CRMx
URL
``` inline-block
https://day.ai/api/mcp
```
[ICD-10 Codes(opens in new tab)](https://claude.com/resources/tutorials/using-the-icd-10-connector-in-claude)
Access ICD-10-CM and ICD-10-PCS code sets
URL
``` inline-block
https://hcls.mcp.claude.com/icd10_codes/mcp
```
[DevRev(opens in new tab)](https://support.devrev.ai/en-US/devrev/article/ART-21859-remote-mcp-server)
Search and update your company's knowledge graph
URL
``` inline-block
https://api.devrev.ai/mcp/v1
```
[DirectBooker(opens in new tab)](https://www.directbooker.ai/products/mcp-server-documentation)
Compare hotels, then book direct
URL
``` inline-block
https://www.directbooker.ai/claude
```
[Exa(opens in new tab)](https://docs.exa.ai/reference/exa-mcp)
Web Search + Code Docs Search
URL
``` inline-block
https://mcp.exa.ai/mcp
```
[Fathom(opens in new tab)](https://help.fathom.video/en/articles/11497793)
Your meetings, now part of every Claude conversation
URL
``` inline-block
https://api.fathom.ai/mcp
```
[Fireflies(opens in new tab)](https://guide.fireflies.ai/articles/8272956938-learn-about-the-fireflies-mcp-server-model-context-protocol)
Analyze and generate insights from meeting transcripts
URL
``` inline-block
https://api.fireflies.ai/mcp
```
[Fiscal.ai(opens in new tab)](https://docs.fiscal.ai/docs/guides/mcp-integration)
Clean Public Equity Fundamental Data
URL
``` inline-block
https://api.fiscal.ai/mcp/sse
```
[Granola(opens in new tab)](https://help.granola.ai/article/granola-mcp#set-up-guide)
The AI notepad for meetings
URL
``` inline-block
https://mcp.granola.ai/mcp
```
[Harmonic(opens in new tab)](https://support.harmonic.ai/en/articles/12785899-harmonic-mcp-server-getting-started-guide)
Discover, research, and enrich companies and people
URL
``` inline-block
https://mcp.api.harmonic.ai
```
[Klarity(opens in new tab)](https://github.com/Klarity-AI/klarity-mcp/blob/main/skills/klarity-process-context-graph/SKILL.md)
Explore your org's processes
URL
``` inline-block
https://architect-v2-api.klarity.ai/mcp
```
[Krisp(opens in new tab)](https://help.krisp.ai/hc/en-us/articles/25416265429660-Krisp-MCP-Supported-tools)
Add your meetings context via transcripts and notes
URL
``` inline-block
https://mcp.krisp.ai/mcp
```
[Lawve AI(opens in new tab)](https://lawve.ai/en/learn/mcp-setup)
Discover expert-written skills for legal work
URL
``` inline-block
https://mcp.lawve.ai/mcp
```
[Lorikeet(opens in new tab)](https://docs.lorikeetcx.ai/mcp/mcp-server)
A universal concierge for complex businesses
URL
``` inline-block
https://mcp.lorikeetcx.ai
```
[LunarCrush(opens in new tab)](https://lunarcrush.com/developers/api/ai)
Add real-time social media data to your searches
URL
``` inline-block
https://lunarcrush.ai/mcp
```
[Mem(opens in new tab)](https://docs.mem.ai/mcp/overview)
The AI notebook for everything on your mind
URL
``` inline-block
https://mcp.mem.ai/mcp
```
[Metaview(opens in new tab)](https://support.metaview.ai/integrations/mcp-integration/mcp-overview.mdx)
The AI platform for recruiting.
URL
``` inline-block
https://mcp.metaview.ai/mcp
```
[Otter.ai(opens in new tab)](https://help.otter.ai/hc/en-us/articles/35287607569687-Otter-MCP-Server)
Unlock your meeting intelligence
URL
``` inline-block
https://mcp.otter.ai/mcp
```
[Peec AI(opens in new tab)](https://docs.peec.ai/mcp/introduction)
Analyze your brand's visibility across LLMs
URL
``` inline-block
https://api.peec.ai/mcp
```
[Read AI(opens in new tab)](https://support.read.ai/hc/en-us/articles/49381158409491-MCP-Server)
Bring your meetings into Claude
URL
``` inline-block
https://api.read.ai/mcp
```
[Scholar Gateway(opens in new tab)](https://docs.scholargateway.ai)
Enhance responses with scholarly research and citations
URL
``` inline-block
https://connector.scholargateway.ai/mcp
```
[Scite(opens in new tab)](https://scite.ai/mcp)
Evidence-based answers grounded in research
URL
``` inline-block
https://api.scite.ai/mcp
```
[Sprouts Data Intelligence(opens in new tab)](https://support.sprouts.ai/en/articles/13384582-sprouts-mcp-server-documentation#h_541c149a52)
From query to qualified lead in seconds.
URL
``` inline-block
https://sprouts-mcp-server.kartikay-dhar.workers.dev
```
[Sybill(opens in new tab)](https://api.sybill.ai/docs/mcp.html)
Ask AI about your sales calls, deals & pipeline
URL
``` inline-block
https://mcp.sybill.ai/mcp
```
[Tray.ai(opens in new tab)](https://tray.ai/documentation/platform/artificial-intelligence/agent-gateway/connecting-clients)
Automate 700+ apps & workflows with governance
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://tray.ai/documentation/platform/artificial-intelligence/agent-gateway/connecting-clients)
[Vibe Prospecting(opens in new tab)](https://developers.explorium.ai/mcp-docs/agentsource-mcp)
Find company & contact data
URL
``` inline-block
https://vibeprospecting.explorium.ai/mcp
```
[Windsor.ai(opens in new tab)](https://windsor.ai/introducing-windsor-mcp/#method-1-using-claude-desktop-3)
Connect Meta Ads, Google Ads, TikTok Ads, LinkedIn Ads + 320 more
URL
``` inline-block
https://mcp.windsor.ai
```
[Era Context(opens in new tab)](https://era.app/help/mcp-server-era-context/)
Manage your personal finances using Claude
URL
``` inline-block
https://context.era.app
```
[Fellow.ai(opens in new tab)](https://help.fellow.ai/en/articles/12622641-fellow-s-mcp-server)
Chat with your meetings to uncover actionable insights
URL
``` inline-block
https://fellow.app/mcp
```
[Gamma(opens in new tab)](https://gamma.app/docs/Gamma-MCP-Server-Documentation-m6p43kobgzy15zj?mode=doc)
Create presentations, docs, socials, and sites with AI
URL
``` inline-block
https://mcp.gamma.app/mcp
```
[Lucid(opens in new tab)](https://help.lucid.co/hc/en-us/articles/42578801807508-Integrate-Lucid-with-AI-tools-using-the-Lucid-MCP-server)
Ideate, diagram, and align teams
URL
``` inline-block
https://mcp.lucid.app/mcp
```
[Natoma(opens in new tab)](https://docs.natoma.ai)
Access all your internal tools, enterprise apps & data.
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://natoma.app/?utm=claude)
[NetDocuments(opens in new tab)](https://support.netdocuments.com/)
Securely access your documents in NetDocuments
[Netlify(opens in new tab)](https://docs.netlify.com/build/build-with-ai/netlify-mcp-server/)
Create, deploy, manage, and secure websites on Netlify.
URL
``` inline-block
https://netlify-mcp.netlify.app/mcp
```
[ThoughtSpot Spotter(opens in new tab)](https://developers.thoughtspot.com/docs/mcp-integration#_add_mcp_server_to_the_mcp_clients_config)
Your AI data analyst, from question to trusted insights
URL
``` inline-block
https://agent.thoughtspot.app/mcp?api-version=latest
```
[AWS Marketplace(opens in new tab)](https://docs.aws.amazon.com/marketplace/latest/APIReference/marketplace-mcp-server.html)
Discover, evaluate, and buy solutions for the cloud
URL
``` inline-block
https://marketplace-mcp.us-east-1.api.aws/mcp
```
[Synthesize Bio(opens in new tab)](https://app.synthesize.bio/mcp/docs)
Generate gene expression from a virtual human
URL
``` inline-block
https://app.synthesize.bio/api/mcp
```
[Kindora Funder Discovery(opens in new tab)](https://kindora.co/mcp)
Find funders who support causes like yours
URL
``` inline-block
https://kindora-mcp.azurewebsites.net/mcp/
```
[Omni Analytics(opens in new tab)](https://docs.omni.co/ai/mcp)
Query your data using natural language through Omni's semantic model
URL
``` inline-block
https://callbacks.omniapp.co/callback/mcp
```
[Send(opens in new tab)](https://www.send.co/mcp/docs)
Create shareable documents, one-pagers, and decks
URL
``` inline-block
https://www.send.co/mcp
```
[Shapes(opens in new tab)](https://mcp.shapes.co)
Analyse your live people data, right in Claude
URL
``` inline-block
https://mcp.shapes.co/mcp
```
[Lloyd by The L Suite(opens in new tab)](https://docs.google.com/document/d/1glRh-BdxnTPxzM1cZLzCcmlgIW5-dQ4-NnnStfhI6vk/edit?tab=t.0#heading=h.hgwkvyizzdb3)
Inhouse counsel insights for members of The L Suite
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.google.com/forms/d/e/1FAIpQLSeK2KFt1G1XbqgQdp2J-cvnLDtiUDigSsTjFH-Hk_B-Va0pRw/viewform?usp=publish-editor)
[TopCounsel by The L Suite(opens in new tab)](https://docs.google.com/document/d/1jcekau3Njlc5XfSspSdSGu7qSgKvM00M6DrYm91ZTzA/edit?tab=t.0#heading=h.hgwkvyizzdb3)
Outside Counsel recommendations from Inhouse Counsel
URL
``` inline-block
https://api.techgc.co/api/mcp/topcounsel
```
[ActiveCampaign(opens in new tab)](https://developers.activecampaign.com/page/mcp)
Autonomous marketing to transform how you work
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://developers.activecampaign.com/page/mcp)
[Adobe Experience Manager(opens in new tab)](https://www.adobe.com/go/aem_claude_mcp_docs)
Manage your Adobe Experience Manager content
URL
``` inline-block
https://mcp.adobeaemcloud.com/adobe/mcp/aem
```
[Ahrefs(opens in new tab)](https://docs.ahrefs.com/docs/mcp/reference/introduction)
SEO & AI search analytics
URL
``` inline-block
https://api.ahrefs.com/mcp/mcp
```
[AirOps(opens in new tab)](https://docs.airops.com/mcp)
Craft content that wins AI search
URL
``` inline-block
https://app.airops.com/mcp
```
[Airtable(opens in new tab)](https://support.airtable.com/docs/using-the-airtable-mcp-server)
Bring your structured data to Claude
URL
``` inline-block
https://mcp.airtable.com/mcp
```
[Airwallex Developer(opens in new tab)](https://www.airwallex.com/docs/developer-tools/ai/developer-mcp)
Integrate with the Airwallex Platform using Claude
URL
``` inline-block
https://mcp-demo.airwallex.com/developer
```
[AllTrails(opens in new tab)](https://support.alltrails.com/hc/en-us/articles/47343827423764-AllTrails-integrations-with-AI-services)
Find your next hike
URL
``` inline-block
https://www.alltrails.com/mcp
```
[Attio(opens in new tab)](https://docs.attio.com/mcp/overview)
Search, manage, and update your Attio CRM from Claude
URL
``` inline-block
https://mcp.attio.com/mcp
```
[Audible(opens in new tab)](https://help.audible.com/s/article/connect-audible-to-claude?language=en_US)
Ask for audiobook recommendations
URL
``` inline-block
https://mcp.audible.com/mcp
```
[Autodesk Product Help(opens in new tab)](https://help.autodesk.com/view/ADSKMCP/ENU/?guid=ADSKMCP_KnowledgeMcp_autodesk_product_help_mcp_server_html)
Securely access Autodesk's help documentation
URL
``` inline-block
https://developer.api.autodesk.com/knowledge/public/v1/mcp
```
[Base44(opens in new tab)](https://docs.base44.com/developers/backend/overview/mcp-server)
Build and manage Base44 apps
URL
``` inline-block
https://app.base44.com/mcp
```
[Benchling(opens in new tab)](https://help.benchling.com/hc/en-us/articles/40342713479437-Benchling-MCP)
Connect to R&D data, source experiments, and notebooks
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://help.benchling.com/hc/en-us/articles/40342713479437-Benchling-MCP)
[BioRender(opens in new tab)](https://help.biorender.com/hc/en-gb/articles/30870978672157-How-to-use-the-BioRender-MCP-connector)
Search for and use scientific templates and icons
URL
``` inline-block
https://mcp.services.biorender.com/mcp
```
[Bitly(opens in new tab)](https://dev.bitly.com/bitly-mcp/)
Shorten links, generate QR Codes, and track performance
URL
``` inline-block
https://api-ssl.bitly.com/v4/mcp
```
[MT Newswires(opens in new tab)](https://console.blueskyapi.com/docs/EDGE/news/MT_NEWSWIRES_Global#mcp)
Trusted real-time global financial news provider
URL
``` inline-block
https://vast-mcp.blueskyapi.com/mcp
```
[Booking.com(opens in new tab)](https://developers.booking.com/mcp/booking-connector/about)
Find hotels, homes and more
URL
``` inline-block
https://demandapi-mcp.booking.com/v1/mcp/8132308
```
[Box(opens in new tab)](https://developer.box.com/guides/box-mcp)
Search, edit and get insights on your Box content
URL
``` inline-block
https://mcp.box.com
```
[Brex(opens in new tab)](https://www.brex.com/support/using-brex-in-ai-apps)
Intelligent finance automation
URL
``` inline-block
https://api.brex.com/mcp
```
[Orion by Gravity(opens in new tab)](http://docs.runorion.com/)
Get insights from your autonomous AI analyst
URL
``` inline-block
https://g.runorion.com/mcp
```
[Calendly(opens in new tab)](https://help.calendly.com/hc/en-us/articles/36734570264855-Connect-Calendly-to-your-AI-tools-with-Calendly-MCP)
Manage event types, availability, and bookings.
URL
``` inline-block
https://mcp.calendly.com
```
[Canva(opens in new tab)](https://www.canva.dev/docs/connect/canva-mcp-server-setup/)
Search, create, autofill, and export Canva designs
URL
``` inline-block
https://mcp.canva.com/mcp
```
[Carta(opens in new tab)](https://docs.carta.com/api-platform/docs/claude-plugins-setup)
The connected ERP for private capital
URL
``` inline-block
https://mcp.app.carta.com/mcp
```
[CB Insights(opens in new tab)](https://mcp.cbinsights.com)
Predictive intelligence on private companies
URL
``` inline-block
https://mcp.cbinsights.com
```
[CData Connect AI(opens in new tab)](https://cloud.cdata.com/docs/Claude-Client.html)
Managed MCP platform for 350 sources
URL
``` inline-block
https://mcp.cloud.cdata.com/mcp
```
[Microsoft 365(opens in new tab)](../../14-Connectors/enabling-and-using-the-microsoft-365-connector.md)
Access your company's SharePoint, OneDrive, Outlook, and Teams directly in Claude
URL
``` inline-block
https://microsoft365.mcp.claude.com/mcp
```
[PubMed(opens in new tab)](https://support.claude.com/en/)
Search biomedical literature from PubMed
URL
``` inline-block
https://pubmed.mcp.claude.com/mcp
```
[Clay(opens in new tab)](https://www.notion.so/clayrun/Clay-Claude-MCP-Server-Documentation-2ef7e66eb01480c9820de48041591aeb?showMoveTo=true&saveParent=true)
Find prospects. Research accounts. Personalize outreach
URL
``` inline-block
https://api.clay.com/v3/mcp
```
[Clerk(opens in new tab)](https://clerk.com/docs/guides/ai/mcp/clerk-mcp-server)
Add authentication, organizations, and billing
URL
``` inline-block
https://mcp.clerk.com/mcp
```
[ClickUp(opens in new tab)](https://help.clickup.com/hc/en-us/articles/33335772678423-What-is-ClickUp-MCP)
Project management & collaboration for teams & agents
URL
``` inline-block
https://mcp.clickup.com/mcp
```
[iManage Work(opens in new tab)](https://docs.imanage.com/cloud/mcpconnector-user-help/en-US/iManage_MCP_Connector_Help.html)
Governed knowledge. AI ready.
URL
``` inline-block
https://cloudimanage.com/mcp/work
```
[Cloudinary(opens in new tab)](https://cloudinary.com/documentation/cloudinary_llm_mcp#available_mcp_servers)
Manage, transform and deliver your images & videos
URL
``` inline-block
https://asset-management.mcp.cloudinary.com/sse
```
[CoinDesk(opens in new tab)](https://mcp.coindesk.com/)
Access Live & Historical Crypto Data, Indices
URL
``` inline-block
https://mcp.coindesk.com/mcp
```
[Consensus(opens in new tab)](https://docs.consensus.app/docs/mcp)
Explore scientific research
URL
``` inline-block
https://mcp.consensus.app/mcp
```
[Aurora(opens in new tab)](https://mcp-docs.ai.consilio.com)
Search your Consilio matters, docs, and more.
URL
``` inline-block
https://mcp.ai.consilio.com
```
[Contentsquare(opens in new tab)](https://support.contentsquare.com/hc/en-us/articles/41563169756945-Model-Context-Protocol-MCP)
Experience analytics platform for digital businesses
URL
``` inline-block
https://api.contentsquare.com/mcp
```
[Context7(opens in new tab)](https://context7.com/docs/overview)
Up-to-date docs for LLMs and AI code editors
URL
``` inline-block
https://mcp.context7.com/mcp
```
[CourtListener(opens in new tab)](https://github.com/freelawproject/courtlistener-api-client/blob/main/MCP_README.md)
Legal research across millions of court records
URL
``` inline-block
https://mcp.courtlistener.com/
```
[Courtroom5(opens in new tab)](https://courtroom5.com/claude)
Civil legal guidance for self-represented litigants
URL
``` inline-block
https://mcp.courtroom5.com/v1
```
[Intuit Credit Karma(opens in new tab)](https://support.creditkarma.com/s/article/Intuit-Credit-Karma-on-Claude-and-ChatGPT)
Credit score factors & insights
URL
``` inline-block
https://anthropic.mcp.creditkarma.com/mcp
```
[Crossbeam(opens in new tab)](https://help.crossbeam.com/en/articles/12601327-crossbeam-mcp-server-beta)
Explore partner data and ecosystem insights in Claude
URL
``` inline-block
https://mcp.crossbeam.com
```
[Crypto.com(opens in new tab)](https://mcp.crypto.com/docs)
Real time prices, orders, charts, and more for crypto
URL
``` inline-block
https://mcp.crypto.com/market-data/mcp
```
[Daloopa(opens in new tab)](https://docs.daloopa.com/docs/daloopa-mcp#/)
Financial fundamental data and KPIs with hyperlinks
URL
``` inline-block
https://mcp.daloopa.com/server/mcp
```
[Databricks(opens in new tab)](https://docs.databricks.com/aws/en/generative-ai/mcp/connect-external-services)
Managed MCP servers with Unity Catalog and Mosaic AI
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.databricks.com/aws/en/generative-ai/mcp/connect-external-services)
[Datadog(opens in new tab)](https://docs.datadoghq.com/bits_ai/mcp_server/)
Debug and resolve issues using Datadog telemetry
[Datasite(opens in new tab)](https://app.global.datasite.com/dev-portal/guides/mcp-server)
Manage your M&A data room from Claude
URL
``` inline-block
https://mcp.global.datasite.com/mcp
```
[Definely(opens in new tab)](https://help.definely.com/en/articles/634922-definely-connector-for-claude-user-guide)
Structured contract review tools for legal teams
URL
``` inline-block
https://mcp.app.definely.com
```
[Descript(opens in new tab)](https://help.descript.com/hc/en-us/articles/45008080343053-Connect-Descript-to-Claude)
Import, edit, or create video with prompts
URL
``` inline-block
https://api.descript.com/v2/mcp/claude
```
[Descrybe Legal Engine(opens in new tab)](https://app.descrybe.com/connect/docs)
Ground your work in clean, structured U.S. primary law
URL
``` inline-block
https://mcp.descrybe.com/mcp
```
[Digits(opens in new tab)](https://help.digits.com/business-connections/digits-mcp-claude)
Track and analyze your finances with Digits
URL
``` inline-block
https://api.digits.com/mcp
```
[D&B Risk Analytics(opens in new tab)](https://view.highspot.com/viewer/2b3c0624606b4d64eb092106b47ad14c)
Execute risk workflows powered by the D&B Commercial Graph™
URL
``` inline-block
https://agents.riskanalytics.dnb.com/mcp
```
[DocuSeal(opens in new tab)](https://www.docuseal.com/guides/integrate-with-ai-agents-using-mcp)
Sign, send & manage documents with DocuSeal
URL
``` inline-block
https://docuseal.com/mcp
```
[Dovetail(opens in new tab)](https://developers.dovetail.com/docs/mcp)
Turn scattered feedback into decisions grounded in customer evidence
URL
``` inline-block
https://dovetail.com/api/mcp
```
[Dremio Cloud(opens in new tab)](https://docs.dremio.com/cloud/sonar/mcp-server/)
Analyze and get insights from your lakehouse data
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.dremio.com/cloud/sonar/mcp-server/)
[Enterpret(opens in new tab)](https://helpcenter.enterpret.com/en/articles/12665166-wisdom-mcp-server)
Get answers from unified feedback of your customers.
URL
``` inline-block
https://wisdom-api.enterpret.com/server/mcp
```
[Euler(opens in new tab)](https://mcp.eulerapp.com/public/docs)
Chat and manage your entire partner program.
URL
``` inline-block
https://mcp.eulerapp.com/mcp
```
[Everlaw(opens in new tab)](https://support.everlaw.com/hc/en-us/articles/50274473477915)
Search and explore your Everlaw database in Claude.
URL
``` inline-block
https://api.everlaw.com/v1/mcp
```
[Expedia(opens in new tab)](https://www.expedia.com/playground/mcp/doc/)
Plan trips, flights and hotels
URL
``` inline-block
https://www.expedia.com/mcp
```
[Fever Event Discovery(opens in new tab)](https://developer.feverup.com/)
Discover live entertainment events worldwide
URL
``` inline-block
https://data-search.apigw.feverup.com/mcp
```
[FMP(opens in new tab)](https://financialmodelingprep.com/developer/docs/mcp-server?utm_source=claude)
Comprehensive financial market data
URL
``` inline-block
https://financialmodelingprep.com/mcp
```
[G2(opens in new tab)](https://documentation.g2.com/docs/g2-mcp-server)
Bring real buyer signals into AI workflows
URL
``` inline-block
https://mcp.g2.com/mcp
```
[Monte Carlo(opens in new tab)](https://docs.getmontecarlo.com/docs/mcp-server)
Data & AI observability
URL
``` inline-block
https://mcp.getmontecarlo.com/mcp
```
[Glean(opens in new tab)](https://docs.glean.com/administration/platform/mcp/about)
Bring enterprise context to Claude and your AI tools
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.glean.com/administration/platform/mcp/about)
[Glovo(opens in new tab)](https://glovoapp.com/docs/en/legal/mcp/)
Anything delivered in minutes
URL
``` inline-block
https://api.glovoapp.com/discovery-mcp/mcp
```
[GoCardless(opens in new tab)](https://developer.gocardless.com/developer-tools/mcp/)
Build GoCardless payment API integrations
URL
``` inline-block
https://mcp.gocardless.com
```
[GoDaddy(opens in new tab)](https://developer.godaddy.com/mcp)
Search domains and check availability
URL
``` inline-block
https://api.godaddy.com/v1/domains/mcp
```
[Goodnotes(opens in new tab)](https://www.notion.so/goodnotes-team/Goodnotes-MCP-Server-Documentation-320b740273d28187a23ad52780a37620)
Turn AI insights into documents
URL
``` inline-block
https://claude-mcp-api.ml.goodnotes.com/mcp
```
[Google Cloud BigQuery(opens in new tab)](https://cloud.google.com/bigquery/docs/use-bigquery-mcp)
BigQuery: Advanced analytical insights for agents
URL
``` inline-block
https://bigquery.googleapis.com/mcp
```
[Google Compute Engine(opens in new tab)](https://cloud.google.com/docs)
MCP server for Google Compute Engine
URL
``` inline-block
https://compute.googleapis.com/mcp
```
[Google Calendar(opens in new tab)](https://developers.google.com/workspace/calendar)
Manage your schedule and coordinate meetings effortlessly
URL
``` inline-block
https://calendarmcp.googleapis.com/mcp/v1
```
[Google Drive(opens in new tab)](https://developers.google.com/workspace/drive)
Search, read, and upload files instantly
URL
``` inline-block
https://drivemcp.googleapis.com/mcp/v1
```
[Gmail(opens in new tab)](https://developers.google.com/workspace/gmail)
Draft replies, summarize threads, & search your inbox
URL
``` inline-block
https://gmailmcp.googleapis.com/mcp/v1
```
[GovTribe(opens in new tab)](https://docs.govtribe.com/user-guide/integrations/govtribe-mcp)
Search government procurement & spending data
URL
``` inline-block
https://govtribe.com/mcp
```
[Grain(opens in new tab)](https://developers.grain.com/mcp)
Put your meetings to work
URL
``` inline-block
https://api.grain.com/_/mcp
```
[Granted(opens in new tab)](https://grantedai.com/mcp)
Discover every grant opportunity in existence.
URL
``` inline-block
https://grantedai.com/api/mcp/mcp
```
[Guidepoint(opens in new tab)](https://clapi-developer.guidepoint.io/mcp/docs)
Real-time access to trusted expert knowledge
URL
``` inline-block
https://clapi.guidepoint.io/mcp-server/v1/mcp
```
[Gusto(opens in new tab)](https://docs.gusto.com/app-integrations/docs/mcp)
Query and analyze your Gusto data
URL
``` inline-block
https://mcp.api.gusto.com/anthropic
```
[Phoenix by HG Insights(opens in new tab)](https://phoenix.hginsights.com/docs/intro)
AI-powered B2B data intelligence & analytics
URL
``` inline-block
https://phoenix.hginsights.com/api/ai/mcp
```
[HubSpot(opens in new tab)](https://knowledge.hubspot.com/integrations/set-up-and-use-the-hubspot-connector-for-claude)
Chat with your CRM data to get personalized insights
URL
``` inline-block
https://mcp.hubspot.com/anthropic
```
[IBISWorld(opens in new tab)](https://help.ibisworld.com/en/articles/14627556-ibisworld-mcp-server-documentation)
Financials, risk data and analysis on 50,000 industries
URL
``` inline-block
https://mcp.ibisworld.com
```
[Interactive Brokers (IBKR)(opens in new tab)](https://www.interactivebrokers.com/lib/cstools/faq/#/content/1442566213)
Trade, invest, analyze, and manage global markets
URL
``` inline-block
https://api.ibkr.com/v1/api/mcp
```
[ICE Data Services(opens in new tab)](https://www.ice.com/ieoauoau)
Analyze U.S. fixed income trade and reference data
URL
``` inline-block
https://fids-mcp.ice.com/mcp
```
[IFTTT(opens in new tab)](https://ift.tt/ai_assistants)
Connect, control, and automate 1,000+ apps with IFTTT
URL
``` inline-block
https://ifttt.com/mcp
```
[Medidata(opens in new tab)](https://learn.medidata.com/en-US/bundle/mcp-server-documentation/page/medidata_mcp_server_documentation.html)
Clinical trial software and site ranking tools
URL
``` inline-block
https://mcp.imedidata.com/mcp
```
[Indeed(opens in new tab)](https://docs.indeed.com/mcp)
Search for jobs on Indeed
URL
``` inline-block
https://mcp.indeed.com/claude/mcp
```
[Instacart(opens in new tab)](https://docs.instacart.com/mcp_servers/)
Groceries and more delivered as fast as 30 minutes
URL
``` inline-block
https://fig-mcp.instacart.com/mcp
```
[Intercom(opens in new tab)](https://developers.intercom.com/docs/guides/mcp)
Access to Intercom data for better customer insights
URL
``` inline-block
https://mcp.intercom.com/mcp
```
[Intuit Mailchimp(opens in new tab)](https://mailchimp.com/help/use-mailchimp-connector-claude)
Create marketing campaigns
URL
``` inline-block
https://ai-inc.mailchimp.com/claude/mcp/v2
```
[Intuit QuickBooks(opens in new tab)](https://quickbooks.intuit.com/learn-support/en-us/help-article/accounting-bookkeeping/use-quickbooks-connector-claude/L3YBlo6Ht_US_en_US?uid=mmzgz9ag)
Business Finances made simple
URL
``` inline-block
https://ai-inc.quickbooks.intuit.com/v1/mcp
```
[Intuit TurboTax(opens in new tab)](https://ttlc.intuit.com/turbotax-support/en-us/help-article/tax-return/access-turbotax-tools-claude)
Estimate tax refunds and connect with live tax experts
URL
``` inline-block
https://ai-inc.turbotax.intuit.com/358A1C1B-F73B-46A7-B130-4B14916E6843/v1/mcp
```
[Ironclad Contracts(opens in new tab)](https://support.ironcladapp.com/hc/en-us/articles/39887091143319-Ironclad-MCP-Server)
Plain language search for faster contract answers
[Jentic(opens in new tab)](https://docs.jentic.com/guides/mcp/remote-mcp/)
One connection to access all your tools securely
URL
``` inline-block
https://api.jentic.com/mcp
```
[PlayMCP(opens in new tab)](https://www.notion.so/2189b97b4888803dbbdcef264e7eff58)
Connect and use PlayMCP servers in your toolbox
URL
``` inline-block
https://playmcp.kakao.com/mcp
```
[S&P Global(opens in new tab)](https://docs.kensho.com/llmreadyapi/mcp)
Query a range of S&P Global datasets
URL
``` inline-block
https://kfinance.kensho.com/integrations/mcp
```
[Ketryx(opens in new tab)](https://docs.ketryx.com/reference/ketryx-mcp-server)
Search and explore regulated software lifecycle data
URL
``` inline-block
https://app.ketryx.com/api/mcp
```
[Kiwi.com(opens in new tab)](https://mcp-install-instructions.alpic.cloud/servers/kiwi-com-flight-search)
Search flights in Claude
URL
``` inline-block
https://mcp.kiwi.com
```
[Klaviyo(opens in new tab)](https://developers.klaviyo.com/en/docs/klaviyo_mcp_server)
Report, strategize & create with real-time Klaviyo data
URL
``` inline-block
https://mcp.klaviyo.com/mcp?include-mcp-app=true
```
[lastminute.com(opens in new tab)](https://mcp.lastminute.com/docs)
Search, compare and book flights, dynamic packages (flight + hotel) and hotels across global airlines and hotel suppliers.
URL
``` inline-block
https://mcp.lastminute.com/mcp
```
[Legal Data Hunter(opens in new tab)](https://legaldatahunter.com/docs)
Search 23M+ legal docs in 160+ jurisdictions.
URL
``` inline-block
https://legaldatahunter.com/mcp
```
[LILT(opens in new tab)](https://support.lilt.com/kb/LILT-mcp)
High-quality translation with human verification
URL
``` inline-block
https://mcp.lilt.com/mcp
```
[Local Falcon(opens in new tab)](https://github.com/local-falcon/mcp)
AI visibility and local search intelligence platform
URL
``` inline-block
https://mcp.localfalcon.com
```
[LSEG(opens in new tab)](https://www.lseg.com/en/solutions/ai-finance-solutions/anthropic)
Access best in class data & analytics across a broad spectrum of asset classes.
URL
``` inline-block
https://api.analytics.lseg.com/lfa/mcp/server-cl
```
[Lumin(opens in new tab)](https://github.com/luminpdf/lumin-mcp-server)
Manage documents, send signature requests, and convert Markdown to PDF
URL
``` inline-block
https://mcp.luminpdf.com/mcp
```
[Lusha(opens in new tab)](https://docs.lusha.com/mcp-docs)
Find and enrich B2B contacts and companies
URL
``` inline-block
https://mcp.lusha.com/mcp/claude
```
[Magic Patterns(opens in new tab)](https://www.magicpatterns.com/docs/documentation/features/mcp-server/overview)
Discuss and iterate on Magic Patterns designs
URL
``` inline-block
https://mcp.magicpatterns.com/mcp
```
[MailerLite(opens in new tab)](https://developers.mailerlite.com/mcp/#how-mcp-works)
Turn Claude into your email marketing assistant
URL
``` inline-block
https://mcp.mailerlite.com/mcp
```
[Make(opens in new tab)](https://developers.make.com/mcp-server/)
Run Make scenarios and manage your Make account
URL
``` inline-block
https://mcp.make.com
```
[Malwarebytes(opens in new tab)](https://help.malwarebytes.com/hc/en-us/articles/47985341083675-Using-Malwarebytes-in-Claude)
Check links, phones, and emails for scams
URL
``` inline-block
https://scamguard.malwarebytes.com/claude/mcp
```
[Melon(opens in new tab)](https://tech.kakaoent.com/ai/using-melon-mcp-server-en/)
Browse music charts & your personalized music picks
URL
``` inline-block
https://mcp.melon.com/mcp/
```
[Mercury(opens in new tab)](https://docs.mercury.com/docs/connecting-mercury-mcp)
Search, analyze and understand your finances on Mercury
URL
``` inline-block
https://mcp.mercury.com/mcp
```
[Metabase(opens in new tab)](https://www.metabase.com/docs/latest/ai/mcp)
Query and explore your Metabase data
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://www.metabase.com/docs/latest/ai/mcp)
[Microsoft Learn(opens in new tab)](https://learn.microsoft.com/en-us/training/support/mcp)
Search trusted Microsoft docs to power your development
URL
``` inline-block
https://learn.microsoft.com/api/mcp
```
[Mintlify(opens in new tab)](https://www.mintlify.com/docs/ai/mintlify-mcp)
Search, read, and edit your documentation
URL
``` inline-block
https://mcp.mintlify.com
```
[Mixpanel(opens in new tab)](https://docs.mixpanel.com/docs/features/mcp)
Analyze, query, and manage your Mixpanel data
URL
``` inline-block
https://mcp.mixpanel.com/mcp
```
[Moody's(opens in new tab)](https://www.moodys.com/web/en/us/genai/model-context-protocol.html)
Risk insights, analytics, and decision intelligence
URL
``` inline-block
https://api.moodys.com/genai-ready-data/m1/mcp
```
[Morningstar(opens in new tab)](https://developer.morningstar.com/direct-web-services/documentation/mcp-server/morningstar-mcp-server)
Up-to-date investment and market insights
URL
``` inline-block
https://mcp.morningstar.com/mcp
```
[MotherDuck(opens in new tab)](https://motherduck.com/docs/sql-reference/mcp/)
Get answers from your data
URL
``` inline-block
https://api.motherduck.com/mcp
```
[Motion Creative Analytics(opens in new tab)](https://help.motionapp.com/en/articles/14315735-motion-mcp)
Analyze your Meta ad creative & competitor ad libraries
URL
``` inline-block
https://projects.motionapp.com/mcp
```
[MSCI(opens in new tab)](https://www.msci.com/downloads/web/msci-com/data-and-analytics/private-asset-solutions/ai-for-private-markets/msci-mcp-msci-connector-user-guide.pdf)
Turn data into insight
URL
``` inline-block
https://mcp.msci.com/mcp/v1.0/mcp
```
[NetSuite(opens in new tab)](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_7200233106.html)
Connect Claude to NetSuite data for analysis & insights
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://system.netsuite.com/mcp/mcpinfo.nl)
[Owkin(opens in new tab)](https://docs.owkin.com/core-features-and-usage)
Interact with AI agents built for biology
URL
``` inline-block
https://mcp.k.owkin.com/mcp
```
[PagerDuty(opens in new tab)](https://developer.pagerduty.com/docs/mcp-tooling-remote-server)
Manage incidents, services and on-call schedules
URL
``` inline-block
https://mcp.pagerduty.com/mcp
```
[PandaDoc(opens in new tab)](https://developers.pandadoc.com/docs/how-to-use-the-pandadoc-mcp-server)
Create, send, sign and track documents
URL
``` inline-block
https://mcp.pandadoc.com/v1/mcp
```
[Pigment(opens in new tab)](https://kb.pigment.com/docs/mcp-server)
Analyze business data
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://kb.pigment.com/docs/mcp-server)
[PitchBook Premium(opens in new tab)](https://help.pitchbook.com/s/article/PitchBook-Premium-for-Claude-by-Anthropic)
PitchBook data, embedded in the way you work.
URL
``` inline-block
https://premium.mcp.pitchbook.com/mcp
```
[Polar Analytics(opens in new tab)](https://intercom.help/polar-app/en/collections/17268490-polar-mcp)
Bring all your data in one place & connect it to Claude
URL
``` inline-block
https://api.polaranalytics.com/mcp
```
[Postman(opens in new tab)](https://github.com/postmanlabs/postman-mcp-server)
Give API context to your coding agents
URL
``` inline-block
https://mcp.postman.com/minimal
```
[Privacy.com(opens in new tab)](https://developers.privacy.com/docs/mcp-server)
Manage virtual cards and track your spending patterns
URL
``` inline-block
https://mcp.privacy.com
```
[Quartr(opens in new tab)](https://mcp.quartr.com/docs)
Financial data and AI infrastructure for company research.
URL
``` inline-block
https://mcp.quartr.com/mcp
```
[Quo(opens in new tab)](https://support.quo.com/core-concepts/integrations/mcp)
Surface call insights and missed opportunities
URL
``` inline-block
https://mcp.quo.com/mcp
```
[Ramp(opens in new tab)](https://docs.ramp.com/developer-api/v1/guides/ramp-mcp-remote)
Search, access, and analyze your Ramp financial data
URL
``` inline-block
https://ramp-mcp-remote.ramp.com/mcp
```
[Ramp Data(opens in new tab)](https://docs.ramp.com/developer-api/v1/ramp-data)
Search and analyze Ramp spend across 50,000+ businesses
URL
``` inline-block
https://mcp.ramp.com/ramp-data/anthropic/mcp
```
[Bigdata.com(opens in new tab)](https://docs.bigdata.com/mcp-reference)
Access real-time financial data
URL
``` inline-block
https://mcp.bigdata.com/
```
[Razorpay(opens in new tab)](https://razorpay.com/docs/mcp-server/?preferred-country=IN)
Turn Claude into your Razorpay Dashboard Assistant
URL
``` inline-block
https://mcp.razorpay.com/mcp
```
[Resy(opens in new tab)](https://www.americanexpress.com/content/dam/amex/en-us/credit-cards/benefits/resy/resy_mcp_app_claude.pdf)
Find and book restaurants instantly
URL
``` inline-block
https://apigw.americanexpress.com/dining/v1/mcp
```
[Retool(opens in new tab)](https://docs.retool.com/education/labs/resources/mcp)
Build production apps and manage Retool with AI agents
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.retool.com/education/labs/resources/mcp)
[Rillet(opens in new tab)](https://docs.api.rillet.com/docs/mcp)
Query your live GL and financials in plain English
URL
``` inline-block
https://api.rillet.com/mcp
```
[SandboxAQ(opens in new tab)](https://docs.aisim.sandboxaq.com/)
Large Quantitative Models for scientific discovery
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.aisim.sandboxaq.com/)
[Semrush(opens in new tab)](https://developer.semrush.com/api/introduction/semrush-mcp/)
SEO, market data, and brand visibility insights
URL
``` inline-block
https://mcp.semrush.com/claude/v1/mcp
```
[Shopify(opens in new tab)](https://help.shopify.com/en/manual/apps/connecting-ai-tools)
Build, manage, and analyze your Shopify store
URL
``` inline-block
https://setup.shopify.com/mcp
```
[Sigma(opens in new tab)](https://help.sigmacomputing.com/docs/use-sigma-mcp-server)
Query, search, and explore your data with Sigma
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://help.sigmacomputing.com/docs/use-sigma-mcp-server)
[SignNow(opens in new tab)](https://docs.signnow.com/docs/signnow/mcp-server)
Automate eSignature workflows directly from Claude
URL
``` inline-block
https://mcp-server.signnow.com/mcp
```
[Similarweb(opens in new tab)](https://docs.similarweb.com/api-v5/mcp/mcp-setup)
Real time web, mobile app, and market data.
URL
``` inline-block
https://mcp.similarweb.com
```
[Trimble SketchUp(opens in new tab)](https://help.sketchup.com/en/sketchup-claude-connector)
Create and iterate 3D models for use in SketchUp
URL
``` inline-block
https://api.sketchup.com/mcp/v1/sketchup/mcp
```
[Slack(opens in new tab)](https://docs.slack.dev/ai/mcp-server)
Send messages, create canvases, and fetch Slack data
URL
``` inline-block
https://mcp.slack.com/mcp
```
[Smartsheet(opens in new tab)](https://help.smartsheet.com/articles/2483663-use-smartsheet-connector-claude)
Analyze and manage Smartsheet data with Claude
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://help.smartsheet.com/articles/2483656-install-smartsheet-connector-claude#toc-get-started)
[Snowflake(opens in new tab)](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp)
Retrieve both structured and unstructured data
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.snowflake.com/en/user-guide/admin-account-identifier#label-account-name-find)
[Solve Intelligence(opens in new tab)](https://api.solveintelligence.com/guide/mcp/intro/)
Search, draft, and chart patents
URL
``` inline-block
https://api.solveintelligence.com/mcp/
```
[Sourcegraph(opens in new tab)](https://sourcegraph.com/docs/api/mcp#sourcegraph-mcp-server)
Give Claude full enterprise-scale codebase context.
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://sourcegraph.com/docs/api/mcp#sourcegraph-mcp-server)
[Splice(opens in new tab)](https://support.splice.com/en/articles/14442749-getting-started-with-the-splice-mcp-server-beta)
Search Splice's sounds catalog, build stacks & more!
URL
``` inline-block
https://mcp.splice.com/mcp
```
[Spotify(opens in new tab)](https://support.spotify.com/)
Music and podcast recommendations, just for you.
URL
``` inline-block
https://mcp-gateway-external-pilot.spotify.net/mcp
```
[AdisInsight(opens in new tab)](https://adisinsight-mcp.springer.com)
Pharmaceutical drug & clinical trial intelligence
URL
``` inline-block
https://adisinsight-mcp.springer.com/mcp
```
[Order by Cash App(opens in new tab)](https://goose-docs.ai/docs/mcp/cash-app-mcp/)
Discover local food spots and order with a conversation
URL
``` inline-block
https://connect.squareup.com/v2/mcp/cash-app
```
[Square(opens in new tab)](https://developer.squareup.com/docs/mcp)
Search and manage transaction, merchant, and payment data
URL
``` inline-block
https://mcp.squareup.com/sse
```
[StubHub(opens in new tab)](https://support.stubhub.com/articles/61000310240-using-stubhub-in-chatgpt-and-claude)
Find tickets on the World's Largest Ticket Marketplace
URL
``` inline-block
https://open-ai-app.stubhub.net/mcp
```
[Superhuman Mail(opens in new tab)](https://help.superhuman.com/hc/en-us/articles/49810745762067-Superhuman-Mail-MCP-Server-Beta)
The most productive email app ever, for Gmail & Outlook
URL
``` inline-block
https://mcp.mail.superhuman.com/mcp
```
[Supermetrics Marketing Analytics(opens in new tab)](https://mcp.supermetrics.com/docs)
Google Ads, Facebook Ads & 200+ marketing platforms
URL
``` inline-block
https://mcp.supermetrics.com/mcp
```
[SurveyMonkey(opens in new tab)](https://www.surveymonkey.com/apps/BKcduxPnkCN4NFCRokUYCw_3D_3D/details/)
Design surveys, collect responses, and analyze results
URL
``` inline-block
https://mcp.surveymonkey.com/mcp
```
[Taskrabbit Booking Assistance(opens in new tab)](https://docs.google.com/document/d/1tWm33lJx4JdwN-Joqk7vydxQHaRGLod68wdS4k_hY9w/edit?tab=t.edb6z98lya3r#heading=h.2j0sep9c1ren)
Find & book local Taskrabbit services near you
URL
``` inline-block
https://mcp.taskrabbit.com/mcp
```
[Tavily(opens in new tab)](https://docs.tavily.com/documentation/mcp)
Connect your AI agents to the web
URL
``` inline-block
https://mcp.tavily.com/mcp
```
[Third Bridge(opens in new tab)](https://www.thirdbridge.com/en-us/data-solutions/mcp)
Expert-led enhanced insights
URL
``` inline-block
https://ai.thirdbridge.com/mcp/sse
```
[CoCounsel Legal(opens in new tab)](https://legal-mcp.thomsonreuters.com/docs/connector-guide)
Thomson Reuters CoCounsel Legal, in Claude
URL
``` inline-block
https://legal-mcp.thomsonreuters.com/mcp
```
[Thumbtack(opens in new tab)](https://docs.google.com/document/d/1RmGske5ktjAi9d7Ayok_yOv3a6Z2RDBSxIlX7aC5OEM/edit?usp=sharing)
Find and hire local pros in Claude
URL
``` inline-block
https://mcp.thumbtack.com/mcp
```
[Tines(opens in new tab)](https://www.tines.com/docs/actions/templates/mcp-server/)
Securely deploy servers in a matter of seconds in Tines
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://www.tines.com/docs/actions/templates/mcp-server/)
[tldraw(opens in new tab)](https://tldraw.notion.site/tldraw-mcp-app)
Let Claude sketch, draw, and diagram with you
URL
``` inline-block
https://tldraw-mcp-app.tldraw.workers.dev/mcp
```
[Tripadvisor(opens in new tab)](https://www.tripadvisor.com)
Find your perfect hotel based on Tripadvisor reviews
URL
``` inline-block
https://production.ai-mcp-extensibility-prd.tamg.cloud/ogMvjY4De1G7CiHanMOAgddl/mcp
```
[Turkish Airlines(opens in new tab)](https://mcp.turkishtechlab.com/)
Search flights, plan trips, and manage bookings
URL
``` inline-block
https://mcp-app.turkishtechlab.com/mcp
```
[Twilio(opens in new tab)](https://www.twilio.com/docs/ai/mcp)
Build powerful communications and customer engagement
URL
``` inline-block
https://mcp.twilio.com/docs
```
[Uber(opens in new tab)](https://www.uber.com/legal/en/)
Get Uber price & time estimates for any ride option
URL
``` inline-block
https://mcp.uber.com/claude/rides-3p/mcp
```
[Uber Eats(opens in new tab)](https://www.ubereats.com)
Explore restaurants and dishes
URL
``` inline-block
https://mcp.ubereats.com/eats-claude/mcp
```
[Udemy Business(opens in new tab)](https://business-support.udemy.com/hc/en-us/articles/34213384429335-How-to-Integrate-the-Udemy-Business-MCP-Server-With-Your-AI-Tool#h_01K9CA42YGCV1AVXPY1RKABKP1)
Search and explore skill-building resources
URL
``` inline-block
https://api.udemy.com/mcp
```
[Pylon(opens in new tab)](https://support.usepylon.com/articles/2407390554-connecting-to-the-pylon-mcp-server?lang=en)
Search and manage Pylon support issues
URL
``` inline-block
https://mcp.usepylon.com/
```
[Verisk Underwriting Intelligence(opens in new tab)](https://www.verisk.com/resources/verisk-underwriting-intelligence/)
Ask questions. Get underwriting insights from Verisk.
URL
``` inline-block
https://gatewaymcp.verisk.com/underwriting/intelligencemcp/v1
```
[Verisk XactRestore(opens in new tab)](https://veriskpropertyestimatingsolutions.my.site.com/s/article/2622)
Natural-language estimating for XactRestore
URL
``` inline-block
https://xactrestore-xactremodelserver-usw2-prod.propsol.io/mcp
```
[Viator(opens in new tab)](https://docs.viator.com/partner-api/mcp/)
Book travel experiences around the world
URL
``` inline-block
https://exp-app-mcp.prod.ep.viator.com/mcp
```
[Visier(opens in new tab)](https://docs.visier.com/developer/agents/mcp/mcp-server.htm)
Find people, productivity and business impact insights
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.visier.com/developer/agents/mcp/mcp-server-set-up.htm)
[Webflow(opens in new tab)](https://developers.webflow.com/mcp/v1.0.0/reference/overview)
Manage Webflow CMS, pages, assets and sites
URL
``` inline-block
https://mcp.webflow.com/mcp
```
[Wolfram(opens in new tab)](https://www.wolfram.com/artificial-intelligence/mcp-service/)
Inject precise, real-time computation and knowledge
URL
``` inline-block
https://agenttools.wolfram.com/mcp
```
[WordPress.com(opens in new tab)](https://developer.wordpress.com/docs/mcp/)
Secure AI access to manage your WordPress.com sites
URL
``` inline-block
https://public-api.wordpress.com/wpcom/v2/mcp/v1
```
[Workable(opens in new tab)](https://workable.readme.io/reference/workable-mcp-server)
Your AI assistant for Hiring and HR — inside Workable
URL
``` inline-block
https://mcp.workable.com/mcp
```
[Workato(opens in new tab)](https://docs.workato.com/en/mcp.html)
Automate workflows and connect your business apps
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://app.workato.com/ai_hub/mcp)
[Wyndham Hotels and Resorts(opens in new tab)](https://www.wyndhamhotels.com/mcp-doc)
Discover the right Wyndham Hotel for you, faster
URL
``` inline-block
https://mcp.wyndhamhotels.com/claude/mcp
```
[Xero(opens in new tab)](https://central.xero.com/s/article/Connect-Xero-using-the-Xero-connector-in-Claude?userregion=true)
Access your Xero financials from any conversation
URL
``` inline-block
https://mcp.xero.com/mcp
```
[Yardi Virtuoso(opens in new tab)](https://help.virtuoso.ai/en/articles/13679727-yardi-virtuoso-mcp-technical-documentation-guide)
Real-time Yardi data & insights
URL
``` inline-block
https://mcp.virtuoso.ai/mcp
```
[Zapier(opens in new tab)](https://docs.zapier.com/mcp/home)
Automate workflows across thousands of apps via conversation
URL
``` inline-block
https://mcp.zapier.com/api/v1/connect
```
[ZipRecruiter(opens in new tab)](https://api.ziprecruiter.com/mcp/docs)
Job search made easy
URL
``` inline-block
https://api.ziprecruiter.com/mcp
```
[Zoho Books(opens in new tab)](https://help.zoho.com/portal/en/kb/mcp/getting-started/articles/zoho-mcp-help-documentation-29-9-2025)
Zoho Books MCP for Smart Finance Ops
[Zoho CRM(opens in new tab)](https://help.zoho.com/portal/en/kb/mcp/getting-started/articles/zoho-mcp-help-documentation-29-9-2025)
MCP Server for Zoho CRM Workflows
[Zoho Desk(opens in new tab)](https://help.zoho.com/portal/en/kb/mcp/getting-started/articles/zoho-mcp-help-documentation-29-9-2025)
Zoho Desk MCP for Customer Support Automation
[Zoho Projects(opens in new tab)](https://help.zoho.com/portal/en/kb/mcp/getting-started/articles/zoho-mcp-help-documentation-29-9-2025)
Zoho Projects MCP for Task & Project Automation
[ZoomInfo(opens in new tab)](https://docs.zoominfo.com/docs/zi-api-mcp-overview/)
Enrich contacts & accounts with GTM intelligence
URL
``` inline-block
https://mcp.zoominfo.com/mcp
```
[Tango(opens in new tab)](https://tango.makegov.com/docs/mcp/)
Search for US Government Contracting Data
URL
``` inline-block
https://govcon.dev/mcp
```
[Jam(opens in new tab)](https://jam.dev/docs/debug-a-jam/mcp)
Record screen and collect automatic context for issues
URL
``` inline-block
https://mcp.jam.dev/mcp
```
[Sentry(opens in new tab)](https://docs.sentry.io/product/sentry-mcp/)
Search, query, and debug errors intelligently
URL
``` inline-block
https://mcp.sentry.dev/mcp
```
[Stytch(opens in new tab)](https://stytch.com/docs/workspace-management/stytch-mcp)
Manage your Stytch Project
URL
``` inline-block
https://mcp.stytch.dev/mcp
```
[Craft(opens in new tab)](https://documents.craft.me/jWeCVJrSfxFRuA)
Notes & second brain
URL
``` inline-block
https://mcp.craft.do/my/mcp
```
[Alma(opens in new tab)](https://alma.food/mcp)
Your nutrition data, inside every Claude conversation.
URL
``` inline-block
https://mcp.alma.food
```
[MoSPI(opens in new tab)](https://www.datainnovation.mospi.gov.in/mospi-mcp)
India's official statistics via natural language
URL
``` inline-block
https://mcp.mospi.gov.in/
```
[Adobe for creativity(opens in new tab)](https://developer.adobe.com/adobe-for-creativity/)
Ideate, create, and deliver with Adobe pro tools
URL
``` inline-block
https://adobe-creativity.adobe.io/mcp
```
[Adobe Journey Optimizer(opens in new tab)](https://experienceleague.adobe.com/en/docs/journey-optimizer/using/content-management/combine/ajo-mcp)
Understand and troubleshoot your Journeys and Campaigns
URL
``` inline-block
https://ajo-mcp.adobe.io/mcp
```
[Adobe Marketing Agent(opens in new tab)](https://acrobat.adobe.com/id/urn:aaid:sc:AP:5799e952-be87-4829-b0c4-6f82ca8e8b8b)
Marketing campaign and audience insights from Adobe
URL
``` inline-block
https://aep-ai-ama.adobe.io/mcp
```
[Common Room(opens in new tab)](https://www.commonroom.io/docs/using-common-room/common-room-for-claude-connector-and-plugin/)
Your GTM Copilot
URL
``` inline-block
https://mcp.commonroom.io/mcp
```
[Customer.io(opens in new tab)](https://docs.customer.io/ai/mcp-server/)
Explore customer data and generate insights via Claude
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.customer.io/ai/mcp-server/)
[Eraser(opens in new tab)](https://docs.eraser.io/docs/mcp)
Generate, manage, and update Eraser diagrams and files
URL
``` inline-block
https://app.eraser.io/api/mcp
```
[Harness.io(opens in new tab)](https://github.com/harness/mcp-server)
Build, Ship and Secure your apps on Harness Platform
URL
``` inline-block
https://mcp.harness.io/mcp
```
[Honeycomb(opens in new tab)](https://docs.honeycomb.io/troubleshoot/product-lifecycle/beta/mcp/)
Query and explore observability data and SLOs
URL
``` inline-block
https://mcp.honeycomb.io/mcp
```
[incident.io(opens in new tab)](https://docs.incident.io/ai/remote-mcp)
See and manage everything in incident.io
URL
``` inline-block
https://mcp.incident.io/mcp
```
[n8n(opens in new tab)](https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference/)
Access and run your n8n workflows
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.n8n.io/advanced-ai/mcp/mcp_tools_reference/)
[Pendo(opens in new tab)](https://support.pendo.io/hc/en-us/articles/41102236924955)
Connect to Pendo for product and user insights
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://support.pendo.io/hc/en-us/articles/41102236924955)
[Sanity(opens in new tab)](https://www.sanity.io/docs/ai/mcp-server)
Create, query, and manage structured content in Sanity
URL
``` inline-block
https://mcp.sanity.io
```
[Starburst(opens in new tab)](https://docs.starburst.io/starburst-galaxy/ai-workflows/mcp-server.html)
Securely retrieve data from your federated data sources
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://docs.starburst.io/starburst-galaxy/ai-workflows/mcp-server.html)
[tldv(opens in new tab)](https://tldv.notion.site/tl-dv-MCP-Official-Documentation-330cce15f3ba80638f5ac0253e3b8fd4?source=copy_link)
Fetch Transcripts & Notes from Meet, Zoom & Teams
URL
``` inline-block
https://mcp.tldv.io/mcp
```
[Tropic(opens in new tab)](https://help.tropicapp.io/hc/en-us/articles/45502083594267-Using-Model-Context-Protocol-MCP-with-Tropic)
Save money on Software + AI contracts
URL
``` inline-block
https://app.tropicapp.io/mcp
```
[Unthread(opens in new tab)](https://docs.unthread.io/docs/unthread-ai/unthread-mcp)
Manage and automate your support tickets
URL
``` inline-block
https://app.unthread.io/api/mcp
```
[Zocks(opens in new tab)](https://help.zocks.io/en/articles/14075856-connect-to-the-zocks-mcp-server)
Analyze client conversations, patterns, and insights.
URL
``` inline-block
https://mcp.zocks.io/v1/mcp
```
[Trellis(opens in new tab)](https://support.trellis.law)
Claude for Trial Court Litigators
URL
``` inline-block
https://mcp.trellis.law/anthropic
```
[Todoist(opens in new tab)](https://github.com/Doist/todoist-ai)
Search, complete, and manage your tasks in Todoist
URL
``` inline-block
https://ai.todoist.net/mcp
```
[Relativity(opens in new tab)](https://help.relativity.com/topic.html?t=GLJ39)
Organize Data. Discover the Truth. Act on It.
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://help.relativity.com/topic.html?t=GLJ39)
[BoardWise(opens in new tab)](https://boardwise.online/mcp)
Calm board-defense guidance for licensed pros.
URL
``` inline-block
https://uakozrqrztgrgwoywxkx.supabase.co/functions/v1/mcp-server
```
[Candid(opens in new tab)](../../14-Connectors/using-the-candid-connector-in-claude.md)
Research nonprofits and funders using Candid's data
URL
``` inline-block
https://mcp.candid.org/mcp
```
[Learning Commons Knowledge Graph(opens in new tab)](https://docs.learningcommons.org/knowledge-graph/integrations/claude)
K-12 standards, skills, and learning progressions
URL
``` inline-block
https://kg.mcp.learningcommons.org/mcp
```
[Open Targets(opens in new tab)](https://github.com/opentargets/open-targets-platform-mcp)
Drug target discovery and prioritisation platform
URL
``` inline-block
https://mcp.platform.opentargets.org/mcp
```
[Synapse.org(opens in new tab)](https://github.com/susheel/synapse-mcp?tab=readme-ov-file#synapse-mcp-server)
Search and metadata tools for Synapse scientific data
URL
``` inline-block
https://mcp.synapse.org/mcp
```
[Chronograph(opens in new tab)](https://lp-help.chronograph.pe/article/735-chronograph-mcp)
Interact with your Chronograph data directly in Claude
URL
``` inline-block
https://ai.chronograph.pe/mcp
```
[Hex(opens in new tab)](https://learn.hex.tech/docs/administration/mcp-server)
Answer questions with the Hex agent
Requires a user-specific URL. [Get your URL here(opens in new tab)](https://learn.hex.tech/docs/administration/mcp-server#connect-to-claude)
[Zoom for Claude(opens in new tab)](https://developers.zoom.us/docs/mcp/zoom/)
Search, recap, and act on your Zoom meetings
URL
``` inline-block
https://mcp.zoom.us/mcp/zoom/streamable
```
**Looking for more?** [Find hundreds more MCP servers on GitHub](https://github.com/modelcontextprotocol/servers).
---
## Advisor tool - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-advisor-tool.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fadvisor-tool)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Advisor tool
Copy page
Pair a faster executor model with a higher-intelligence advisor model that provides strategic guidance mid-generation.
Copy page
The advisor tool lets a faster, lower-cost **executor model** consult a higher-intelligence **advisor model** mid-generation for strategic guidance. The advisor reads the full conversation, produces a plan or course correction, and the executor continues with the task.
This pattern fits long-horizon agentic workloads (coding agents, computer use, multistep research pipelines) where most turns are mechanical but having an excellent plan is crucial. You get close to advisor-solo quality while the bulk of token generation happens at executor-model rates. For measured results, including how the benefit shrinks as the executor's own capability approaches the advisor's, see [Optimizing for cost and intelligence](../../20-Models/about-claude-models-optimizing-for-cost-and-intelligence.md).
To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
## When to use it
The advisor fits these configurations:
- **You currently use Sonnet on complex tasks:** Add a higher-tier advisor. Opus keeps total cost similar or lower; Claude Fable 5.1 maximizes the quality lift.
- **You currently use Haiku and want a step up in intelligence:** Add an Opus or Fable advisor. Expect higher cost than Haiku alone, but lower than switching the executor to a larger model.
Results are task-dependent. Evaluate on your own workload.
The advisor is a weaker fit for single-turn Q&A (nothing to plan), pure pass-through model pickers where your users already choose their own cost and quality tradeoff, or workloads where every turn genuinely requires the advisor model's full capability.
## Quick start
The advisor tool is in beta. Include the beta header `advisor-tool-2026-03-01` in your requests.
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-sonnet-5",
max_tokens=4096,
betas=["advisor-tool-2026-03-01"],
tools=[
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5-5",
}
],
messages=[
{
"role": "user",
"content": "Build a concurrent worker pool in Go with graceful shutdown.",
}
],
)
print(response)
```
The response `content` includes an `advisor_tool_result` block carrying the advisor's guidance. With `claude-opus-5-5` as the advisor, as in this quick start, the block's `content` field is an `advisor_redacted_result` variant (encrypted; the executor reads it server-side, but your client does not). To see the advice text directly in your response, use `claude-opus-4-8` as the advisor model instead, which returns the plaintext `advisor_result` variant. See [Result variants](#result-variants) for both shapes side by side and which advisor models return which, and [Model compatibility](#model-compatibility) for the full list of valid pairs.
## How it works
When you add the advisor tool to your `tools` array, the executor model determines when to call it, like any other tool. When the executor calls the advisor:
1. The executor emits a [`server_tool_use`](agents-and-tools-tool-use-server-tools.md) block with `name: "advisor"` and an empty `input`. The executor signals timing, and the server supplies context.
2. Anthropic runs a separate inference pass on the advisor model server-side. The advisor runs under its own Anthropic-supplied system prompt and receives the executor's full transcript as quoted context in its input. That transcript includes your system prompt, the tool definitions, the prior turns and tool results, and the text the executor has produced so far in this turn.
3. The advisor's response returns to the executor as an `advisor_tool_result` block.
4. The executor continues generating, informed by the advice.
All of this occurs inside a single `/v1/messages` request, with no extra round trips on your side. The exception is a turn that pauses mid-call, which you resume with a follow-up request (see [Resuming a paused turn](#resuming-a-paused-turn)).
The advisor itself runs without tools and without context management. Its thinking blocks are dropped before the result returns. Only the advice text reaches the executor.
## Tool parameters
[TABLE]
The `caching` object has the shape `{"type": "ephemeral", "ttl": "5m" | "1h"}`. Unlike `cache_control` on content blocks, this is not a breakpoint marker. It is an on/off switch. The server determines where cache boundaries go.
The advisor tool also accepts the generic properties available on any tool definition: `cache_control`, `allowed_callers`, `defer_loading`, and `strict` (covered in [structured outputs](../Guides/build-with-claude-structured-outputs.md)). See the [Tool reference](agents-and-tools-tool-use-tool-reference.md#tool-definition-properties) for their semantics.
## Response structure
### Successful advisor call
When the advisor is called, a `server_tool_use` block is followed by an `advisor_tool_result` block in the assistant's content. The following example shows the plaintext `advisor_result` variant returned by a Claude Opus 4.8 advisor. The [Quick start](#quick-start) uses Claude Opus 5.5, which returns the encrypted `advisor_redacted_result` variant instead; see [Result variants](#result-variants) for both shapes side by side.
```python
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "Let me consult the advisor on this."
},
{
"type": "server_tool_use",
"id": "srvtoolu_abc123",
"name": "advisor",
"input": {}
},
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_result",
"text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
}
},
{
"type": "text",
"text": "Here's the implementation. I'm using a channel-based coordination pattern to avoid writer starvation..."
}
]
}
```
The `server_tool_use.input` is always empty. The server constructs the advisor's view from the full transcript automatically. Nothing the executor puts in `input` reaches the advisor.
### Result variants
The `advisor_tool_result.content` field is a discriminated union. For successful calls, the variant depends on the advisor model:
| Variant | Fields | Returned when |
|---------------------------|------------------------------------|---------------------------------------------------------------------|
| `advisor_result` | `text`, `stop_reason` | The advisor model returns plaintext (for example, Claude Opus 4.8). |
| `advisor_redacted_result` | `encrypted_content`, `stop_reason` | The advisor model returns encrypted output. |
Claude Sonnet 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Fable 5, Claude Mythos 5, and Claude Haiku 5.5 advisors return the encrypted `advisor_redacted_result`. Every other advisor model in the [compatibility table](#model-compatibility) returns the plaintext `advisor_result`. To read the advice text in your own responses, use an advisor that returns plaintext, such as `claude-opus-4-8`, where your executor's row in the [compatibility table](#model-compatibility) lists one. Claude Sonnet 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Fable 5, and Claude Mythos 5 executors pair only with advisors that return the encrypted form, so on those executors the advice text isn't readable in the response.
Here is the same request sent twice, identical except for the advisor `model` in the tool definition, showing both variants.
With `"model": "claude-opus-4-8"`, the advice is plaintext:
```python
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_result",
"text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
}
}
```
With `"model": "claude-opus-5-5"`, the advice is encrypted:
```python
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_redacted_result",
"encrypted_content": "EqQBCkYIBRgCIiQ5ZjE0N2M2OC0yYWIxLTRkZTktYjA3ZC1hZTUyMzkxYjhkMmU..."
}
}
```
Both result variants carry a `stop_reason` field when you set [`max_tokens`](#capping-advisor-output) on the tool definition, and omit it when you do not. It holds the advisor sub-call's stop reason, typically `"end_turn"`, or `"max_tokens"` when the cap is hit. The values match the top-level Messages API [`stop_reason`](../Guides/build-with-claude-handling-stop-reasons.md).
With `advisor_result`, the `text` field contains human-readable advice. With `advisor_redacted_result`, the `encrypted_content` field contains an opaque blob that you cannot read. On the next turn, the server decrypts it and renders the plaintext into the executor's prompt.
In both cases, round-trip the content verbatim on subsequent turns. If you switch advisor models mid-conversation, branch on `content.type` to handle both shapes.
### Error results
If the advisor call fails, the result carries an error:
```python
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_tool_result_error",
"error_code": "overloaded"
}
}
```
The executor sees the error and continues without further advice. The request itself does not fail.
| `error_code` | Meaning |
|---------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| `max_uses_exceeded` | The request reached the `max_uses` cap set on the tool definition. Further advisor calls in the same request return this error. |
| `too_many_requests` | The advisor sub-inference was rate-limited. |
| `overloaded` | The advisor sub-inference hit capacity limits. |
| `prompt_too_long` | The transcript exceeded the advisor model's context window. |
| `execution_time_exceeded` | The advisor sub-inference timed out. |
| `model_not_found` | The configured advisor model is not available. |
| `unavailable` | Any other advisor failure. |
Advisor rate limits draw from the same per-model bucket as direct calls to the advisor model. A rate limit on the advisor appears as `too_many_requests` inside the tool result. A rate limit on the executor fails the whole request with HTTP 429.
## Multi-turn conversations
Pass the full assistant content, including `advisor_tool_result` blocks, back to the API on subsequent turns. Round-trip the result blocks verbatim: with a Claude Opus 5.5 advisor the result block's `content` is the encrypted `advisor_redacted_result` variant, and the server decrypts it and renders the advice into the executor's prompt on the next turn (see [Result variants](#result-variants)). The mechanics are identical for any advisor model.
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5-5",
}
]
messages = [
{
"role": "user",
"content": "Build a concurrent worker pool in Go with graceful shutdown.",
}
]
response = client.beta.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
betas=["advisor-tool-2026-03-01"],
tools=tools,
messages=messages,
)
# Append the full response content, including any advisor_tool_result blocks
messages.append({"role": "assistant", "content": response.content})
# Continue the conversation
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})
response = client.beta.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
betas=["advisor-tool-2026-03-01"],
tools=tools,
messages=messages,
)
```
You can drop the advisor tool from `tools` on a follow-up turn while the message history still contains `advisor_tool_result` blocks. The request is accepted and the historical blocks are preserved; the model cannot call the advisor on that turn. You must still send the `advisor-tool-2026-03-01` beta header for those history blocks to be accepted.
The advisor tool has no built-in conversation-level cap. To limit advisor calls across a conversation, count them client-side. When you reach your ceiling, remove the advisor tool from your `tools` array. You do not need to strip `advisor_tool_result` blocks from your message history.
### Resuming a paused turn
A response can end with `stop_reason: "pause_turn"` while an advisor call is still pending. When that occurs, the response contains the advisor's `server_tool_use` block with no `advisor_tool_result` for it. To resume, append that assistant message to `messages` with its content unchanged, keeping the `server_tool_use` block, and send the request again with the same advisor tool and beta header. You do not need to add a user message or a `tool_result` block. The API runs the pending advisor call and continues the executor's turn in the new response. A resumed turn can pause again. If it does, repeat the same step. Omitting the advisor tool from the resume request returns a 400 `invalid_request_error`, because the pending `server_tool_use` block has no tool definition to run against; include the tool whenever a call is pending. If instead the executor called one of your tools in the same turn, the response ends with `stop_reason: "tool_use"` while the advisor call is still pending. Send the `tool_result` blocks as usual, and the pending advisor call runs at the start of that next request. See [Mixing server tools and client tools in one turn](agents-and-tools-tool-use-server-tools.md#mixing-server-tools-and-client-tools-in-one-turn).
### Mid-conversation nudge for under-calling executors
If a Haiku executor has not called the advisor in its first assistant turn, append a short reminder as an additional user message before the second assistant turn. In Anthropic's internal behavioral evaluation on Claude Haiku 4.5 executors, this raised task pass rates by roughly 7 percentage points. On Sonnet executors, the plain-text nudge had no measurable effect in Anthropic's testing. The call-timing considerations that follow are especially relevant for Sonnet. Do not apply the nudge to Opus executors: On Opus it slightly lowered pass rates.
With the default `NUDGE_TURN` of 2, the reminder typically arrives after the model has oriented on the task but before it has committed to an approach.
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
NUDGE_TURN = 2 # inject before this assistant turn if no advisor call yet
NUDGE_TEXT = (
"You have not consulted the advisor yet. If the task has a non-obvious "
"design decision or a failure mode you haven't ruled out, call advisor "
"now before committing to an approach."
)
MAX_TURNS = 10 # agent loop cap
def run_your_tools(content):
# Replace with your tool dispatch. Returns one tool_result block per tool_use block.
return [
{
"type": "tool_result",
"tool_use_id": block.id,
"content": "Replace with your tool output.",
}
for block in content
if block.type == "tool_use"
]
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5-5",
},
# ... your other tools
]
task = "Build a concurrent worker pool in Go with graceful shutdown."
messages = [{"role": "user", "content": task}]
advisor_called = False
for turn in range(1, MAX_TURNS + 1):
response = client.beta.messages.create(
model="claude-haiku-5-5",
max_tokens=4096,
betas=["advisor-tool-2026-03-01"],
tools=tools,
messages=messages,
)
messages.append({"role": "assistant", "content": response.content})
advisor_called = advisor_called or any(
block.type == "server_tool_use" and block.name == "advisor"
for block in response.content
)
if response.stop_reason == "pause_turn":
continue # server tool pending; re-send to let the API complete it
if response.stop_reason != "tool_use":
break # end_turn, or a stop such as max_tokens that needs handling (see below)
results = run_your_tools(response.content) # list of tool_result blocks
if results:
messages.append({"role": "user", "content": results})
# Skip this if your system prompt already tells the model to call sparingly.
if turn == NUDGE_TURN - 1 and not advisor_called:
messages.append({"role": "user", "content": NUDGE_TEXT})
```
The loop ends on any stop reason other than `tool_use` or `pause_turn`. If `max_tokens` cuts a response off, drop the truncated assistant turn from `messages` and [retry with a higher `max_tokens`](../Guides/build-with-claude-handling-stop-reasons.md#max-tokens). When that turn contains no `tool_use` block, you can instead keep it and [continue the response](../Guides/build-with-claude-handling-stop-reasons.md#ensuring-complete-responses) with a new user message. Re-sending the truncated assistant turn as the last message is a [prefill](../Endpoints/errors.md#prefill-not-supported), which Claude 4.6 and later models reject.
Append the nudge as its own user message after the tool results rather than as a sibling block in the same message. Consecutive user messages are valid. In Anthropic's testing on Claude Haiku 4.5 and Sonnet executors they behaved equivalently to a sibling block. The separate-message shape also keeps the reminder clearly distinct from tool output.
**Trade-offs:** The nudge raises the call rate, which can push trivially simple tasks into an unnecessary consult. If your workload mixes simple and complex tasks, consider raising `NUDGE_TURN` to 3 so two-turn tasks complete before the nudge fires, or gate the nudge on a task-complexity signal you already compute. If your system prompt already contains restraint language ("reserve the advisor for genuine uncertainty"), skip the nudge entirely, because the two instructions conflict.
The plain-text nudge is highly salient on Claude Haiku 4.5 and Sonnet executors: 74 percent (Sonnet) to 98 percent (Claude Haiku 4.5) of nudged attempts in Anthropic's testing called the advisor immediately at turn 2. If that lands before your executor has read the problem or gathered context, the resulting advisor call is low-context and can displace a better-timed later call. Measure your executor's baseline first-call turn before adding the nudge. If the executor already calls the advisor reliably and its first call typically lands at turn N, set `NUDGE_TURN` greater than N. In Anthropic's testing, a turn-2 nudge on workloads where the baseline first call was turn 7 or later correlated with a 3 to 4 percentage-point task-performance drop. On a browse workload where the baseline call rate was 86 percent, the same nudge raised engagement with no task-performance cost.
To force a consult on a specific request instead of nudging, set `tool_choice` to `{"type": "tool", "name": "advisor"}`, subject to the constraints in [Forcing tool use](agents-and-tools-tool-use-implement-tool-use.md#forcing-tool-use). Forcing tool use cannot be combined with manual extended thinking (`thinking: {type: "enabled"}`): the API returns a `400 invalid_request_error` if you enable both. Adaptive thinking supports forced tool use. Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and Claude Mythos 5.1 executors reject `tool_choice` types `tool` and `any`, so use the prompt nudge on those models instead.
## Streaming
The advisor sub-inference does not stream. The executor's stream pauses while the advisor runs; then the full result arrives in a single event.
The `server_tool_use` block with `name: "advisor"` signals that an advisor call is starting. The pause begins when that block closes (`content_block_stop`). During the pause, the stream is quiet except for standard SSE `ping` keepalives emitted roughly every 30 seconds. Short advisor calls might show no pings.
When the advisor finishes, the `advisor_tool_result` arrives fully formed in a single `content_block_start` event (no deltas). Executor output then resumes streaming.
A `message_delta` event follows with the updated `usage.iterations` array reflecting the advisor's token counts.
## Usage and billing
Advisor calls run as a separate sub-inference billed at the advisor model's rates. Usage is reported in the `usage.iterations[]` array:
```python
{
"usage": {
"input_tokens": 1760,
"cache_read_input_tokens": 412,
"cache_creation_input_tokens": 0,
"output_tokens": 531,
"iterations": [
{
"type": "message",
"input_tokens": 412,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 89
},
{
"type": "advisor_message",
"model": "claude-opus-5-5",
"input_tokens": 823,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 1612
},
{
"type": "message",
"input_tokens": 1348,
"cache_read_input_tokens": 412,
"cache_creation_input_tokens": 0,
"output_tokens": 442
}
]
}
}
```
Top-level `usage` fields reflect executor tokens only. Advisor tokens are not rolled into the top-level totals because they are billed at a different rate. Iterations with `type: "advisor_message"` are billed at the advisor model's rates, and iterations with `type: "message"` are billed at the executor model's rates.
Every top-level `usage` field is the sum of that field across all executor iterations, including `input_tokens`, `output_tokens`, and `cache_read_input_tokens`. Because each executor iteration re-sends the growing conversation, later iterations' inputs include earlier iterations' output, so summed `input_tokens` exceeds the size of any single prompt. Use `usage.iterations` for a full per-iteration breakdown when building cost-tracking logic.
Advisor output is typically 400 to 700 text tokens, or 1,400 to 1,800 tokens total including thinking. The cost savings come from the advisor not generating your full final output. The executor does that at its lower rate.
The top-level `max_tokens` applies to executor output only. It does not bound advisor sub-inference tokens. To cap advisor output directly, set [`max_tokens` on the tool definition](#capping-advisor-output). The advisor's tokens also do not draw from any [task budget](../Guides/build-with-claude-task-budgets.md) applied to the executor.
[Priority Tier](../Endpoints/service-tiers.md) applies to each model independently. A Priority Tier commitment on the executor model does not extend to the advisor. Advisor calls run at Priority Tier only if your organization also holds a commitment on the advisor model.
## Advisor prompt caching
There are two independent caching layers.
### Executor-side caching
The `advisor_tool_result` block is cacheable like any other content block. A `cache_control` breakpoint placed after it on a subsequent turn hits. The executor's prompt always contains the plaintext advice regardless of whether your client received `text` or `encrypted_content`, so caching behavior is identical for both result variants.
### Advisor-side caching
Set `caching` on the tool definition to enable prompt caching for the advisor's own transcript across calls within the same conversation:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5-5",
"caching": {"type": "ephemeral", "ttl": "5m"},
}
]
```
The advisor's prompt on the Nth call is the (N-1)th call's prompt with one more segment appended, so the prefix is stable across calls. With `caching` enabled, each advisor call writes a cache entry, and the next call reads up to that point and pays only for the delta. You'll see `cache_read_input_tokens` become non-zero on the second and later `advisor_message` iterations.
**When to enable it:** The cache write costs more than the reads save when the advisor is called two or fewer times per conversation. Caching breaks even at roughly three advisor calls and improves from there. Enable it for long agent loops, and keep it off for short tasks.
**Keep it consistent:** Set `caching` once and leave it for the whole conversation. Toggling it off and on mid-conversation causes cache misses.
[`clear_thinking`](../Guides/build-with-claude-context-editing.md) with a `keep` value other than `"all"` shifts the advisor's quoted transcript each turn, causing advisor-side cache misses. This is a cost degradation only. Advice quality is unaffected. When thinking is on without explicit `clear_thinking` configuration, the API defaults to `keep: {type: "thinking_turns", value: 1}`, which triggers this behavior (the default on earlier Opus and Sonnet models and on Haiku models through Claude Haiku 4.5; on Claude Opus 4.5 and later Opus models, Claude Sonnet 4.6 and later Sonnet models, and Claude Haiku 5.5, the default is to keep all turns). Set `keep: "all"` to preserve advisor cache stability.
## Combining with other tools
The advisor tool composes with other server-side and client-side tools. Add them all to the same `tools` array:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
tools = [
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5,
},
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5-5",
},
{
"name": "run_bash",
"description": "Run a bash command",
"input_schema": {
"type": "object",
"properties": {"command": {"type": "string"}},
},
},
]
```
The executor can search the web, call the advisor, and use your custom tools in the same turn. The advisor's plan can inform which tools the executor reaches for next.
| Feature | Interaction |
|-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Batch processing](../Guides/build-with-claude-batch-processing.md) | Supported. `usage.iterations` is reported per item. |
| [Token counting](../Guides/build-with-claude-token-counting.md) | Returns the executor's first-iteration input tokens only. For a rough advisor estimate, call `client.beta.messages.count_tokens()` with `model` set to the advisor model and the same messages. |
| [Context editing](../Guides/build-with-claude-context-editing.md) | `clear_tool_uses` is not fully compatible with advisor tool blocks. With `clear_thinking`, see the earlier caching warning. |
| `pause_turn` | A dangling advisor call ends the response with `stop_reason: "pause_turn"` and a `server_tool_use` block with no result when no client `tool_use` block is awaiting your result in the same turn. The advisor runs on resumption. If the executor also called one of your tools in that turn, the response ends with `stop_reason: "tool_use"` instead, and the pending advisor call runs at the start of your next request, after you send the `tool_result` blocks. See [Resuming a paused turn](#resuming-a-paused-turn), [Mixing server tools and client tools in one turn](agents-and-tools-tool-use-server-tools.md#mixing-server-tools-and-client-tools-in-one-turn), and [Server tools](agents-and-tools-tool-use-server-tools.md#the-server-side-loop-and-pause-turn). |
## Best practices
### Prompting for coding and agent tasks
The advisor tool ships with a built-in description that nudges the executor to call it near the start of complex tasks and when it hits difficulty. For research tasks, no additional prompting is typically needed.
On coding and agent tasks, the advisor produces higher intelligence at similar cost when it reduces total tool calls and conversation length. Two timings drive this improvement:
1. An early first advisor call, after a few exploratory reads are in the transcript.
2. For difficult tasks, a final advisor call after file writes and test outputs are in the transcript.
If your agent exposes other planner-like tools (for example, a todo list tool), prompt the model to call the advisor before those tools so the advisor's plan funnels into them. The [suggested system prompt](#suggested-system-prompt-for-coding-tasks) reinforces the early-call pattern. Add your own funnel-in sentence pointing at whichever planner tools your agent exposes.
#### Suggested system prompt for coding tasks
Without system-prompt steering, the executor tends to under-call the advisor in some domains, particularly coding tasks. For coding tasks where you want consistent advisor timing and around two to three calls for each task, prepend the following blocks to your executor system prompt before any other sentences that mention the advisor.
Timing guidance:
``` block
You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.
Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.
Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck — errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.
On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.
```
How the executor should treat the advice (place directly after the timing block):
```python
Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it's evidence your test doesn't check what the advice is checking.
If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.
```
#### Alternative system prompt for Haiku on coding workloads
Claude Haiku 4.5 applies the default advisor guidance conservatively. That keeps its call rate appropriately low on research and lookup workloads but gives up quality on coding workloads, where an early advisor consult reliably pays for itself. On an internal coding benchmark, a close variant of the following block (the read-only carve-out in the Hard rule was added after measurement) raised Haiku pass rates by roughly 7.5 percentage points over the built-in default.
Use this block in place of the earlier timing and advice blocks when your Haiku executor runs predominantly coding or write-task workloads:
```python
Consult a stronger reviewer who sees your full conversation transcript.
No parameters. When you call advisor(), your entire history -- task, every tool call and result, your reasoning -- is automatically forwarded. The advisor sees exactly what you've done.
Call advisor BEFORE substantive work -- before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.
Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck -- errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.
On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.
Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking.
If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.
Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first -- that judgment call is exactly where a second opinion is highest-value.
Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.
```
**Caveat:** On an internal browse-comprehension benchmark (n = 1,266), a close variant of this block cost roughly 4 percentage points of accuracy relative to the built-in default. If your workload mixes coding with substantial lookup or retrieval, stay with the [suggested blocks](#suggested-system-prompt-for-coding-tasks), or gate the swap on a workload-type signal you already compute.
#### Increasing advisor calls on Opus executors
Opus executors typically call the advisor at an appropriate rate without additional prompting. If your Opus executor is under-calling on your workload, add the following checkpoint to your system prompt:
```python
Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first. That judgment call is exactly where a second opinion is highest-value. (This does not apply to simple factual lookups or arithmetic; those you answer directly.)
Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.
```
**Caveat:** In Anthropic's testing, a close variant of this block (the read-only carve-out in the Hard rule was added after measurement) raised pass rates on under-calling tasks by roughly 7 to 10 percentage points but caused Opus to over-call on tasks whose first action needs no planning. The net effect was roughly flat on a mixed workload. Only add it if you have observed Opus skipping the advisor on tasks where a consult would have helped. Do not add it as a default.
#### Trimming advisor output length
Advisor output is the advisor's largest cost driver, and the top-level `max_tokens` does not bound it. The advisor sees both your system prompt and your user messages as quoted context about the executor's task, so instructions that address the advisor directly are followed much more reliably than third-person descriptions. The most effective placement Anthropic tested is a line in the user message:
``` block
(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)
```
This line can be prefixed programmatically by your agent framework before sending the request. The limit is a soft constraint. The advisor occasionally exceeds it, so ask for roughly 80 percent of your true ceiling.
In Anthropic's testing this line also increased how often the executor consults the advisor, but the net effect was still lower total cost (more consults, each shorter).
Pair this approach with the timing guidance in [Suggested system prompt for coding tasks](#suggested-system-prompt-for-coding-tasks) (or the [alternative Haiku block](#alternative-system-prompt-for-haiku-on-coding-workloads) if you swapped it in) for the strongest cost-versus-quality tradeoff. For a hard ceiling rather than a soft request, see [Capping advisor output](#capping-advisor-output).
### Capping advisor output
Set `max_tokens` on the tool definition to cap the advisor's total output (thinking plus text) per call:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5-5",
"max_tokens": 2048,
}
]
```
The minimum value is 1024. Setting `max_tokens` above the advisor model's own output cap returns a 400 error. The cap applies to each advisor call independently and is not shared across calls in the same request.
This is not a hard truncation alone. The server also passes the advisor its remaining-token budget, so the advisor shapes its response to fit.
**Recommended starting point:** `max_tokens: 2048`. In Anthropic's testing on a hard reasoning benchmark (n = 40 per configuration), this reduced mean advisor output by roughly 7x compared with leaving the cap unset, with near-zero truncation and no detectable quality degradation. The minimum value of 1024 reduced output roughly 10x but truncated around 10 percent of calls. Accuracy differences across all configurations were within noise at this sample size. Validate on your own workload.
| `max_tokens` | Mean advisor output tokens | Calls truncated |
|--------------|----------------------------|-----------------|
| unset | ~4,200 to 5,900 | n/a |
| 2048 | ~630 to 840 | ~0% |
| 1024 | ~370 to 480 | ~10% |
Hard reasoning tasks elicit substantially longer advisor output than the [typical 1,400 to 1,800 tokens](#usage-and-billing) quoted earlier for lighter workloads. Use this table to size the savings ratio, not as a universal baseline for advisor output.
When the advisor does hit the cap, the result block carries `stop_reason: "max_tokens"` on both [result variants](#result-variants), whichever advisor model you use. Use `stop_reason` to detect truncated advice and decide whether to raise the cap or let the executor proceed with partial guidance. The API also appends `[Advisor output truncated at max_tokens=2048.]` (naming your cap) to the advice text, so the executor sees the truncation in its own context; with a plaintext `advisor_result` advisor that marker is visible to your client as well. Both signals appear only when you set `max_tokens` on the tool definition.
```python
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_redacted_result",
"encrypted_content": "EqQBCkYIBRgCIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
"stop_reason": "max_tokens"
}
}
```
Check `output_tokens` on the corresponding `advisor_message` entry in `usage.iterations` to see how close each call came to its cap.
Compared with the [prompt-based approach](#trimming-advisor-output-length), `max_tokens` is a hard ceiling rather than a soft request. Use `max_tokens` when you need a guaranteed bound for cost or latency. Use the prompt-based approach (or both together) when you want to bias toward brevity without risking a mid-thought cut.
### Pairing with effort settings
For coding tasks, pairing a Sonnet executor at medium [effort](../Guides/build-with-claude-effort.md) with an Opus advisor achieves intelligence comparable to Sonnet at default effort, at lower cost. For maximum intelligence, keep the executor at default effort.
### Cost control
- For conversation-level budgets, count advisor calls client-side. When you reach your cap, remove the advisor tool from `tools`; you do not need to strip `advisor_tool_result` blocks from your message history (see the note in [Multi-turn conversations](#multi-turn-conversations)).
- Enable `caching` only for conversations where you expect three or more advisor calls.
## Model compatibility
The executor model (the top-level `model` field) and the advisor model (the `model` field inside the tool definition) must form a valid pair. The advisor must be Claude Sonnet 4.6 or a more capable model, and it must be at least as capable as the executor. Models of equal capability (for example, Claude Opus 4.7 and Claude Opus 4.8) can advise each other.
[TABLE]
If you request an invalid pair, the API returns a `400 invalid_request_error` naming the unsupported combination.
### Platform availability
The advisor tool is available in beta on the Claude API and on [Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md). It is not currently available on Amazon Bedrock, Google Cloud, or Microsoft Foundry.
## Advisor on Claude Managed Agents
[Claude Managed Agents](../Other/managed-agents-overview.md) sessions support an advisor as well, configured as part of the agent rather than as a tool definition: set `"advisor": {"type": "enabled", "model": ...}` in the agent's `multiagent` block, and the session's primary thread can consult that model mid-turn. The setting takes no `max_uses`, `max_tokens`, or `caching` options, and advice is delivered as thread events on the session's event stream rather than as `advisor_tool_result` blocks in the response. See [Give the session an advisor](../Other/managed-agents-multiagent-orchestration.md#give-the-session-an-advisor).
## Next steps
[Memory tool](agents-and-tools-tool-use-memory-tool.md)
Store and retrieve information across conversations with a client-side memory directory.
[Server tools](agents-and-tools-tool-use-server-tools.md)
Work with Anthropic-executed tools: server_tool_use blocks, pause_turn continuation, and domain filtering.
[Tool reference](agents-and-tools-tool-use-tool-reference.md)
Directory of Anthropic-provided tools and reference for optional tool definition properties.
[Effort](../Guides/build-with-claude-effort.md)
Control how many tokens Claude uses when responding with the effort parameter, trading off between response thoroughness and token efficiency.
---
## Bash tool - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-bash-tool.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fbash-tool)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Bash tool
Copy page
Let Claude request shell commands that your application runs in a persistent bash session and returns as tool results.
Copy page
To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
The bash tool is a [client tool](agents-and-tools-tool-use-how-tool-use-works.md): Claude doesn't run commands itself. When you include the tool in a request, Claude replies with a `tool_use` block that names the command to run. Your application runs that command in a bash session it owns and returns the output in a `tool_result` block.
Your application keeps one bash process alive across tool calls, so state persists between commands. The working directory, environment variables, and any files a command creates are still there for the next command.
The current version of the tool is `bash_20250124`. For model support, beta headers, and the earlier version, see [Tool versions](#tool-versions). For all Anthropic-provided tools, see the [Tool reference](agents-and-tools-tool-use-tool-reference.md).
## Use cases
- **Development workflows:** Run build commands, tests, and development tools
- **System automation:** Execute scripts, manage files, automate tasks
- **Data processing:** Process files, run analysis scripts, manage datasets
- **Environment setup:** Install packages, configure environments
## Quick start
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[{"type": "bash_20250124", "name": "bash"}],
messages=[
{"role": "user", "content": "List all Python files in the current directory."}
],
)
print(response)
```
Claude responds with `stop_reason: "tool_use"` and a `tool_use` block that contains the command for your application to run:
Output
```python
{
"id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll list all Python files in the current directory for you."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "bash",
"input": {
"command": "ls *.py"
}
}
]
}
```
Run `input.command` in your bash session and send the output back as a `tool_result`. See [Implement the bash tool](#implement-the-bash-tool) for the round trip.
## How it works
Each tool call is one round trip between Claude and your application:
1. Claude returns a `tool_use` block containing the `command` to run.
2. Your application runs the command in its bash session.
3. Your application returns the command's output, stdout and stderr together, to Claude in a `tool_result` block.
4. Claude either requests another command in the same session or responds with text.
Claude can also return several `tool_use` blocks in one response. Run them in order in the same session and return all of the results in one `user` message. See [Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md).
The API is stateless. Nothing about your shell session travels between requests, so your application decides when the session starts, how long it lives, and when to restart it. For the full request and response cycle, see [Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md).
## Parameters
A bash tool definition has two required fields, `type` and `name`, and the `name` must be `bash`. The tool is schema-less: you don't provide an `input_schema`, because the schema is built into Claude's model and can't be modified. The following table lists the input fields Claude sets when it calls the tool.
| Parameter | Required | Description |
|-----------|----------|-------------------------------------------|
| `command` | Yes\* | The bash command to run |
| `restart` | No | Set to `true` to restart the bash session |
\*Required unless using `restart`
To handle `restart: true`, kill the shell process, start a new one, and return a `tool_result` that confirms the restart. A restarted session starts clean: the working directory, environment variables, and any running processes are gone.
### Example usage
Run a command:
```python
{
"command": "ls -la *.py"
}
```
Restart the session:
```python
{
"restart": true
}
```
## Tool versions
`bash_20250124` is the current version of the tool, and it requires no beta header. Every model from Claude Sonnet 3.7 ([retired](../../20-Models/about-claude-model-deprecations.md)) onward accepts it, including all current Claude models.
The original `bash_20241022` version works only with the October 2024 Claude Sonnet 3.5 model ([retired](../../20-Models/about-claude-model-deprecations.md)). Requests that use it need the `anthropic-beta: computer-use-2024-10-22` header, and the SDK exposes it only in its beta namespace. New integrations should use `bash_20250124`.
## Example: Multistep automation
Claude can chain commands across tool calls to complete a multistep task:
``` inline-block
User request:
"Install the requests library and create a simple Python script that
fetches a joke from an API, then run it."
Claude's tool uses:
1. Install package
{"command": "pip install requests"}
2. Create script
{"command": "cat > fetch_joke.py << 'EOF'\nimport requests\nresponse = requests.get('https://official-joke-api.appspot.com/random_joke')\njoke = response.json()\nprint(f\"Setup: {joke['setup']}\")\nprint(f\"Punchline: {joke['punchline']}\")\nEOF"}
3. Run script
{"command": "python fetch_joke.py"}
```
The session maintains state between commands, so files created in step 2 are available in step 3.
## Implement the bash tool
Claude determines which command to run. Your application owns everything else: the shell process, the timeout, and the safety checks. The following steps show a minimal implementation.
1. 1
### Create a persistent bash session
Start one long-lived bash process and run every command inside it. Because a pipe to a live process never reports end-of-file, the session prints a unique sentinel line after each command to mark where that command's output ends:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
``` shiki
import subprocess
import uuid
class BashSession:
"""A bash process that stays alive between commands so state persists."""
def __init__(self):
self.process = subprocess.Popen(
["/bin/bash"],
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT, # interleave errors with output, in order
start_new_session=True, # own process group: a timeout can kill every child
text=True,
)
def execute_command(self, command):
"""Run a command in the session and return its output."""
sentinel = f"__CLAUDE_BASH_DONE_{uuid.uuid4().hex}__" # unique per call
self.process.stdin.write(f"{command}\necho {sentinel}\n")
self.process.stdin.flush()
output = []
for line in self.process.stdout:
if sentinel in line: # this command's output is complete
break
output.append(line)
return "".join(output)
def restart(self):
self.process.kill()
self.process.wait()
self.__init__()
bash_session = BashSession()
print(bash_session.execute_command("cd /tmp && pwd"))
print(bash_session.execute_command("pwd")) # still /tmp: the session kept its state
```
The session interleaves stderr with stdout, so error messages land where they happened. The example leaves out what a complete implementation also needs: a timeout that kills the shell and every process it started when a command hangs, then restarts the session. The [Use command timeouts](#follow-implementation-best-practices) best practice shows one way to add it.
2. 2
### Process Claude's tool calls
Extract and run commands from Claude's responses:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
``` shiki
tool_results = []
for content in response.content:
if content.type == "tool_use" and content.name == "bash":
if content.input.get("restart"):
bash_session.restart()
result = "Bash session restarted"
else:
command = content.input.get("command")
result = bash_session.execute_command(command)
# One tool_result per tool_use block, all returned in the next user message
tool_results.append(
{"type": "tool_result", "tool_use_id": content.id, "content": result}
)
```
3. 3
### Return the result to Claude
Send the `tool_result` back in a `user` message that continues the same conversation. Claude either requests another command in the same session or finishes its answer:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
``` shiki
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[{"type": "bash_20250124", "name": "bash"}],
messages=[
{"role": "user", "content": "List all Python files in the current directory."},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "bash",
"input": {"command": "ls *.py"},
}
],
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "analysis.py\nprocess_data.py\n",
}
],
},
],
)
print(response.content)
```
Repeat the run-and-return cycle while `stop_reason` is `tool_use`. For the full loop, see [Handling results from client tools](agents-and-tools-tool-use-handle-tool-calls.md#handling-results-from-client-tools).
4. 4
### Implement safety measures
Add validation and restrictions. Use an allowlist rather than a blocklist: a blocklist misses any command it didn't anticipate. The example also rejects shell operators that appear as separate words:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
``` shiki
import shlex
ALLOWED_COMMANDS = {"ls", "cat", "echo", "pwd", "grep", "find", "wc", "head", "tail"}
SHELL_OPERATORS = {"&&", "||", "|", ";", "&", ">", "<", ">>"}
def validate_command(command):
# Allow only commands from an explicit allowlist
try:
tokens = shlex.split(command)
except ValueError:
return False, "Could not parse command"
if not tokens:
return False, "Empty command"
executable = tokens[0]
if executable not in ALLOWED_COMMANDS:
return False, f"Command '{executable}' is not in the allowlist"
# Reject shell operators written as separate words
for token in tokens[1:]:
if token in SHELL_OPERATORS or token.startswith(("$", "`")):
return False, f"Shell operator '{token}' is not allowed"
return True, None
```
This check is a tripwire for obvious mistakes, not an enforcement boundary. It rejects the spaced chaining (`&&`), pipes, and redirection that the other examples on this page use. It does not catch an operator glued to a word, such as `cat data.txt|grep x`, because the tokenizer keeps `data.txt|grep` inside one token. Decide which commands and operators your application allows. The real control is isolation: run the whole session inside a container or a virtual machine (see [Security](#security)).
### Handle errors
When a command fails or the session breaks, tell Claude what happened. Return the message as the `tool_result` content and set `is_error` to `true`, which marks the tool call as failed. See [Handling errors with is_error](agents-and-tools-tool-use-handle-tool-calls.md#handling-errors-with-is-error).
### Command execution timeout
If a command takes too long to execute:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: command did not finish within 30 seconds",
"is_error": true
}
]
}
```
### Command not found
If a command doesn't exist:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "bash: nonexistentcommand: command not found",
"is_error": true
}
]
}
```
### Permission denied
If there are permission issues:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "bash: /root/sensitive-file: Permission denied",
"is_error": true
}
]
}
```
### Follow implementation best practices
### Use command timeouts
A command that never finishes, such as one that waits for input, blocks the session forever because its sentinel line never arrives. Give every command a deadline. When the deadline passes, stop the shell and everything the command started, then restart the session:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
import concurrent.futures
import os
import signal
def execute_with_timeout(session, command, timeout=30):
"""Run a command in the session, replacing the session if the command hangs."""
with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
future = pool.submit(session.execute_command, command)
try:
return future.result(timeout=timeout)
except concurrent.futures.TimeoutError:
# The group is the shell and every process the command started
os.killpg(session.process.pid, signal.SIGKILL)
session.restart()
return f"Error: command did not finish within {timeout} seconds"
```
The kill stops the hung command and everything it started. Return the message as an error `tool_result` (see [Handle errors](#handle-errors)), which marks the tool call as failed.
### Maintain session state
Keep the bash session persistent to maintain environment variables and working directory:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
# Commands run in the same session maintain state
commands = [
"cd /tmp",
"echo 'Hello' > test.txt",
"cat test.txt", # The session is still in /tmp
]
```
### Handle large outputs
Truncate large outputs to prevent token limit issues:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
def truncate_output(output, max_lines=100):
lines = output.split("\n")
if len(lines) > max_lines:
truncated = "\n".join(lines[:max_lines])
return f"{truncated}\n\n... Output truncated ({len(lines)} total lines) ..."
return output
```
### Log all commands
Keep an audit trail. Route every command through one wrapper that records the command before it runs and the output after it finishes. A command that hangs or breaks the session still leaves a record:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
import logging
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(message)s")
def execute_and_log(session, command):
"""Run a command in the session and keep an audit record of it."""
logging.info("command=%r", command)
output = session.execute_command(command)
logging.info("output=%r", output[:200]) # first 200 characters
return output
```
The records go to `stderr` by default; point them at a file or your logging pipeline to keep them. Include whatever ties the record to the request in your application, such as the end user and the `tool_use_id`.
## Security
Your application runs whatever command Claude requests. Run the session in an isolated environment, such as a container or a virtual machine, as the least-privileged user that can do the work. Treat every command as untrusted input.
Beyond isolation, add these controls:
- Validate commands before running them, with an allowlist rather than a blocklist. See [Implement the bash tool](#implement-the-bash-tool).
- Set resource limits on the shell process (CPU, memory, and disk), for example with `ulimit`.
- Log every command and its output so you can audit what ran.
- Redact credentials and other secrets from output before returning it to Claude.
## Pricing
The bash tool definition adds the following input tokens to your request. This is in addition to the per-model [tool use system prompt](agents-and-tools-tool-use-overview.md#pricing) that applies whenever any tool is present.
| Model | Additional input tokens |
|-------------------------------------------------------|-------------------------|
| Claude 4.7 and later models and Claude Mythos Preview | 325 tokens |
| Claude 4.6 and earlier models | 244 tokens |
Additional tokens are consumed by:
- Command outputs (stdout/stderr)
- Error messages
- Large file contents
See [tool use pricing](agents-and-tools-tool-use-overview.md#pricing) for complete pricing details.
## Common patterns
### Development workflows
- Running tests: `pytest && coverage report`
- Building projects: `npm install && npm run build`
- Git operations: `git status && git add . && git commit -m "message"`
For guidance on using git as a checkpoint-and-recovery mechanism in long-running agent workflows, see [state management best practices](../../10-Prompting-Guides/build-with-claude-prompt-engineering-claude-prompting-best-practices.md#state-management-best-practices).
### File operations
- Processing data: `wc -l *.csv && ls -lh *.csv`
- Searching files: `find . -name "*.py" | xargs grep "pattern"`
- Creating backups: `tar -czf backup.tar.gz ./data`
### System tasks
- Checking resources: `df -h && free -m`
- Process management: `ps aux | grep python`
- Environment setup: `export PATH=$PATH:/new/path && echo $PATH`
## Limitations
- **No interactive commands:** The session can't run `vim`, `less`, password prompts, or any command that waits for input on stdin.
- **No GUI applications:** The session is command-line only.
- **Session scope:** Bash session state is client-side. Your application is responsible for maintaining the shell session between turns.
- **Output limits:** The API doesn't truncate tool results (an oversized request is rejected). Truncate large outputs in your application before returning them to Claude.
- **No streaming:** Output reaches Claude only when your application returns the `tool_result` in the next request.
## Combining with other tools
The bash tool pairs well with the [Text editor tool](agents-and-tools-tool-use-text-editor-tool.md): Claude edits a file with one tool and requests the command that runs it with the other.
If you're also using the [Code execution tool](agents-and-tools-tool-use-code-execution-tool.md), Claude has access to two separate execution environments: your local bash session and Anthropic's sandboxed container. State is not shared between them. See [Using code execution with other execution tools](agents-and-tools-tool-use-code-execution-tool.md#using-code-execution-with-other-execution-tools) for guidance on prompting Claude to distinguish between environments.
## Next steps
[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)
View and modify text files to debug, fix, and improve code.
[Tool use with Claude](agents-and-tools-tool-use-overview.md)
Connect Claude to external tools and APIs. See where tools execute, when Claude calls them, and which tool fits your task.
---
## Browser and computer use with the SDK toolsets - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-sdk
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-browser-use-sdk.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fbrowser-use-sdk)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Google Cloud](../Guides/build-with-claude-claude-models-on-google-cloud-overview.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Browser and computer use with the SDK toolsets
Copy page
Run the browser use tool or the computer use tool from the Python or TypeScript SDK. The SDK runs the loop and the checks you configure, and you supply the browser or the desktop.
Copy page
With the browser and computer toolsets in the Python and TypeScript SDKs, you can build an agent that works in a web browser or on a desktop. It can use applications with no programmatic interface. Through the [browser use tool](agents-and-tools-tool-use-browser-use-tool.md), Claude navigates, reads, and interacts with webpages. Through the [computer use tool](agents-and-tools-tool-use-computer-use-tool.md), Claude receives screenshots of a desktop and uses the mouse and keyboard.
The SDK connects Claude to your browser or desktop. It runs the checks you configure, such as a URL policy for `navigate` or an approval callback. It sends each call that passes to your driver and builds the `tool_result` from what the driver returns. The [tool runner](agents-and-tools-tool-use-tool-runner.md) can run the agentic loop for you.
You supply the driver, which operates the browser or desktop. Start from a [provider's driver](#use-a-driver-from-a-provider). With one, an agent takes a few lines of code. If none fits, write your own with a browser automation library such as Playwright.
Most of this page is about the browser toolset. [Computer toolset](#computer-toolset) covers what differs.
Writing your own driver is an advanced case, covered in [Implement a driver](#implement-a-driver). The claude-quickstarts repository also has an [example browser driver](https://github.com/anthropics/claude-quickstarts/tree/main/browser-toolset) in Python and TypeScript. It controls Chromium through the Chrome DevTools Protocol (CDP), and it isn't production code.
The browser toolset class is in beta and available in the [Python SDK](https://github.com/anthropics/anthropic-sdk-python/blob/main/browser-toolset.md) and the [TypeScript SDK](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/browser-toolset.md). The computer toolset class is in beta in the same SDKs, which have a [Python computer toolset guide](https://github.com/anthropics/anthropic-sdk-python/blob/main/computer-toolset.md) and a [TypeScript computer toolset guide](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/computer-toolset.md).
## Use a driver from a provider
With a driver from a provider, such as one under [Partner integrations](#partner-integrations), you can build an agent in a few lines of code. The provider in this example is made up. Replace `example_browser_provider` and `ExampleBrowser` with a real provider's package and driver class, and set them up as the provider's docs describe.
Python
TypeScript
Python
```python
from anthropic import Anthropic
from example_browser_provider import ExampleBrowser # made-up provider
client = Anthropic()
with ExampleBrowser() as browser:
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
tools=[browser],
messages=[
{"role": "user", "content": "Open example.com and tell me its heading."}
],
)
for message in runner:
print(message)
```
Pass the driver instance itself as the `tools` entry. The runner never closes the toolset, so one instance can serve several runs. Close it when you're done.
To write your own driver, see [Implement a driver](#implement-a-driver).
## Partner integrations
Browser Use, Browserbase, Daytona, and E2B publish their own drivers for the SDK toolsets.
[Browser Use](https://docs.browser-use.com/open-source/customize/integrations/toolsets-for-claude)
Browser Use driver for the browser toolset.
[Browserbase](https://docs.stagehand.dev/v4/integrations/agent-frameworks/claude-cua-toolset-quickstart)
Browserbase Stagehand driver for the browser toolset.
[Daytona](https://www.daytona.io/docs/en/guides/claude/claude-draws-daytona-sandbox/)
Daytona driver for the computer toolset.
[E2B](https://docs.e2b.dev/agents/claude-toolsets)
E2B drivers for the browser and computer toolsets.
Partner code is also available on GitHub: the [Browser Use quickstart](https://github.com/browser-use/browser-use/tree/main/examples/integrations/toolsets-for-claude), the [Browserbase toolset](https://github.com/browserbase/claude-cua-toolset), and the [E2B example](https://github.com/e2b-dev/e2b-cookbook/tree/main/examples/anthropic-computer-use-orangehrm-js).
Do these two things before you run a driver against anything but a throwaway browser:
- [Write a URL policy](#write-a-url-policy). Without one, the SDK checks no URL. For a browser that a provider hosts, also read [Remote and hosted browsers](#remote-and-hosted-browsers).
- Use a browser profile that isn't signed in to any account whose data or actions you wouldn't hand to Claude. See [Isolate the browser host](#isolate-the-browser-host).
[Run the toolset safely](#run-the-toolset-safely) covers the rest.
## Customize a driver
The examples in this section use `MyBrowser`, the driver from the [advanced example](#quick-start) later on this page.
### Enable or disable members
`configs` takes the per-member settings described under [Configure the toolset](agents-and-tools-tool-use-browser-use-tool.md#configure-the-toolset). List only the members you change:
Python
TypeScript
Python
```python
# A MyBrowser that also implements read_console
browser = MyBrowser(
backend, configs={"read_console": {"enabled": True}, "navigate": {"enabled": False}}
)
```
The SDK refuses a call to a disabled member before your code runs. Enabling a member your class doesn't implement is a configuration error, unless the class overrides `execute`.
### Add before and after hooks
Override `execute` and call the parent's `execute`. Code before that call runs after the [URL policy](#write-a-url-policy), the [file policy](#confine-uploads-and-downloads), and [`confirm`](#gate-consequential-members), and it can change the input. The SDK doesn't check the changed input again. Code after the call receives the result, and it can change the result. Raise `ToolError` (throw it in TypeScript) to refuse the call.
Overriding `execute` changes which members Claude is offered. The SDK counts every member as implemented, so Claude is offered every member that's on by default. The `MyBrowser` in the [advanced example](#quick-start) serves three members, so the following `TracedBrowser` offers Claude members it can't serve. Turn those members off with `configs` before you use it.
Python
TypeScript
Python
```python
import time
class TracedBrowser(MyBrowser):
def execute(self, context, name, input):
started = time.monotonic()
result = super().execute(context, name, input)
elapsed_ms = (time.monotonic() - started) * 1000
call_id = context.tool_use.id if context.tool_use else "-"
log.info("%s %s %.0fms", call_id, name, elapsed_ms)
return redact(result) if name == "get_page_text" else result
```
## Implement a driver
A driver is your subclass of `BetaAbstractBrowserToolset20260801`. In it, override the members your browser supports. A member you don't implement is sent to the API as disabled. If Claude calls it anyway, the SDK returns an error, and the run continues. Overriding `execute` changes which members are sent as disabled ([Add before and after hooks](#add-before-and-after-hooks)). Each member receives the call context and the member's input as a typed object, such as `BetaBrowserNavigateInput`. The input types come from `anthropic.types.beta`. [Member tools](agents-and-tools-tool-use-browser-use-tool.md#member-tools) lists each input's fields.
In TypeScript, spell the `type` member `type_`, and write members as methods, not arrow-function fields, because the SDK finds them on the prototype.
### Return results
What a member returns determines what Claude reads. A successful result ends with a `browser_state` block built from your state report. An error result carries no block.
| Member | Returns | Claude reads |
|:----------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------|
| `screenshot`, `zoom` | `BetaScreenshotResult` | One image block |
| `navigate` | `BetaBrowserNavigateResult` | `Navigated to {url} — {title} (HTTP {status})` |
| `new_tab`, `switch_tab`, `list_tabs`, `close_tab` | A tab entry (`new_tab`, `switch_tab`), a list of tab entries (`list_tabs`), or nothing (`close_tab`) | The `browser_state` block alone |
| `read_page`, `get_page_text`, `find`, `read_console`, `read_network`, `javascript_exec` | A string | The string, or `(empty)` for an empty string |
| Every other member | Nothing, or one line of text | A short confirmation, such as `Clicked.`, then the returned line in a text block of its own |
### Report browser state
The SDK calls `_browser_state` after each call that returns a result, including refused and failed calls. Return every open tab, and what changed since the last report:
- Opened tabs and download events
- A `BetaNavigationRefused` for each navigation your [request hook](#intercept-requests-in-the-driver) blocked
- A `BetaDialogDismissed` for each native dialog your driver dismissed
Put all of these in `state_changes`. A refused navigation is `anthropic.tools.browser.BetaNavigationRefused()`, and a dismissed dialog is `anthropic.tools.browser.BetaDialogDismissed(kind=..., message=...)`.
The last two aren't API state changes. The SDK reports them to Claude as text outside the `browser_state` block: one line for all refused navigations, which doesn't include a URL, and a line for each of the first three dismissed dialogs, then a count of any others.
When any tab is open, exactly one must be active. Every member that takes a `tab_id` must act on the tab it names. The API's limits on the report are listed under [Track tabs with `browser_state`](agents-and-tools-tool-use-browser-use-tool.md#track-tabs-and-page-state).
Claude reads each tab's URL, each download's URL, and the URL that your `navigate` returns, as your driver wrote them. The SDK doesn't parse these URLs. It turns line breaks and other control characters into spaces, trims the ends, and cuts each URL at 4,096 characters. So a `data:` URL's contents, a `file:` URL's path, and a username or password in a URL all reach Claude.
### Handle errors
| Raised by a member or the SDK | Claude reads | The run |
|:------------------------------|:-----------------------------------------|:----------|
| `ToolError` | Its message, as an error result | Continues |
| `ToolsetUsageError` | Nothing | Stops |
| Any other exception | `ClassName: message`, as an error result | Continues |
The SDK raises `ToolsetUsageError` for a configuration error, a misuse of the SDK during a call, or a call after `close`. It also raises one when `_browser_state` raises any exception, even a `ToolError`. The tool runner and `tool_result` don't catch it, so it reaches their caller.
The SDK doesn't hide local paths in a member's error text, in the line an action such as `left_click` returns, in a failed download's error, or in a dismissed dialog's message.
A `ToolError` from your URL policy, file policy, or `confirm` callable reaches Claude as written, so leave local paths out of its text. Catch exceptions in your members, and raise `ToolError` (throw it in TypeScript) with your own text.
### Start calls while the response streams
By default, the tool runner runs a turn's calls after Claude's response ends. With early start, it can start a browser or computer call while the response is still streaming.
To turn it on, pass `stream=True` and `run_tools_eagerly=True` to the tool runner, as the [advanced example](#quick-start) does. With `stream`, each pass through your loop over the runner gives you a stream instead of a message.
Early start changes when a call can start, not how the toolset runs it:
- **The checks still run first:** The SDK calls your URL policy, your file policy, and `confirm` before a call runs. With early start, it can call `confirm` while the response is still streaming.
- **Calls still run one at a time:** A toolset runs its calls in the order Claude wrote them. A failed call still stops that toolset's later calls in the turn.
- **A call that has started can't be taken back:** If the response is then cut off, for example at `max_tokens`, or your loop stops early, the action still occurs, and Claude never reads its result.
### Run without the tool runner
Pass `browser` in `tools`, and answer each member call with `tool_result`. The browser use tool requires you to stop at the first failed call ([Batch actions](agents-and-tools-tool-use-browser-use-tool.md#batch-actions)).
This loop uses `MyBrowser` and the URL policy from the [advanced example](#quick-start). After a failed call, it answers the turn's later calls without running them:
Python
TypeScript
Python
```python
from anthropic.types.beta import BetaMessageParam, BetaToolResultBlockParam
NOT_EXECUTED = "Not executed: an earlier action in this turn failed."
MAX_TURNS = 10
with MyBrowser(backend, url_policy=url_policy) as browser:
messages: list[BetaMessageParam] = [{"role": "user", "content": "Open example.com"}]
for _ in range(MAX_TURNS):
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[browser],
messages=messages,
)
messages.append({"role": "assistant", "content": response.content})
calls = [
block
for block in response.content
if block.type == "tool_use" and block.toolset_name == browser.toolset_name
]
if not calls:
break
results: list[BetaToolResultBlockParam] = []
failed = False
for call in calls:
if failed:
# After a failed call, the rest of the turn is answered, not run.
results.append(
{
"type": "tool_result",
"tool_use_id": call.id,
"toolset_name": call.toolset_name,
"content": NOT_EXECUTED,
"is_error": True,
}
)
continue
result = browser.tool_result(call)
failed = bool(result.get("is_error"))
results.append(result)
messages.append({"role": "user", "content": results})
```
Each answer to a skipped call carries `is_error`, the call's `toolset_name`, and the exact text that [Batch actions](agents-and-tools-tool-use-browser-use-tool.md#batch-actions) requires. The tool runner sends the same answer.
## Advanced example: write your own driver
This example puts the main parts of [Implement a driver](#implement-a-driver) into one driver, `MyBrowser`, and runs it with the tool runner and [early start](#start-calls-while-the-response-streams). `MyBrowser` implements `navigate`, `screenshot`, and `left_click`, plus `_browser_state`, the state report that every driver needs.
`backend` stands for your own wrapper around a browser automation library, such as Playwright. The URL policy is an example. [Write a URL policy](#write-a-url-policy) explains it.
Python
TypeScript
Python
```python
import re
from urllib.parse import urlsplit
from anthropic import Anthropic
from anthropic.tools import ToolError
from anthropic.tools.browser import (
BetaAbstractBrowserToolset20260801,
BetaBrowserNavigateResult,
BetaBrowserState,
BetaScreenshotResult,
BetaToolsetCallContext,
BetaURLContext,
)
from anthropic.types.beta import (
BetaBrowserLeftClickInput,
BetaBrowserNavigateInput,
BetaBrowserScreenshotInput,
BetaBrowserStateTabEntryParam,
)
class MyBrowser(BetaAbstractBrowserToolset20260801):
def __init__(self, backend, **options):
super().__init__(**options)
self.backend = backend
def _browser_state(self, context: BetaToolsetCallContext) -> BetaBrowserState:
return BetaBrowserState(
tabs=[
BetaBrowserStateTabEntryParam(
tab_id=tab.id,
title=tab.title,
url=tab.url,
active=tab.id == self.backend.active,
)
for tab in self.backend.tabs()
],
state_changes=self.backend.drain_changes(),
)
def navigate(
self, context: BetaToolsetCallContext, input: BetaBrowserNavigateInput
) -> BetaBrowserNavigateResult:
# input.url is "back", "forward", "reload", or a URL that your URL policy
# allowed, as Claude wrote it. Like is_allowed, backend.goto adds https://
# to a URL that doesn't start with a scheme.
page = self.backend.goto(input.url, input.tab_id)
return BetaBrowserNavigateResult(
url=page.url, status=page.status, title=page.title
)
def screenshot(
self, context: BetaToolsetCallContext, input: BetaBrowserScreenshotInput
) -> BetaScreenshotResult:
data = self.backend.png_base64(input.tab_id)
return BetaScreenshotResult(data=data, media_type="image/png")
def left_click(
self, context: BetaToolsetCallContext, input: BetaBrowserLeftClickInput
) -> None:
# Nothing to return: Claude reads "Clicked."
self.backend.click(input.target, input.tab_id)
def close(self) -> None:
super().close() # first, so no call is still using the browser when it closes
if not self.backend.closed:
self.backend.close()
ALLOWED_HOSTS = ("example.com", "iana.org")
SCHEME_PREFIX = re.compile(r"[a-z][a-z0-9+.-]*:", re.IGNORECASE)
def is_allowed(url: str) -> bool:
# An example, not a production policy. See "Write a URL policy".
if url.lower() == "about:blank":
return True
with_scheme = url if SCHEME_PREFIX.match(url) else f"https://{url}"
# A browser reads "\" as "/" in a web URL.
try:
parts = urlsplit(with_scheme.replace("\\", "/"))
except ValueError:
return False
host = parts.hostname or ""
listed = any(host == name or host.endswith(f".{name}") for name in ALLOWED_HOSTS)
return parts.scheme in ("http", "https") and listed
def url_policy(context: BetaURLContext, url: str) -> None:
if not is_allowed(url):
raise ToolError(f"blocked: {url} is not on an allowed host")
client = Anthropic()
with MyBrowser(backend, url_policy=url_policy) as browser:
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
tools=[browser],
messages=[
{
"role": "user",
"content": "Open example.com and tell me the page heading.",
}
],
stream=True,
run_tools_eagerly=True, # so a call can start before the response ends
)
for stream in runner:
print(stream.get_final_message())
```
## Run the toolset safely
Claude's next action depends on the pages it reads. A page, or text injected into one, can attempt to reach internal services or pull files off the host. It can also attempt to trigger actions with real effects. Before you run a driver against anything but a throwaway browser, take these six steps:
1. [Write a URL policy](#write-a-url-policy) that refuses every `navigate` URL the task doesn't need.
2. [Intercept requests in the driver](#intercept-requests-in-the-driver), and check each request with the same rules.
3. [Put egress policy on the container](#put-egress-policy-on-the-container), so the network blocks what the driver can't see.
4. [Confine uploads and downloads](#confine-uploads-and-downloads), or leave uploads off.
5. [Gate consequential members](#gate-consequential-members) with `confirm`.
6. [Isolate the browser host](#isolate-the-browser-host) in a dedicated container or VM for each session.
The SDK applies steps 1, 4, and 5 through the policies and the callable you pass. Steps 2, 3, and 6 are up to your driver and your deployment. The precautions under [Security considerations](agents-and-tools-tool-use-browser-use-tool.md#security-considerations) apply as well.
Anthropic's prompt-injection classifiers, described under [Security considerations](agents-and-tools-tool-use-browser-use-tool.md#security-considerations), don't currently run on browser toolset requests sent through Amazon Bedrock.
### Write a URL policy
Without a URL policy, the SDK checks no URL, and the API doesn't filter the URLs Claude opens. Even with a policy, a link Claude clicks or a redirect can take the browser to loopback (`localhost`, `127.0.0.1`), to link-local addresses such as the cloud metadata address `169.254.169.254`, and to private network ranges. [Egress rules on the container](#put-egress-policy-on-the-container) can block the link-local and private addresses. Rules enforced outside the container can't block loopback.
The SDK doesn't check a URL's scheme, so your driver must refuse every scheme that you don't intend it to open, such as `javascript:`, `view-source:`, `data:`, and `file:`. Most drivers need only `http` and `https`. The example policy later in this section allows only `http` and `https` URLs, plus `about:blank`.
A `file:` URL lets Claude read files on the browser host. A `javascript:` URL runs script in the current page, even when `javascript_exec` is off. Egress rules don't stop either one.
A URL policy is a function that you pass as `url_policy`. You write the policy, and you're responsible for making it ready for production. Before your `navigate` runs, the SDK calls the policy with the call's context and the URL as Claude wrote it.
Return nothing to allow the URL. To refuse it, raise `ToolError` (throw it in TypeScript). Claude reads the error's message, and `navigate` doesn't run. The policy checks only the URL in each `navigate` call. It isn't a network control.
This is the policy from the [advanced example](#quick-start). It allows `about:blank`, plus two sites and their subdomains over `http` and `https`:
Python
TypeScript
Python
```python
import re
from urllib.parse import urlsplit
from anthropic.tools import ToolError
from anthropic.tools.browser import BetaURLContext
ALLOWED_HOSTS = ("example.com", "iana.org")
SCHEME_PREFIX = re.compile(r"[a-z][a-z0-9+.-]*:", re.IGNORECASE)
def is_allowed(url: str) -> bool:
# An example, not a production policy.
if url.lower() == "about:blank":
return True
with_scheme = url if SCHEME_PREFIX.match(url) else f"https://{url}"
# A browser reads "\" as "/" in a web URL.
try:
parts = urlsplit(with_scheme.replace("\\", "/"))
except ValueError:
return False
host = parts.hostname or ""
listed = any(host == name or host.endswith(f".{name}") for name in ALLOWED_HOSTS)
return parts.scheme in ("http", "https") and listed
def url_policy(context: BetaURLContext, url: str) -> None:
if not is_allowed(url):
raise ToolError(f"blocked: {url} is not on an allowed host")
browser = MyBrowser(backend, url_policy=url_policy)
```
The SDK calls the policy only for `navigate`, and not for `"back"`, `"forward"`, or `"reload"`. Claude can leave out the scheme, as in `example.com`, so before it reads the host, the example adds `https://` to a URL that doesn't start with a scheme. Your `navigate` gets the URL as Claude wrote it. Add the scheme there with the same test, so that the browser opens the URL your policy checked.
The example isn't production grade. A production policy needs much more, in areas such as these:
- Links Claude clicks, forms it submits, redirects, and the requests a page makes on its own. Only your driver sees them. See [Intercept requests in the driver](#intercept-requests-in-the-driver).
- Hostnames and URLs that come from page content, which an attacker can choose.
- Parsing each URL the way the browser does, not finding the hostname with a plain string split.
- URL schemes. The SDK doesn't check them, so refuse every scheme that you don't intend your driver to open.
- Egress rules on the container, for what no URL check can see. See [Put egress policy on the container](#put-egress-policy-on-the-container).
If you pass `url_policy=None`, the SDK refuses every `navigate` to a URL, so a `None` read from your configuration can't leave URLs unchecked by accident. In TypeScript, `undefined` leaves the option unset, the same as not passing it.
### Intercept requests in the driver
The URL policy checks only the URL in a `navigate` call. A link Claude clicks, a form it submits, a redirect, or an image or script on an allowed page can still reach a host the policy would refuse. Use [egress rules](#put-egress-policy-on-the-container) to block those hosts.
A driver with request interception can also check those requests in its request hook, the function your automation library calls before each request. Call the function that your policy uses, so that you write the rules once:
Python
TypeScript
Python
```python
class MyBrowser(BetaAbstractBrowserToolset20260801):
...
# Registered on a Playwright browser context with context.route("**/*", self._guard)
def _guard(self, route):
# is_allowed is the function from "Write a URL policy"
if not is_allowed(route.request.url):
return route.abort("blockedbyclient")
route.continue_()
```
A request hook like this one doesn't see WebSocket handshakes, service-worker requests, or redirect hops. Block service workers. Check WebSocket handshakes and redirect hops with a hook that sees them. The example policy refuses `ws://` and `wss://` URLs, so change `ws://` to `http://` and `wss://` to `https://` before you pass a WebSocket URL to `is_allowed()`.
### Put egress policy on the container
Interception can't see every request the browser makes, and the URL policy doesn't see where a name resolves. An egress policy that the container's network enforces covers both:
- Block link-local and private address ranges in IPv4 and IPv6. That includes the cloud metadata address `169.254.169.254`.
- Allow outbound connections only to the hosts the task needs. If your rules match IP addresses, resolve the hostnames you allow when the container starts.
- Allow DNS only to the container's resolver.
Rules enforced outside the browser's container, such as a Kubernetes NetworkPolicy or a cloud firewall, don't see loopback inside it. With only those rules, a page can reach anything listening there, including a DevTools port, which shows a list of the browser's open tabs and the address that controls each one.
### Confine uploads and downloads
`file_upload` is off by default. With no `file_policy`, the SDK refuses every upload that gives a path or a [document ID](agents-and-tools-tool-use-browser-use-tool.md#upload-files). To enable uploads, pass a `BetaLocalFilePolicy` with one upload directory that holds only the task's files:
Python
TypeScript
Python
```python
from anthropic.tools.browser import BetaLocalFilePolicy
# A MyBrowser that also implements file_upload
browser = MyBrowser(
backend,
configs={"file_upload": {"enabled": True}},
confirm=make_confirm(), # required for file_upload; see Gate consequential members
url_policy=url_policy,
file_policy=BetaLocalFilePolicy(
upload_roots=["/task/uploads"],
download_dir="/task/downloads",
expose_download_paths=False,
),
)
```
The SDK resolves each upload path, following symlinks, and refuses any path outside the upload roots. The file policy raises a configuration error for a download directory that is an upload root, is inside one, or contains one. That check can miss a symlink, so don't let one make the download directory the same as an upload root, or put one inside the other. The SDK includes a download's `path` in the state report only when `expose_download_paths` is true and the file is inside the download directory.
The shipped file policy checks paths on the filesystem of the process that runs the SDK. It protects only a browser that shares that filesystem. For a remote browser, follow [Remote and hosted browsers](#remote-and-hosted-browsers) instead.
Set up downloads this way:
- Create the download directory yourself with mode `0700`, and mount it `noexec,nosuid,nodev`.
- Keep the directory out of reach of other tools that Claude can call, such as a shell or a file tool.
- In a `download_failed` state change, write `error` as a fixed phrase. An exception's text can contain the path or the URL.
- Don't read a downloaded file into the conversation, or run it, until a person decides to.
### Gate consequential members
`javascript_exec` and `file_upload` are off by default. If you enable either one without a `confirm` callable, the constructor raises a configuration error. With a `confirm` callable, the SDK calls it before every call that's about to run. Without one, nothing is asked. In TypeScript, `confirm: null` doesn't raise the configuration error, and the SDK refuses every call to any member.
Return `True` to run the call, or `False` to refuse it. When your callable asks a person, show them the member, the page's URL, and the call's input. First, escape every character outside printable ASCII in the URL and the input, because both can carry text from the page.
This example asks about the two gated members through your own `ask_user()` function, and approves the rest:
Python
TypeScript
Python
```python
import json
from collections.abc import Callable
from urllib.parse import urlsplit
from anthropic.tools.browser import BetaConfirmContext
GATED = {"javascript_exec", "file_upload"}
def shown(value: object) -> str:
"""A value as JSON, with every character outside printable ASCII escaped."""
return json.dumps(value, ensure_ascii=True, indent=2)
def make_confirm() -> Callable[[BetaConfirmContext], bool]:
granted: set[tuple[str, str, str]] = set()
def confirm(context: BetaConfirmContext) -> bool:
name = context.member
if name not in GATED:
return True
detail = shown(context.input.to_dict())
page = context.tab_url
where = shown(page) if page else "a tab with no URL"
question = f"Allow {name} on {where}?\n{detail}"
if page is None or urlsplit(page).scheme not in ("http", "https"):
return ask_user(question) # no web origin: ask every time
# An approval covers only this exact input on this page.
key = (name, page, detail)
if key not in granted and ask_user(question):
granted.add(key)
return key in granted
return confirm
# A MyBrowser that also implements javascript_exec and file_upload
# file_upload also needs the file_policy from "Confine uploads and downloads"
browser = MyBrowser(
backend,
configs={"javascript_exec": {"enabled": True}, "file_upload": {"enabled": True}},
confirm=make_confirm(),
url_policy=url_policy,
)
```
Each call to `make_confirm()` returns a callable with no approvals. Call it once for each toolset, and give each user their own toolset.
An approval covers the page as the last state report showed it, and the page can change before the call runs. Purchases, sent messages, and accepted terms go through ordinary members such as `left_click` and `type`, so `confirm` can't pick them out by name. To have a person approve them, ask about those members too.
Don't enable `javascript_exec` unless [egress rules](#put-egress-policy-on-the-container) limit the browser's outbound connections to the hosts the task needs. A script can send the page's content to any address that the browser can reach.
A `javascript:` URL in a `navigate` call also runs script in the current page, even when `javascript_exec` is off. `confirm` sees that call as a `navigate`, so the example's `confirm` callable would approve it. Your driver must refuse `javascript:` URLs. In the example, the [URL policy](#write-a-url-policy) refuses them before `confirm` runs.
### Isolate the browser host
Run the browser in a dedicated, minimal-privilege container or VM for each session:
- Run as a non-root user, with a read-only root filesystem where the browser allows it.
- Mount nothing from the host beyond the upload and download directories you configured, if any.
- Keep credentials out of the environment, and start from a fresh browser profile.
- Share no filesystem with other tools Claude can call.
The browser profile must not be signed in to any account whose data or actions you wouldn't hand to Claude. `javascript_exec` runs with the page's own authority: its cookies, its storage, and its signed-in sessions.
Run the code that calls the API outside the browser's container, because that code holds your API key and the conversation. The tool runner and `tool_result` both run the toolset in that code's process, so the browser doesn't share the toolset's filesystem. Treat the browser as remote: [Remote and hosted browsers](#remote-and-hosted-browsers) applies.
Treat everything a page returns as untrusted, including page text, screenshots, console and network entries, tab titles, and download names.
### Remote and hosted browsers
Some browsers don't share a filesystem with the process that runs the SDK. Examples are a browser in another container, one you reach at a DevTools URL, and one from a hosted browser service. With these, the URL policy, request interception, and `confirm` still run in your process.
With a hosted browser, the provider controls egress and host isolation. Your own egress policy doesn't apply there, so the driver's request hook is your only check on the browser's requests. Find out what the browser's network can reach.
The shipped path checks don't protect a remote browser. `BetaLocalFilePolicy` checks paths on the filesystem of the process that runs the SDK, and the browser reads and writes its own filesystem.
The SDK can't detect that a browser is remote. So for a remote browser, keep `file_upload` off unless your driver checks upload paths where the browser runs, with a `BetaFilePolicy` of its own. A `BetaFilePolicy` vets each upload's paths and document IDs, and determines whether Claude sees a download's path.
Have a remote browser refuse downloads, unless its own host has the download setup from [Confine uploads and downloads](#confine-uploads-and-downloads).
Keep the provider's API key and the session's connection URL, which can contain a key, out of logs, tool results, and error text. If the provider records sessions, the recording is another copy of everything Claude saw and typed, and the provider's retention terms apply to it.
## Computer toolset
`BetaAbstractComputerToolset20260801` is the class for the [computer use tool](agents-and-tools-tool-use-computer-use-tool.md). A driver is a subclass with one method for each tool, such as `screenshot` or `left_click`. Start from a partner's driver under [Partner integrations](#partner-integrations). To write your own, the claude-quickstarts repository has a [minimal VNC example](https://github.com/anthropics/claude-quickstarts/tree/main/computer-toolset) in Python and TypeScript. It controls a desktop over VNC, and it isn't production code.
The class takes `configs`, `confirm`, and `tool_configs`, and you pass them as you do for the browser class. [Customize a driver](#customize-a-driver), [Handle errors](#handle-errors), [Start calls while the response streams](#start-calls-while-the-response-streams), and [Run without the tool runner](#run-without-the-tool-runner) apply to it too, with these differences:
- **Browser-only options:** The class has no [URL policy](#write-a-url-policy), no [file policy](#confine-uploads-and-downloads), and no [state report](#report-browser-state).
- **`configs`:** Every tool you implement is on by default. The per-tool settings are listed under [Tool parameters](agents-and-tools-tool-use-computer-use-tool.md#tool-parameters).
- **`confirm`:** If your class implements `type`, `key`, or `hold_key`, the constructor raises a configuration error unless you pass a `confirm` callable or turn those tools off with `configs`. A class that overrides `execute` counts as implementing all three.
- **Skipped calls:** After a failed computer call, the tool runner answers the turn's later computer calls with `Not executed: an earlier computer action in this turn failed.` Browser calls get a different text. In a loop you write, answer the skipped computer calls with that exact text ([Batch actions in the computer use tool](agents-and-tools-tool-use-computer-use-tool.md#batch-actions)).
- **`execute`:** In TypeScript, an `execute` override types `name` as `BetaComputerMemberName` and `input` as `BetaComputerMemberInput`. Both come from `@anthropic-ai/sdk/resources/beta`.
- **Error text:** The SDK doesn't hide local paths in a computer tool's error text or in the text a tool returns. Claude reads both, cut at 4,096 characters. Catch exceptions in your tools, and raise `ToolError` (throw it in TypeScript) with your own text.
### Write a desktop driver
This driver implements five of the 17 tools listed under [Available actions](agents-and-tools-tool-use-computer-use-tool.md#available-actions). A tool you don't implement is sent to the API as disabled, as [Implement a driver](#implement-a-driver) explains. In the example, `display` stands for your own wrapper around whatever controls the desktop, such as a VNC client or `xdotool`, and `ask_user()` stands for your own function that asks a person.
Python
TypeScript
Python
```python
from anthropic import Anthropic
from anthropic.tools.computer import (
BetaAbstractComputerToolset20260801,
BetaComputerCursorPositionResult,
BetaScreenshotResult,
BetaToolsetCallContext,
)
from anthropic.types.beta import (
BetaComputerCursorPositionInput,
BetaComputerKeyInput,
BetaComputerLeftClickInput,
BetaComputerScreenshotInput,
BetaComputerTypeInput,
)
class MyDesktop(BetaAbstractComputerToolset20260801):
def __init__(self, display, **options):
super().__init__(**options)
self.display = display
def screenshot(
self, context: BetaToolsetCallContext, input: BetaComputerScreenshotInput
) -> BetaScreenshotResult:
# Claude's coordinates are pixel positions in this image.
data = self.display.png_base64()
return BetaScreenshotResult(data=data, media_type="image/png")
def cursor_position(
self, context: BetaToolsetCallContext, input: BetaComputerCursorPositionInput
) -> BetaComputerCursorPositionResult:
x, y = self.display.cursor()
return BetaComputerCursorPositionResult(x=x, y=y)
def left_click(
self, context: BetaToolsetCallContext, input: BetaComputerLeftClickInput
) -> None:
# input.coordinate is [x, y], or None to click at the cursor. input.text is a
# modifier to hold, such as "shift". Nothing to return: Claude reads "Clicked."
self.display.click(input.coordinate, input.text)
def type(
self, context: BetaToolsetCallContext, input: BetaComputerTypeInput
) -> None:
self.display.type(input.text)
def key(self, context: BetaToolsetCallContext, input: BetaComputerKeyInput) -> None:
self.display.press(input.text, input.repeat or 1)
def close(self) -> None:
super().close() # first, so no call is still using the desktop when it closes
self.display.close()
client = Anthropic()
with MyDesktop(
display,
# required for type and key; see Run the computer toolset safely
confirm=lambda context: ask_user(f'Allow the "{context.member}" tool?'),
) as desktop:
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
tools=[desktop],
messages=[
{"role": "user", "content": "Open the calculator and compute 17 * 23."}
],
)
for message in runner:
print(message)
```
The `confirm` in this example asks a person before every call the driver runs. Before you run the driver against anything but a throwaway machine, read [Run the computer toolset safely](#run-the-computer-toolset-safely).
Four tools have no input fields: `screenshot`, `cursor_position`, `left_mouse_down`, and `left_mouse_up`. Every input type, including theirs, comes from `anthropic.types.beta`.
In TypeScript, write tools as methods, not arrow-function fields. [Implement a driver](#implement-a-driver) gives the reason.
### Scale coordinates and size images
Every point Claude sends is a pixel position in the screenshots you return: each `coordinate` and `start_coordinate`, and both corners of a `zoom` `region`. The SDK passes them to your tools unchanged.
If your screenshots are a different size from the display, convert in both directions in your driver: Claude's points to display pixels, and the cursor position you report to screenshot pixels. Keep the screenshot size the same for the whole session, and give it the display's aspect ratio:
Python
TypeScript
Python
```python
from anthropic.tools import ToolError
SCREENSHOT_SIZE = (1280, 720) # the size of every full screenshot the driver returns
DISPLAY_SIZE = (2560, 1440)
def to_display(coordinate: list[int]) -> tuple[int, int]:
x, y = coordinate
width, height = SCREENSHOT_SIZE
if not (0 <= x < width and 0 <= y < height):
# Refuse the point. Moving it into range would click where Claude didn't choose.
raise ToolError(f"[{x}, {y}] is outside the {width}x{height} screenshot")
return x * DISPLAY_SIZE[0] // width, y * DISPLAY_SIZE[1] // height
def to_screenshot(x: int, y: int) -> tuple[int, int]:
width, height = DISPLAY_SIZE
return x * SCREENSHOT_SIZE[0] // width, y * SCREENSHOT_SIZE[1] // height
to_display([640, 360]) # (1280, 720)
```
Call `to_display()` on each `coordinate` and `start_coordinate` before you act on it, and `to_screenshot()` on the position that `cursor_position` reports. A click or scroll with no `coordinate` acts at the cursor, so it has nothing to convert. Scale a `zoom` `region` by the same factor. A `zoom` image doesn't change this: the next points Claude sends are still pixel positions in the full screenshot.
The SDK never reads or resizes an image. The API rejects an image over the model's limits, which ends the run. Scale each screenshot and `zoom` image in the driver. See [Size screenshots to fit image limits](agents-and-tools-tool-use-computer-use-tool.md#handle-coordinate-scaling-for-higher-resolutions). On a long run, one request can hold more than 20 images, and the API then holds each one to a stricter limit. See [Manage screenshot history](agents-and-tools-tool-use-computer-use-tool.md#manage-screenshot-history).
### Input checks and results
Don't rely on the SDK to check a call's input. Have your driver check the fields it uses and refuse a call it can't run: raise `ToolError` (throw it in TypeScript). Claude reads the message and can send a corrected call.
The SDK doesn't limit a `duration`, a `repeat` count, or a `scroll_amount`. Step 4 under [Run the computer toolset safely](#run-the-computer-toolset-safely) covers them.
What a tool returns determines what Claude reads:
| Tool | Returns | Claude reads |
|:---------------------|:-----------------------------------|:--------------------------------------------------------------------------------------------|
| `screenshot`, `zoom` | `BetaScreenshotResult` | One image block |
| `cursor_position` | `BetaComputerCursorPositionResult` | `X={x},Y={y}` |
| Every other tool | Nothing, or one line of text | A short confirmation, such as `Clicked.`, then the returned line in a text block of its own |
### Run the computer toolset safely
What's on the screen steers Claude's next action. A page or a notification can attempt to make Claude type into the wrong window, or trigger an action with real effects.
A driver that implements `type`, `key`, or `hold_key` needs a `confirm` callable. Without one, the constructor raises a configuration error, unless `configs` turns those tools off. The SDK itself asks no one: it runs every call that your `confirm` approves, and with no `confirm` it runs every call, including every click. Every computer tool you implement is on by default.
Before you run a driver against anything but a throwaway machine, take these five steps:
1. Isolate the desktop. Run it in a dedicated, minimal-privilege container or VM for each session, with no credentials and no host mounts. Install only the applications the task needs. Run the code that calls the API outside it.
2. Gate actions that have real effects with `confirm`. A purchase or a sent message is an ordinary `left_click`, `type`, or `key`, and `confirm` receives the tool and its input, not the screen. So choose which tools need approval based on the applications Claude can reach on the desktop.
3. Keep terminals, run dialogs, and launchers off the desktop unless the task needs one. When one has keyboard focus, `type`, `key`, and `hold_key` run whatever Claude types, and a click can start a program. If the task needs one, ask a person before keyboard input and clicks, and isolate the desktop so that a command can reach no further than the task needs.
4. Refuse input your desktop shouldn't honor, such as a point outside the screenshot, a `wait` of several minutes, or a very large `repeat` or `scroll_amount`. Raise `ToolError` (throw it in TypeScript) instead of moving the value into range.
5. Treat everything on the screen as untrusted, including window titles and clipboard text. Don't run it or pass it on unchecked.
The SDK applies step 2 through the callable you pass. The other steps are up to your driver and your deployment. The precautions under [Security considerations for the computer use tool](agents-and-tools-tool-use-computer-use-tool.md#security-considerations) apply as well.
The following `confirm` asks a person before any keyboard input, through your own `ask_user()` function, and approves every other call. `context.member` is the tool's name. To have a person approve clicks too, set `ASK_FIRST` to `KEYBOARD | CLICKS`.
Python
TypeScript
Python
```python
from anthropic.tools.computer import BetaComputerConfirmContext
KEYBOARD = {"type", "key", "hold_key"}
CLICKS = {
"left_click",
"right_click",
"middle_click",
"double_click",
"triple_click",
"left_click_drag",
"left_mouse_down",
"left_mouse_up",
}
ASK_FIRST = KEYBOARD
def confirm(context: BetaComputerConfirmContext) -> bool:
if context.member not in ASK_FIRST:
return True
# shown is the function from "Gate consequential members".
detail = shown(context.input.to_dict())
return ask_user(f'Allow the "{context.member}" tool with this input?\n{detail}')
desktop = MyDesktop(display, confirm=confirm)
```
A refused call gets an error result, and the run continues. For a refused `type` call, Claude reads `The user did not grant permission to run 'type'. Do not retry it unless the user asks you to.`
This `confirm` approves every tool that isn't in `ASK_FIRST`, including any tool you add later. To fail closed, approve only the tools with no effect on the desktop (`screenshot`, `zoom`, `cursor_position`, and `wait`) and ask about every other tool.
### Use both toolsets in one request
Pass both instances in `tools`. Each call carries its `toolset_name`, `browser` or `computer`, and the tool runner sends the call to the matching instance. After a failed call, the tool runner skips only the turn's later calls to the same toolset, so a failed computer call doesn't skip the turn's browser calls.
Python
TypeScript
Python
```python
# MyBrowser, backend, and url_policy are from the advanced example.
# confirm is the function from "Run the computer toolset safely".
with (
MyBrowser(backend, url_policy=url_policy) as browser,
MyDesktop(display, confirm=confirm) as desktop,
):
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
tools=[browser, desktop],
messages=[
{
"role": "user",
"content": "Copy the heading on example.com into the open text editor.",
}
],
stream=True,
run_tools_eagerly=True, # so a call can start before the response ends
)
for stream in runner:
print(stream.get_final_message())
```
In a loop you write, answer each call with `tool_result` on the instance whose `toolset_name` matches the call's `toolset_name`. In each turn, track failed calls for each toolset separately, and answer a skipped call with that toolset's own text. [Run without the tool runner](#run-without-the-tool-runner) has the browser's text, and the Skipped calls bullet at the top of this section has the computer's.
## Reference
The constructor options have the same meaning in both SDKs:
| Python | TypeScript | Sets |
|:----------------------------|:---------------|:---------------------------------------------------------------------|
| `configs` | `configs` | Which members are enabled |
| `confirm` | `confirm` | The callable that approves or refuses each call |
| `url_policy` | `urlPolicy` | Your URL policy, which the SDK calls before each `navigate` to a URL |
| `file_policy` | `filePolicy` | Upload roots and download path exposure |
| `tool_configs` | `toolConfigs` | Fields for the `tools` entry, such as `cache_control` |
| The `_browser_state` method | `browserState` | The state report |
The browser class takes every option in the table. The computer class takes `configs`, `confirm`, and `tool_configs`.
You can't change an option after construction. The [Python browser toolset guide](https://github.com/anthropics/anthropic-sdk-python/blob/main/browser-toolset.md), the [TypeScript browser toolset guide](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/browser-toolset.md), the [Python computer toolset guide](https://github.com/anthropics/anthropic-sdk-python/blob/main/computer-toolset.md), and the [TypeScript computer toolset guide](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/computer-toolset.md) describe each option. The Python guides also cover the async classes, `BetaAsyncAbstractBrowserToolset20260801` and `BetaAsyncAbstractComputerToolset20260801`.
## Limitations
- **The SDK doesn't include a browser, a desktop, a ready-made driver, or a URL policy:** You supply them. See [Partner integrations](#partner-integrations), [Implement a driver](#implement-a-driver), and [Write a URL policy](#write-a-url-policy).
- **The URL policy sees only `navigate` calls:** It doesn't see the requests a page makes, or pages that open any other way, such as from a link Claude clicks or a redirect. See [Intercept requests in the driver](#intercept-requests-in-the-driver).
- **An approval is based on the last state report:** The page can change after that report. The SDK doesn't check the page again before the call runs.
- **Calls on one toolset run one at a time:** You can't turn this off.
- **The SDK doesn't check that tab IDs are unique or how many tabs there are, and doesn't always check that one tab is active:** The API rejects a report that breaks those rules.
- **For a computer call, `confirm` receives the tool and its input, not the screen:** You can't tell from them what a click at a given point does.
- **The SDK doesn't resize a computer toolset's images:** The API rejects an image over the model's limits. See [Scale coordinates and size images](#scale-coordinates-and-size-images).
## Next steps
[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)
The member tools, the `browser_state` block, and the tool's security considerations.
[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)
The 17 tools, coordinates and image limits, and the tool's security considerations.
[Tool runner (SDK)](agents-and-tools-tool-use-tool-runner.md)
How the SDK runs the loop, and how to change the messages it sends.
[Mitigate jailbreaks and prompt injections](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-mitigate-jailbreaks.md)
Guardrails for any application that reads untrusted content.
---
## Browser use tool - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-browser-use-tool.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fbrowser-use-tool)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
Browser use tool
[ZDR](../Other/manage-claude-api-and-data-retention.md)
Eligible
excludes [Covered Models](../Other/manage-claude-api-and-data-retention.md#model-specific-data-retention-requirements)
# Browser use tool
Copy page
Let Claude navigate, read, and interact with webpages in your own browser environment with the browser use tool.
Copy page
**Start with the SDK toolsets:** The Python and TypeScript SDKs have a browser toolset class, in beta. Start from [a partner's integration](agents-and-tools-tool-use-browser-use-sdk.md#partner-integrations), or see [Browser and computer use with the SDK toolsets](agents-and-tools-tool-use-browser-use-sdk.md). Use this page as the tool reference, or when you handle the tool calls yourself.
The browser use tool lets Claude navigate, read, and interact with webpages in a browser that your application runs. Claude works with the page both through its structure (the accessibility tree, elements, forms, and tabs) and through screenshots and viewport coordinates.
The tool is an Anthropic-defined [client toolset](agents-and-tools-tool-use-tool-reference.md#client-toolsets): one `browser_toolset_20260801` entry in `tools` gives Claude 27 member tools by default, such as `navigate`, `read_page`, `left_click`, and `screenshot`, plus four more when you [enable them](#enable-optional-member-tools). Your application runs every call against its own browser automation; nothing runs on Anthropic's side. The tool isn't currently available in [Claude Managed Agents](../Other/managed-agents-tools.md).
Choose browser use when the task stays inside webpages and means acting on them, or when pages build their content with JavaScript. When a task needs a whole desktop, use the [computer use tool](agents-and-tools-tool-use-computer-use-tool.md), which works through screenshots and coordinates alone. For reading pages you can point Claude to, or finding sources on the web, the [web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md) and [web search tool](agents-and-tools-tool-use-web-search-tool.md) are lighter. They're [server tools](agents-and-tools-tool-use-server-tools.md) that the API runs for you, with no browser to operate.
With browser use, Claude reads and acts on live webpages, so everything a page supplies is untrusted input and the actions Claude takes can have real effects. See [Security considerations](#security-considerations) before you deploy.
## Quick start
The browser use tool is available on the Claude API and [Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md): add one entry of type `browser_toolset_20260801`, with no `name`, to the `tools` array of a [Messages API](../Endpoints/messages-create.md) request.
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=2048,
tools=[{"type": "browser_toolset_20260801"}],
messages=[
{
"role": "user",
"content": "Open example.com/docs and tell me how to get started.",
}
],
)
print(response)
```
Claude's first response ends with `stop_reason: "tool_use"` and carries one or more member `tool_use` blocks, each naming a member tool in `name` and carrying `"toolset_name": "browser"`:
Output
```python
{
"id": "msg_01HCDu4XSTLzTAcodEQ58vDo",
"type": "message",
"role": "assistant",
"model": "claude-opus-5-5",
"content": [
{
"type": "text",
"text": "I'll open the documentation and read the page to find the getting-started instructions."
},
{
"type": "tool_use",
"id": "toolu_01NRLabsLyVHZPKxbKvkfSMn",
"name": "navigate",
"toolset_name": "browser",
"input": { "url": "https://example.com/docs" }
},
{
"type": "tool_use",
"id": "toolu_01UvHU5cDyTZ2vXKf5wCkPqR",
"name": "read_page",
"toolset_name": "browser",
"input": { "filter": "interactive" }
}
],
"stop_reason": "tool_use",
"stop_sequence": null
}
```
Your executor (the part of your application that drives the browser and produces tool results) runs `navigate`, then `read_page`. Your application returns one `tool_result` per block in its next request, echoing `toolset_name` on each. The `navigate` result reports the tab it loaded in a `browser_state` block; the `read_page` result is text in which every element carries a reference:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01NRLabsLyVHZPKxbKvkfSMn",
"toolset_name": "browser",
"content": [
{ "type": "text", "text": "Navigated to https://example.com/docs" },
{
"type": "browser_state",
"tabs": [
{
"tab_id": "tab-1",
"title": "Documentation",
"url": "https://example.com/docs",
"active": true
}
]
}
]
},
{
"type": "tool_result",
"tool_use_id": "toolu_01UvHU5cDyTZ2vXKf5wCkPqR",
"toolset_name": "browser",
"content": [
{
"type": "text",
"text": "link \"Documentation\" [ref_1]\nlink \"Getting started\" [ref_2]\ntextbox \"Search docs\" [ref_3]\nbutton \"Search\" [ref_4]\nlink \"Pricing\" [ref_5]"
}
]
}
]
}
```
Claude now holds references it can act on, so its next turn can click `ref_2` to open the getting-started page, with no need to locate the link in a screenshot first.
## How browser use works
Browser use runs as an agent loop in your application: Claude returns member tool calls, your executor runs them against the browser, and you return the results until Claude answers in text.
1. 1
### Provide Claude with the browser use tool and a user prompt
- Add the `browser_toolset_20260801` entry, and optionally other tools, to your API request.
- Include a user prompt that calls for working with webpages, for example, "Open example.com/docs and tell me how to get started."
2. 2
### Claude responds with member tool calls
- Claude returns one or more `tool_use` blocks in a single assistant turn; several in one turn form a batch action, for example, `left_click`, then `type`, then `key`.
- Each block's `name` is the member name, each carries `"toolset_name": "browser"`, and `input` holds only that member's parameters, with no `action` field. The response's `stop_reason` is `tool_use`.
3. 3
### Run the calls in order and return results
- Iterate every `tool_use` block in `response.content` (don't assume there's exactly one) and run them sequentially, in the order they appear, because later calls usually depend on earlier ones.
- Return one `tool_result` per block in a new `user` message, matched by `tool_use_id`, and echo `"toolset_name": "browser"` on each. Every call must be answered or the next request is rejected.
- If a call fails, return `is_error: true` with a text description for that block, then apply the halt rule in [Batch actions](#batch-actions) to every later block in the turn.
4. 4
### Claude continues until the task is complete
- Claude reads the results (page text, accessibility trees, screenshots, tab state) and, if it needs more, returns further member calls, which takes you back to step 3.
- Otherwise, it returns a text response to the user.
Here's a skeleton of that loop's tool-call step in two parts. First, stub member handlers stand in for your browser automation. Five members (`navigate`, `read_page`, `left_click`, `type`, and `screenshot`) return the text, or for `screenshot` the image block, that becomes the result content, and the dispatcher raises an error for any member it doesn't implement.
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
# Placeholder image data; a real executor captures the viewport and returns the PNG bytes
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
def navigate(url):
return f"navigated to {url}"
def read_page():
return 'link "Docs" [ref_1]\nbutton "Search" [ref_2]'
def click(target):
# A target is an element reference from read_page or find, or a viewport coordinate
if target["type"] == "ref":
return f"clicked {target['ref']}"
return f"clicked at ({target['x']}, {target['y']})"
def type_text(text):
return f"typed: {text}"
def capture_screenshot() -> list[ImageBlockParam]:
# screenshot answers with an image block rather than text: return the result content list
return [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": PLACEHOLDER_PNG,
},
}
]
def handle_browser_action(name, tool_input):
if name == "navigate":
return navigate(tool_input["url"])
elif name == "read_page":
return read_page()
elif name == "left_click":
return click(tool_input["target"])
elif name == "type":
return type_text(tool_input["text"])
elif name == "screenshot":
return capture_screenshot()
# Handle other actions as needed
raise ValueError(f"Unknown or unimplemented member: {name}")
```
The second part runs a batch in order, dispatches each block to those handlers, echoes `toolset_name` on every result, and applies the halt rule from [Batch actions](#batch-actions), turning a handler error into an error result. The sampling loop that calls it is the one shown in [Understand the agent loop](agents-and-tools-tool-use-computer-use-tool.md#understanding-the-agentic-loop), with the browser toolset in `tools`.
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
NOT_EXECUTED = "Not executed: an earlier action in this turn failed."
def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
"""
Run the browser actions in Claude's response in order and answer each
one. After the first failure the rest are skipped, because Claude planned
them assuming the earlier actions succeeded.
"""
tool_results: list[ToolResultBlockParam] = []
failed = False
for block in response.content:
# Only the browser toolset is declared; route other tools here if you add them
if block.type != "tool_use" or block.toolset_name != "browser":
continue
result: ToolResultBlockParam = {
"type": "tool_result",
"tool_use_id": block.id,
"toolset_name": "browser",
}
if failed:
result["content"] = NOT_EXECUTED
result["is_error"] = True
else:
try:
# A string or a list of content blocks; a real executor also adds a
# browser_state block to navigation and tab-management results
result["content"] = handle_browser_action(block.name, block.input)
except Exception as err:
result["content"] = f"Error: {err}"
result["is_error"] = True
failed = True
tool_results.append(result)
return tool_results
```
Dispatch each block on the pair (`toolset_name`, `name`) rather than on `name` alone, because a custom tool in the same request may share a member's name; [Client toolsets](agents-and-tools-tool-use-tool-reference.md#client-toolsets) describes the parts of this contract both toolsets share. If Claude names a member your executor doesn't implement, or one you disabled, answer that block with an [error result](#return-errors-from-your-executor) rather than dropping it.
When you stream the response, each member's `input` arrives as one complete `input_json_delta` rather than as fragments, so wait for the turn to finish before running the batch.
### Batch actions
A turn with several member calls is a batch action: run the calls in the order they appear, stop at the first failure, and answer every later call with `is_error: true` and the exact text `Not executed: an earlier action in this turn failed.` A batch uses the same response shape as [parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md); the difference is that you run the blocks in order rather than concurrently. Here Claude clicks the search box it found earlier, types a query, and presses Enter in one turn:
```python
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"name": "left_click",
"toolset_name": "browser",
"input": { "target": { "type": "ref", "ref": "ref_3" } }
},
{
"type": "tool_use",
"id": "toolu_01Ez4kLb1nQ2vXo8sJ9pWm3c",
"name": "type",
"toolset_name": "browser",
"input": { "text": "install" }
},
{
"type": "tool_use",
"id": "toolu_01FkP8rTz6uYh2mNq4LsXw7v",
"name": "key",
"toolset_name": "browser",
"input": { "text": "Enter" }
}
]
}
```
Your application returns three `tool_result` blocks in one `user` message, each carrying `toolset_name` and a short text acknowledgment such as `Clicked element ref_3.` Pressing Enter loads a results page, so the `key` result also carries a `browser_state` block with the tab's updated URL ([Tab context on other results](#tab-context-on-other-results)). If the click had failed instead, its result would carry your error text and the other two results would carry the halt text, as shown under [Return errors from your executor](#return-errors-from-your-executor).
You don't need to return a screenshot after every call. Claude typically ends a batch with an observation call (`screenshot`, `read_page`, or `get_page_text`), and your application can also attach its own observation, such as a fresh screenshot or accessibility tree, as an extra content block on the last result in the batch to save a round trip. Because a tab-management result must be exactly one `browser_state` block, attach it to the last result that isn't a tab-management call.
If your executor can run only one call per round trip, set `disable_parallel_tool_use` to `true` in `tool_choice` and Claude returns at most one member call per turn, at the cost of more round trips ([Disable parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md#disable-parallel-tool-use)). The rest of the contract under [Batch actions for the computer use tool](agents-and-tools-tool-use-computer-use-tool.md#batch-actions) carries over, including one `tool_result` for every `tool_use` in the next `user` message, except for two things: the halt text and what a successful result's `content` holds. Result content follows [Member tools](#member-tools) on this page instead: a `new_tab`, `switch_tab`, `close_tab`, or `list_tabs` result is exactly one `browser_state` block with no text or image ([Tab management results](#tab-management-results)), and any other member's result may add a `browser_state` block to its text or image ([Tab context on other results](#tab-context-on-other-results)). Where cache breakpoints inside a batch take effect is described in the `cache_control` row of the computer use tool's [Tool parameters](agents-and-tools-tool-use-computer-use-tool.md#tool-parameters).
### Targets and coordinates
Member tools that act on a location take a `target` object, which is either a viewport-pixel coordinate or a reference to an element that `read_page` or `find` returned. The [Member tools](#member-tools) tables write `Target` for a parameter that accepts either shape.
| Shape | `target.type` | Fields | Accepted by |
|:-------------------|:---------------|:-----------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `CoordinateTarget` | `"coordinate"` | `x`, `y` (integers, viewport pixels) | `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click`, `hover`, `left_click_drag` (`from` and `target`), `left_mouse_down`, `left_mouse_up`, `mouse_move`, `scroll` |
| `RefTarget` | `"ref"` | `ref` (an element reference such as `"ref_2"`) | `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click`, `hover`, `scroll_to`, `form_input`, `file_upload` |
**Coordinates are viewport pixels**, the pixel space of a full-viewport `screenshot` with the origin at the top left of the rendered page; there's no surrounding desktop or window frame. The toolset declares no display dimensions and Claude infers the viewport size from the screenshots you return, so keep them one consistent size. A `zoom` doesn't change the frame, so its `region` and any coordinates Claude emits after seeing the zoomed image are still full-viewport pixels.
**Screenshots must fit the image limits.** The API doesn't downscale toolset images: a screenshot or zoom image over your model's [image size limits](../Guides/build-with-claude-vision.md#evaluate-image-size), or over the stricter per-image limit that applies once a request holds [more than 20 images](../Guides/build-with-claude-vision.md#request-limits), is rejected. Resize before returning, and scale Claude's coordinates back up by the inverse of your factor before dispatching them ([Size screenshots to fit image limits](agents-and-tools-tool-use-computer-use-tool.md#handle-coordinate-scaling-for-higher-resolutions)).
**Element references come from `read_page` and `find`.** Each element in their output carries a tag such as `[ref_2]`, as in the Quick start result:
``` block
link "Documentation" [ref_1]
link "Getting started" [ref_2]
textbox "Search docs" [ref_3]
button "Search" [ref_4]
link "Pricing" [ref_5]
```
Claude passes a reference back as a `{"type": "ref", "ref": "ref_2"}` target on a later click, `hover`, `scroll_to`, `form_input`, or `file_upload` call, or as the `ref` parameter on `read_page` to read a subtree. Your executor assigns the references, keeps the mapping from each one to the underlying node (an accessibility-node ID, a stored selector, or equivalent), and acts on that node when a reference comes back.
References are scoped to the tab that produced them and stay valid until that tab navigates or its DOM changes materially. The API can't detect a stale or unknown reference, so when Claude passes a reference your executor no longer recognizes, return an error result such as `Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references.` Claude then reads the page again. Don't renumber references you've already handed out for a tab until it navigates, because that silently invalidates references Claude still holds.
Claude uses both targeting styles and switches between them based on what the page exposes; your prompt and what your executor returns steer the choice:
- **Prefer references where the page has a usable accessibility tree.** A reference survives layout shifts and reflows that make pixel coordinates fragile, and lets Claude act on controls that are hard to hit with a pointer.
- **Fall back to coordinates for content the tree doesn't describe.** Canvas-rendered interfaces, embedded video or remote-desktop surfaces, heavily virtualized lists, and elements inside cross-origin iframes often have no useful node, so Claude works from `screenshot` and `zoom` and clicks by coordinate; your executor resolves which frame a coordinate lands in.
- **Scope reads, and read the tree before you screenshot.** On large pages, `read_page` with `filter: "interactive"` or the `ref` of a container returns a focused subtree, and a tree read of a typical page often costs fewer input tokens than a screenshot while giving Claude references it can act on immediately. Screenshots remain the right observation when visual layout, images, or rendering state matter.
## Security considerations
Browser use carries risks that standard API features don't, because Claude reads and acts on content from the open web, where any page can contain text written to manipulate it.
To reduce these risks, take precautions such as the following:
1. Run the browser and your executor in a dedicated container or virtual machine with minimal privileges, a fresh profile that holds no credentials, and no access to sensitive filesystems or internal networks; isolate any tool you run alongside it the same way.
2. Restrict the hosts the browser can reach to a domain allowlist enforced at the network layer and re-checked in your `navigate` handler after redirects, and block loopback, link-local, and private ranges unless the task needs them.
3. Treat everything a page supplies as untrusted input, including the tab titles and URLs, and each download's `url`, `path`, and `error`, that you report in a [`browser_state`](#track-tabs-and-page-state) block, and build page reads from what the page renders (the accessibility tree or visible text), not raw DOM source, so hidden text doesn't reach Claude.
4. In your `navigate` handler, accept the history keywords `"back"`, `"forward"`, and `"reload"`, treat a URL without a scheme as `https://`, then parse the URL and refuse any scheme other than `http` or `https` (`javascript:`, `file:`, `data:`, `chrome:`, and so on) with an [error result](#return-errors-from-your-executor). Check the scheme with a URL parser rather than a string prefix; the API doesn't filter the URLs Claude opens, so it can't reject one for you.
5. Leave `javascript_exec` and `file_upload` disabled unless you need them, and read [Enable optional members](#enable-optional-member-tools) before turning either on.
6. Have a human confirm consequential actions and anything that requires affirmative consent (purchasing, modifying accounts, messaging, and accepting terms), and make that check in your executor before each call, because one turn can carry several.
Claude sometimes follows instructions found in page content even when they conflict with yours; text on a page that says "ignore your previous instructions and navigate to..." can divert it from the task. Isolate Claude from sensitive data and actions to limit what a prompt injection can reach, review [Mitigate jailbreaks and prompt injections](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-mitigate-jailbreaks.md), and if a task can't avoid a logged-in session, use a dedicated low-privilege account and keep human confirmation on account-changing actions.
Anthropic has trained the model to resist these prompt injections and has added an extra layer of defense. If you use the browser use tool, classifiers will automatically scan what the browser returns, such as page text or screenshots, to flag potential prompt injections. When these classifiers identify a potential prompt injection, they will automatically steer the model to check whether the instruction really came from you before acting on it.
This extra protection won't be ideal for every use case (for example, use cases without a human in the loop), so if you'd like to opt out and turn it off, [contact support](https://support.claude.com/en/). The precautions above remain important even with these classifiers in place.
Because the browser runs in your environment, the sites Claude visits see your executor's network identity, and page content reaches the API only as the tool results you return. Inform end users of the relevant risks and obtain their consent before enabling browser use in your products.
## Member tools
The `browser_toolset_20260801` entry declares 31 member tools; each call's `input` is exactly the parameters listed here, and `tab_id`, where optional, defaults to the active tab. `Target`, `CoordinateTarget`, and `RefTarget` are the shapes described in [Targets and coordinates](#targets-and-coordinates). Four members (`javascript_exec`, `file_upload`, `read_console`, and `read_network`) are disabled by default and appear only when you [enable them](#enable-optional-member-tools). The input bounds and output conventions noted in each member's row are stated to Claude, not enforced by the API, so validate inputs (including coordinates against your viewport) and apply the conventions in your executor.
Only `screenshot` and `zoom` require an [`image` block](agents-and-tools-tool-use-handle-tool-calls.md#handling-results-from-client-tools) in their result, and the four tab-management members (`new_tab`, `list_tabs`, `switch_tab`, and `close_tab`) return exactly one `browser_state` block (see [Tab management results](#tab-management-results)). Every other member returns a `text` block: either a short acknowledgment such as `Clicked element ref_2.` or the member's output. Any result other than a tab-management result may also carry an `image` block, typically a screenshot taken after the action, so Claude sees the outcome without a separate `screenshot` call; [Batch actions](#batch-actions) shows where to attach one in a batch. A member `tool_result` may contain only `text`, `image`, and `browser_state` content blocks.
### Navigation and capture
| Member | Input | Description |
|:-------------|:--------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `navigate` | `url`, `tab_id?` | Load an `http` or `https` URL, or move through history with `"back"`, `"forward"`, or `"reload"`. Treat a URL without a scheme as `https://` and refuse any other scheme with an error result. Return a short acknowledgment, plus a `browser_state` block when the tab's URL or title changed. |
| `screenshot` | `tab_id?` | Capture the viewport and return an `image` block. |
| `zoom` | `region`, `tab_id?` | Return a cropped, upscaled `image` of `region`, given as `[x0, y0, x1, y1]` in viewport pixels, for closer inspection of small text or controls. |
### Pointer
| Member | Input | Description |
|:------------------|:----------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `left_click` | `target: Target`, `modifiers?`, `tab_id?` | Left-click a coordinate or a referenced element. `modifiers` is a chord held during the click, for example, `"shift"` or `"ctrl+shift"`. |
| `right_click` | `target: Target`, `modifiers?`, `tab_id?` | Right-click a coordinate or element. |
| `middle_click` | `target: Target`, `modifiers?`, `tab_id?` | Middle-click a coordinate or element. |
| `double_click` | `target: Target`, `modifiers?`, `tab_id?` | Double left-click a coordinate or element. |
| `triple_click` | `target: Target`, `modifiers?`, `tab_id?` | Triple left-click a coordinate or element, which typically selects a line or paragraph. |
| `hover` | `target: Target`, `tab_id?` | Move the pointer over a coordinate or element without clicking. |
| `left_click_drag` | `from: CoordinateTarget`, `target: CoordinateTarget`, `tab_id?` | Press at `from`, drag to `target`, and release. |
| `left_mouse_down` | `target: CoordinateTarget`, `tab_id?` | Press and hold the left button at a coordinate; pair with `left_mouse_up` for a custom drag. |
| `left_mouse_up` | `target: CoordinateTarget`, `tab_id?` | Release the left button at a coordinate. |
| `mouse_move` | `target: CoordinateTarget`, `tab_id?` | Move the pointer to a coordinate. |
| `scroll` | `target: CoordinateTarget`, `scroll_direction`, `scroll_amount?`, `tab_id?` | Scroll at a viewport position. `scroll_direction` is `"up"`, `"down"`, `"left"`, or `"right"`; `scroll_amount` is in scroll-wheel notches, 1 to 10, default 3. |
| `scroll_to` | `target: RefTarget`, `tab_id?` | Scroll a referenced element into view. |
### Keyboard and timing
| Member | Input | Description |
|:-----------|:------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `type` | `text`, `tab_id?` | Type a literal string at the current focus. |
| `key` | `text`, `repeat?`, `tab_id?` | Press a key or chord. `text` is a single key (`"Enter"`), a chord joined with `+` (`"ctrl+a"`), or a space-separated sequence (`"Backspace Backspace"`); `repeat` is 1 to 100, default 1. |
| `hold_key` | `text`, `duration`, `tab_id?` | Hold a key or chord for `duration` seconds, 0 to 30. |
| `wait` | `duration`, `tab_id?` | Pause for `duration` seconds, 0 to 30. |
### Page reading
| Member | Input | Description |
|:----------------|:---------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `read_page` | `filter?`, `depth?`, `ref?`, `tab_id?` | Return the page's accessibility tree as text with each element tagged with a reference such as `[ref_2]`. With `filter` omitted, return every visible element; with `"interactive"`, only visible interactive elements; with `"all"`, also elements outside the viewport. `depth` caps the tree depth (minimum 1, default 15) and `ref` scopes the read to that element's subtree. Cap the output at 50,000 characters and say so in the text; Claude then narrows with a smaller `depth` or a `ref`. |
| `find` | `query`, `tab_id?` | Search for elements matching a natural-language description such as `"search field"` or `"add to cart button"`, and return up to 20 matches in the same tagged format as `read_page`. |
| `get_page_text` | `tab_id?` | Return the page's visible text as plain text, prioritizing the main article content; suited to articles, documentation, and other text-heavy pages. |
### Forms and files
| Member | Input | Description |
|:------------------------------------|:----------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `form_input` | `target: RefTarget`, `value`, `tab_id?` | Set a form element's value directly. `value` is a `string`, `number`, or `boolean`; use a `boolean` for checkboxes and an option's value or visible text for selects. |
| `file_upload` (disabled by default) | `target: RefTarget`, `paths?`, `document_ids?`, `tab_id?` | Set the files on a file-input element from `paths` on the executor's filesystem, `document_ids` your application has staged, or both; at least one is required. See [Upload files](#upload-files). |
### Diagnostics and scripting
| Member | Input | Description |
|:----------------------------------------|:------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `read_console` (disabled by default) | `tab_id?` | Return the tab's console entries (log, warning, and error lines) accumulated since the last read, one line per entry. See [Read console and network activity](#read-console-and-network-activity). |
| `read_network` (disabled by default) | `tab_id?` | Return the tab's network requests (method, URL, status, MIME type, timing) since the last read, one line per entry. |
| `javascript_exec` (disabled by default) | `text`, `tab_id?` | Run `text` as JavaScript in the page context and return the value of the last expression as text. See [Enable optional members](#enable-optional-member-tools). |
### Tab management
| Member | Input | Description |
|:-------------|:--------------------|:---------------------------------------|
| `new_tab` | (none) | Open a tab and make it the active tab. |
| `list_tabs` | (none) | Report the tab inventory. |
| `switch_tab` | `tab_id` (required) | Make `tab_id` the active tab. |
| `close_tab` | `tab_id` (required) | Close `tab_id`. |
On success, each of these returns exactly one `browser_state` block and no text or image; see [Tab management results](#tab-management-results).
## Configure the toolset
Besides `type`, the toolset entry accepts `configs`, `cache_control`, and `allowed_callers`; the rules these fields share with the computer use toolset are listed under [Client toolsets](agents-and-tools-tool-use-tool-reference.md#client-toolsets), and this section covers the browser-specific defaults. `configs` is an object keyed by member name, and each member's value accepts two fields:
| Field | Default | Meaning |
|:----------------|:--------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `enabled` | `true`, except `false` for the four [optional members](#enable-optional-member-tools) | Whether the member is offered to Claude. |
| `defer_loading` | `false` | Whether the toolset's definition is deferred for tool search. Must resolve to the same value on every enabled member. With the four optional members left disabled, deferring the toolset means setting it on the other 27; see [Client toolsets](agents-and-tools-tool-use-tool-reference.md#client-toolsets). |
### Enable or disable member tools
List only the members you want to change in `configs`; every member you omit keeps its default. For example, an executor that implements console reads but not low-level pointer or key-hold control turns `read_console` on and withholds three members:
```python
{
"type": "browser_toolset_20260801",
"configs": {
"read_console": { "enabled": true },
"left_mouse_down": { "enabled": false },
"left_mouse_up": { "enabled": false },
"hold_key": { "enabled": false }
}
}
```
A disabled member disappears from the definition Claude sees; that doesn't guarantee Claude never names it, so your executor still answers such a call with an [error result](#return-errors-from-your-executor).
### Combine with other tools
Declare the browser use tool alongside your own tools and other Anthropic-provided tools in the same `tools` array. A custom tool may share a member's name (your own `navigate`, for example), because `toolset_name` distinguishes Claude's calls, but no other entry may be named `browser`, and a request may contain only one browser toolset entry.
You can also declare it alongside the [computer use tool](agents-and-tools-tool-use-computer-use-tool.md), either the toolset or an earlier computer use tool version. The two work independently, each in its own coordinate frame (viewport pixels here, desktop screenshot pixels there), and Claude's calls to members that share a name, such as `screenshot` or `key`, are told apart by `toolset_name`.
## Enable optional members
Four member tools are disabled by default: `javascript_exec` and `file_upload` because they widen what a manipulated page could make Claude do, and `read_console` and `read_network` because not every browser automation stack can supply those logs and they widen what page-controlled content reaches Claude. Enable each one with `configs` (for example, `"configs": {"file_upload": {"enabled": true}}`) only when your executor implements it and the task needs it.
### Upload files
`file_upload` sets the files on an `` element directly, which is more reliable than driving a native file chooser. Its `target` is a reference only, because the call needs the element's identity, and it takes `paths`, `document_ids`, or both:
- `paths` are file paths on the executor's filesystem, for deployments where the executor can read your application's files directly (the same condition under which you populate a download's `path`).
- `document_ids` are identifiers for files your application has staged for the browser, for deployments where it can't. Your application defines what the identifiers mean; scope their resolution the way you scope `paths`, to files staged for this task.
```python
{
"type": "tool_use",
"id": "toolu_01N7gVzFEfZjLjgsYwnrPgrF",
"name": "file_upload",
"toolset_name": "browser",
"input": {
"target": { "type": "ref", "ref": "ref_12" },
"paths": ["/home/user/uploads/summary.pdf"],
"tab_id": "tab-2"
}
}
```
Claude writes these paths while it's reading untrusted pages, so an unrestricted implementation would let a malicious page direct the upload of any file the executor can read to a site the page controls. Enable the member only when your executor resolves each path (following symlinks and `..` segments) and accepts nothing outside a dedicated, allowlisted upload directory that holds only files meant for the task. Don't reuse the browser's download directory for this; if you do, every file a page causes the browser to download becomes uploadable.
### Run JavaScript in the page
`javascript_exec` runs the expression Claude writes in the page's context and returns the value of the last expression as text; Claude writes an expression, not a `return` statement. The code runs with the page's full privileges, including its cookies, storage, and same-origin requests. Enable the member only in sessions that hold no credentials, keep the domain allowlist from [Security considerations](#security-considerations) in force, treat the returned value as untrusted input, and log the code Claude emits.
### Read console and network activity
`read_console` returns the tab's console entries and `read_network` returns its network requests, each as text with one line per entry accumulated since the previous read of that tab. A console line carries a log, warning, or error entry; a network line carries the method, URL, status, MIME type, and timing. Entries exist only from the moment your browser automation attached to the tab, so an empty result doesn't mean a tab that was already open had no traffic.
These members let Claude diagnose a misbehaving page (a failed request behind a spinner, a script error behind a dead button) without repeated screenshots. Console and network entries are page-controlled and often contain secrets such as tokens in request URLs, so redact credential-like values you don't want in Claude's context and truncate very long entries before returning them.
## Track tabs with `browser_state`
Claude addresses tabs by `tab_id`, your application is the source of truth for which tabs exist, and you report that state in a `browser_state` content block that Claude never sees directly: the API renders the text Claude reads from it.
```python
{
"type": "browser_state",
"tabs": [
{
"tab_id": "tab-1",
"title": "Documentation",
"url": "https://example.com/docs",
"active": true
},
{ "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" }
]
}
```
- `tabs` is the full inventory of open tabs after the call, not a delta. It may be empty; whenever it isn't, exactly one entry carries `"active": true`.
- `state_changes` (not shown here) reports side effects of the call: a `tab_opened` entry for each tab the call opened that's still open when it finishes, whose `tab_id` must also appear in `tabs`, and [download events](#report-downloads). Omit the field when there's nothing to report; an empty array is rejected.
- Send the block only on results that answer a browser member call, at most once per `tool_result`, and never on a result with `is_error: true`. You express "no tab state to report" by omitting the block.
- The API renders `tabs`, and any download entries in `state_changes`, into text for Claude. The next two sections and [Report downloads](#report-downloads) show that text.
**You assign `tab_id` values.** Any stable string works, such as your automation library's page identifier or your own counter, as long as you don't reuse a `tab_id` while a tab with that identifier is still listed as open in an earlier result. The API enforces these limits on the block:
- Each `tab_id`, `title`, and `url` may be at most 4,096 characters, `tab_id` must be non-empty, and none may contain control characters (including newlines) or Unicode line or paragraph separators.
- A block may list at most 100 tabs and 200 state changes.
- The same limits apply to the `tab_id` Claude passes to `switch_tab` and `close_tab`, because the API renders it into the result text, so answer a call whose `tab_id` violates them with an error result instead of a `browser_state` block.
Tab titles and URLs come from the page and render into text Claude reads, so they're a prompt-injection surface. The API renders tab URLs verbatim, so sanitize page-supplied URLs before populating `tabs`. It escapes double quotes and backslashes in titles when it renders them, so don't pre-escape titles (a pre-escaped title reaches Claude double-escaped); truncating or dropping suspicious titles is still worthwhile. A download entry's `url`, `path`, and `error` also render into text Claude reads, so treat them as untrusted too; the API quotes and escapes them as it does titles. The length and character limits the API enforces are a floor, not a defense.
### Tab management results
For `new_tab`, `switch_tab`, `close_tab`, and `list_tabs`, a successful result's `content` is exactly one `browser_state` block with no text or image, and the API writes the text Claude sees. A `new_tab` result's block must also carry exactly one `tab_opened` state change whose `tab_id` matches the entry marked `active: true`.
| Member | Text Claude sees |
|:-------------|:----------------------------------------------------------------------------------------------------------------------------|
| `switch_tab` | `Switched to tab {tab_id}`, taken from the call's `input.tab_id` |
| `close_tab` | `Closed tab {tab_id}`, taken from the call's `input.tab_id` |
| `new_tab` | `Created new tab with tab_id: {tab_id}, URL: {url}. It is now the current tab.`, taken from the entry marked `active: true` |
| `list_tabs` | `Available tabs:` followed by one line per tab, or `No tabs available` when `tabs` is empty |
A `list_tabs` result whose block lists two tabs with the first one active renders as follows, with each line indented two spaces and ` (current)` appended to the active tab only:
``` block
Available tabs:
• tab_id tab-1: "Documentation" (https://example.com/docs) (current)
• tab_id tab-2: "Pricing" (https://example.com/pricing)
```
An error result for one of these members is the reverse: ordinary error text in `content`, `is_error: true`, and no `browser_state` block.
For example, when Claude calls `new_tab` (its `input` is empty), your executor opens the tab, makes it active, and returns the inventory with one `tab_opened` entry:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01WvHSbQVV9j5nWGvTmk4vNL",
"toolset_name": "browser",
"content": [
{
"type": "browser_state",
"tabs": [
{ "tab_id": "tab-1", "title": "Documentation", "url": "https://example.com/docs" },
{ "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" },
{ "tab_id": "tab-3", "title": "", "url": "about:blank", "active": true }
],
"state_changes": [{ "type": "tab_opened", "tab_id": "tab-3" }]
}
]
}
]
}
```
Claude sees `Created new tab with tab_id: tab-3, URL: about:blank. It is now the current tab.` Report the URL the tab was opened at, as here, not one it later redirects to; later results report the tab's then-current URL.
### Tab context on other results
On every other member the block is optional: send it when the set of open tabs, the active tab, or a tab's title or URL changed, or when there are `state_changes` to report, and always include the full `tabs` inventory. When a result carries both text and a `browser_state` block, the API appends a `Tab Context` footer to that result's text, separated from your text by a blank line, so Claude receives the new state without a separate `list_tabs` call:
```python
Tab Context:
- Executed on tab_id: tab-1
- Available tabs:
• tab_id tab-1: "Documentation" (https://example.com/docs)
• tab_id tab-2: "Pricing" (https://example.com/pricing)
```
`Executed on` names the tab the call ran on, which is its `tab_id` input when present and otherwise the active tab, and the footer's tab lines carry no `(current)` marker. Don't append this text yourself; send the structured block and let the API render it. The footer is deduplicated, so identical tab state isn't rendered again on later results and populating the block liberally costs nothing.
Three cases render no footer even when the block is present:
- Any `zoom` result.
- A result with no `text` block (an image-only `screenshot` result, for example). Nothing is rendered or remembered for that result; the tab context appears on the next result that carries both text and a `browser_state` block, so include a short text block alongside the image when you want Claude to see a tab change on that same result. The exception is a result whose block reports a [download event](#report-downloads). The API adds the download lines as a text block, and the footer follows them as it would on any result with text.
- A result whose `tabs` list is empty on a call that carried no `tab_id`, because there's no tab to name.
For example, when Claude clicked the "Pricing" link (`ref_5`) earlier in this session, the page opened it in a new tab Claude didn't ask for, and without a report Claude would have to call `list_tabs` to discover it. Return the click's acknowledgment plus a block whose `state_changes` names the opened tab, marking whichever tab your executor left active:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01EgTXj1FjE2FCTt2zNFWLao",
"toolset_name": "browser",
"content": [
{ "type": "text", "text": "Clicked element ref_5." },
{
"type": "browser_state",
"tabs": [
{
"tab_id": "tab-1",
"title": "Documentation",
"url": "https://example.com/docs",
"active": true
},
{ "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" }
],
"state_changes": [{ "type": "tab_opened", "tab_id": "tab-2" }]
}
]
}
]
}
```
Claude sees `Clicked element ref_5.` followed by the Tab Context footer shown earlier. A tab opened during a call that failed gets no `tab_opened` entry, because error results carry no `browser_state`; it appears in the `tabs` inventory of the next successful result instead. In a batch, attach the block to the result of the call during which the change happened, and give every successful tab-management result its own block even when an earlier result in the same turn reported the same state.
### Report downloads
When a click or navigation starts a file download, report it in `state_changes` on the result of the call during which it happened, correlated across results by a `download_id` you assign. Downloads run asynchronously and can span several results, so there are three event types:
| `type` | Fields | When to send |
|:---------------------|:---------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `download_started` | `download_id`, `url` | On the result of the call during which the download began. `url` is the final URL the file is served from, after redirects. |
| `download_completed` | `download_id`, `url`, `path?`, `size_bytes?` | On the result of whichever later call is running when the download finishes. Include `path` only when another tool in the same environment (for example, the [bash tool](agents-and-tools-tool-use-bash-tool.md) or `file_upload`) can read the file there; otherwise `download_id` is the download's only identifier. |
| `download_failed` | `download_id`, `url`, `error?` | When the download fails or is canceled, with the reason in `error` if the browser provides one. |
The API renders each entry as one line of text for Claude, in the order the entries appear. It adds the lines after the result's text, separated by a blank line, and before any Tab Context footer. Every kind of member result carries the lines, including `zoom` and tab-management results. A result with no `text` block gets them as a text block of its own. Each line gives the `download_id` and `url`, plus `path` and `size_bytes` (for `download_completed`) or `error` (for `download_failed`) when you send them. You don't need to describe the download in your own text. The API wraps `url`, `path`, and `error` in double quotes and escapes double quotes and backslashes inside them, so don't pre-escape these values.
For example, a click on "Download price list (CSV)" (`ref_8`) in the Pricing tab starts a download, so the click's result carries a `download_started` entry with `download_id` `"dl-1"` and the file's URL. The download finishes while a later `screenshot` call is running, so that result's `content` holds the image, a text block such as `Screenshot captured.`, and this `browser_state` block reporting the completion under the same `download_id`:
```python
{
"type": "browser_state",
"tabs": [
{ "tab_id": "tab-1", "title": "Documentation", "url": "https://example.com/docs" },
{
"tab_id": "tab-2",
"title": "Pricing",
"url": "https://example.com/pricing",
"active": true
}
],
"state_changes": [
{
"type": "download_completed",
"download_id": "dl-1",
"url": "https://example.com/pricing/price-list.csv",
"path": "/home/user/downloads/price-list.csv",
"size_bytes": 48213
}
]
}
```
Claude sees `Screenshot captured.` followed by a blank line and a line like this:
```python
Download completed with download_id: dl-1, URL: "https://example.com/pricing/price-list.csv". Saved to "/home/user/downloads/price-list.csv". Size: 48213 bytes.
```
Download reports follow these rules:
- At most one entry per `download_id` in a single block, so a download that starts and finishes during the same call reports only `download_completed`.
- Never send `state_changes` on an `is_error: true` result; report a download event that occurred during a failed call on the next successful result.
- `state_changes` isn't an inventory of downloads in progress; report each event once.
- Each entry carries only the fields its `type` declares. `size_bytes` is a non-negative integer, `download_id` is non-empty, and `download_id`, `url`, `path`, and `error` are each at most 4,096 characters with no control characters or Unicode line or paragraph separators. The `url` comes from the remote server and often carries signed query-string credentials after redirects, so strip query parameters you don't want in Claude's context and sanitize it before reporting it or using it in a filesystem path.
## Handle errors
Report a failed call to Claude as an ordinary error result: `is_error: true`, text content that says what went wrong, `toolset_name` echoed, and no `browser_state` block.
### Return errors from your executor
Make error text specific, because Claude reads it and adapts: `Error: Navigation to https://example.com/status timed out after 30 seconds. The page may be unavailable.` gives Claude something to act on where a bare `Error: navigation failed` doesn't. Other common cases:
### Refused navigation scheme
```python
{
"type": "tool_result",
"tool_use_id": "toolu_01LeUTyqkhRxBFq1QTG3pkwN",
"toolset_name": "browser",
"is_error": true,
"content": "Error: Navigation refused. Only http and https URLs are allowed."
}
```
### Stale or unknown element reference
```python
{
"type": "tool_result",
"tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"toolset_name": "browser",
"is_error": true,
"content": "Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references."
}
```
### Disabled or unimplemented member
```python
{
"type": "tool_result",
"tool_use_id": "toolu_013h2Q55HcNwVyapSpy2s5ZG",
"toolset_name": "browser",
"is_error": true,
"content": "Error: javascript_exec is not enabled in this environment."
}
```
### Skipped after an earlier failure in the turn
When the `left_click` on `ref_3` from [Batch actions](#batch-actions) fails with the stale-reference error shown earlier, the `type` and `key` calls after it each get this result:
```python
{
"type": "tool_result",
"tool_use_id": "toolu_01FkP8rTz6uYh2mNq4LsXw7v",
"toolset_name": "browser",
"is_error": true,
"content": "Not executed: an earlier action in this turn failed."
}
```
### Request errors
The API validates the toolset entry and every member `tool_use` and `tool_result` block in the conversation. When one is malformed, the API returns an `invalid_request_error` before Claude runs. In the following table, the left column names what you sent.
| Request | Why it fails and what to do |
|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| An option or combination the toolset entry doesn't accept, for example, a `name`, `strict: true`, `input_examples`, `defer_loading` on the entry itself, a `configs` key that isn't a member name, a field other than `enabled` or `defer_loading` in a member's `configs` value ([Configure the toolset](#configure-the-toolset)), enabled members whose `defer_loading` values differ ([Configure the toolset](#configure-the-toolset)), a `configs` that leaves no member enabled, a code execution caller in `allowed_callers`, the legacy `fine-grained-tool-streaming-2025-05-14` beta header on the request, a `tool_choice` of type `tool` naming `browser` or a member, or a second browser toolset entry or another tool named `browser` | These aren't supported on client toolsets. See [Client toolsets](agents-and-tools-tool-use-tool-reference.md#client-toolsets) for each rule and its alternative. |
| A `tool_result` answering a member call without `"toolset_name": "browser"` or with a different value, or `toolset_name` on a result whose call wasn't a member call | Echo `toolset_name` exactly on member results, and only on them. |
| A member `tool_use` from an earlier turn with no matching `tool_result` | Answer every member call, including the ones you didn't run after a failure. |
| A content block other than `text`, `image`, or `browser_state` in a member result | Member results accept only those three block types. |
| A `browser_state` block that breaks a rule in [Track tabs with `browser_state`](#track-tabs-and-page-state), for example, one on an `is_error: true` result or on a result that doesn't answer a browser member call, more than one in a result, a non-empty `tabs` without exactly one `active: true` entry, a duplicate `tab_id`, an empty `state_changes` array, a `tab_opened` whose `tab_id` isn't in `tabs`, two state changes for one `download_id` or a state-change field its `type` doesn't declare ([Report downloads](#report-downloads)), or a field over its limits | Fix the block. "Nothing to report" is expressed by omitting the block or the `state_changes` field, never by an empty value. |
| A successful `new_tab`, `switch_tab`, `close_tab`, or `list_tabs` result whose `content` isn't exactly one `browser_state` block, or a `new_tab` result without exactly one `tab_opened` matching the active tab | The API renders these results from the block and needs it in that exact shape; see [Tab management results](#tab-management-results). |
| An `image` in a result over your model's [image size limits](../Guides/build-with-claude-vision.md#evaluate-image-size), or over the stricter per-image limit that applies once the request holds [more than 20 images](../Guides/build-with-claude-vision.md#request-limits), counting screenshots and `zoom` images in earlier results | The API doesn't downscale toolset images. Resize screenshots before returning them ([Size screenshots to fit image limits](agents-and-tools-tool-use-computer-use-tool.md#handle-coordinate-scaling-for-higher-resolutions)). |
| A `model` that doesn't support `browser_toolset_20260801` | See [Compatibility](#compatibility) for the supported models. |
## Limitations
- **Platform availability:** Browser use is available on the Claude API and [Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md).
- **Whole-input streaming only:** When you stream, each member's `input` arrives as one complete `input_json_delta` ([Client toolsets](agents-and-tools-tool-use-tool-reference.md#client-toolsets)).
- **Element references are best-effort:** Highly dynamic pages (virtualized lists, canvas-rendered interfaces, pages that re-render on scroll) might not expose stable references, and Claude falls back to screenshots and coordinate clicks there.
- **`read_console` and `read_network` depend on your browser automation:** They report only what it can capture, and only from the moment it attached to a tab.
- **General agent limitations apply:** Latency, vision accuracy, and prompt-injection risks carry over from computer use (see the computer use tool's [Limitations](agents-and-tools-tool-use-computer-use-tool.md#understand-computer-use-limitations)), and its guidance under [Optimize model performance with prompting](agents-and-tools-tool-use-computer-use-tool.md#optimize-model-performance-with-prompting), [Manage screenshot history](agents-and-tools-tool-use-computer-use-tool.md#manage-screenshot-history), and [Follow implementation best practices](agents-and-tools-tool-use-computer-use-tool.md#follow-implementation-best-practices) (action delays, action validation, and logging) applies to browser executors too.
## Pricing and data retention
Browser use follows the standard [tool use pricing](agents-and-tools-tool-use-overview.md#pricing). When using the browser use tool:
**Toolset definition overhead:** Declaring `browser_toolset_20260801` with its default members adds about 6,600 input tokens to a request (about 6,670 on Claude Sonnet 5 and about 6,610 on the other supported models), which covers the member tool definitions and the tool use system prompt. Enabling all four optional members adds about 880 tokens, and disabling members with `configs` reduces the count. The exact count for a request is reported in the response `usage`, and you can estimate it in advance with the [token counting endpoint](../Guides/build-with-claude-token-counting.md).
**Additional token consumption:**
- Screenshot and zoom images returned in tool results, billed as image input (see [Vision pricing](../Guides/build-with-claude-vision.md#evaluate-image-size))
- Text tool results returned to Claude, such as accessibility trees, page text, and console or network entries
If you also use the computer use tool, bash tool, text editor tool, or your own tools alongside browser use, those tools have their own token costs as documented on their respective pages.
The browser session, downloads, and uploaded files stay in your environment; the screenshots, page text, and tab state you return are part of your API request content and follow the standard retention policy, or your ZDR arrangement if you have one. The browser use tool is ZDR eligible; see [API and data retention](../Other/manage-claude-api-and-data-retention.md) for retention periods and eligibility across features.
## Next steps
[Browser and computer use with the SDK toolsets](agents-and-tools-tool-use-browser-use-sdk.md)
Start from a partner's driver, or write your own in Python or TypeScript. The SDK runs the loop and the checks you configure.
[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)
Give Claude control of a full desktop when the task leaves the browser; its implementation guidance applies to browser executors too.
[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)
Format `tool_result` blocks, return images and errors, and continue the conversation.
[Tool reference](agents-and-tools-tool-use-tool-reference.md)
Browse client toolsets and every other Anthropic-provided tool, with their versions and parameters.
## Compatibility
Supported models
- Fable 5 and 5.1
- Mythos 5 and 5.1
- Opus 4.8, 5, and 5.5
- Sonnet 5 and 5.5
- Haiku 5.5
Supported platforms
- Claude API
- Google Cloud
---
## Tutorial: Build a tool-using agent - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/build-a-tool-using-agent
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-build-a-tool-using-agent.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fbuild-a-tool-using-agent)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Tutorial: Build a tool-using agent
Copy page
A guided walkthrough from a single tool call to a production-ready agentic loop.
Copy page
This tutorial builds a calendar-management agent in five concentric rings. Each ring is a complete, runnable program that adds exactly one concept to the ring before it. By the end you will have written the agentic loop by hand and then replaced it with the Tool Runner SDK abstraction.
The example tool is `create_calendar_event`. Its schema uses nested objects, arrays, and optional fields, so you will see how Claude handles realistic input shapes rather than a single flat string.
Every ring runs standalone. Copy any ring into a fresh file and it will run without the code from earlier rings.
## Ring 1: Single tool, single turn
The smallest possible tool-using program: one tool, one user message, one tool call, one result. The code is heavily commented so you can map each line to the [tool use lifecycle](agents-and-tools-tool-use-how-tool-use-works.md).
The request sends a `tools` array alongside the user message. When Claude determines that a tool call is needed, the response comes back with `stop_reason: "tool_use"` and a `tool_use` content block containing the tool name, a unique `id`, and the structured `input`. Your code runs the tool, then sends the result back in a `tool_result` block whose `tool_use_id` matches the `id` from the call.
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
# Ring 1: Single tool, single turn.
import json
import anthropic
# Create a client. It reads ANTHROPIC_API_KEY from the environment.
client = anthropic.Anthropic()
# Define one tool. The input_schema is a JSON Schema object describing
# the arguments Claude should pass when it calls this tool. This schema
# includes nested objects (recurrence), arrays (attendees), and optional
# fields, which is closer to real-world tools than a flat string argument.
tools = [
{
"name": "create_calendar_event",
"description": "Create a calendar event with attendees and optional recurrence.",
"input_schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"start": {"type": "string", "format": "date-time"},
"end": {"type": "string", "format": "date-time"},
"attendees": {
"type": "array",
"items": {"type": "string", "format": "email"},
},
"recurrence": {
"type": "object",
"properties": {
"frequency": {"enum": ["daily", "weekly", "monthly"]},
"count": {"type": "integer", "minimum": 1},
},
},
},
"required": ["title", "start", "end"],
},
}
]
# Send the user's request along with the tool definition. Claude decides
# whether to call the tool based on the request and the tool description.
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=[
{
"role": "user",
"content": "Schedule a 30-minute sync with alice@example.com and bob@example.com on Monday, March 30, 2026 at 10am.",
}
],
)
# When Claude calls a tool, the response has stop_reason "tool_use"
# and the content array contains a tool_use block alongside any text.
print(f"stop_reason: {response.stop_reason}")
# Find the tool_use block. A response may contain text blocks before the
# tool_use block, so scan the content array rather than assuming position.
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Tool: {tool_use.name}")
print(f"Input: {tool_use.input}")
# Execute the tool. In a real system this would call your calendar API.
# Here the result is hardcoded to keep the example self-contained.
result = {"event_id": "evt_123", "status": "created"}
# Send the result back. The tool_result block goes in a user message and
# its tool_use_id must match the id from the tool_use block above. The
# assistant's previous response is included so Claude has the full history.
followup = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=[
{
"role": "user",
"content": "Schedule a 30-minute sync with alice@example.com and bob@example.com on Monday, March 30, 2026 at 10am.",
},
{"role": "assistant", "content": response.content},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": tool_use.id,
"content": json.dumps(result),
}
],
},
],
)
# With the tool result in hand, Claude produces a final natural-language
# answer and stop_reason becomes "end_turn".
print(f"stop_reason: {followup.stop_reason}")
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)
```
**What to expect**
Output
```python
stop_reason: tool_use
Tool: create_calendar_event
Input: {'title': 'Sync', 'start': '2026-03-30T10:00:00', 'end': '2026-03-30T10:30:00', 'attendees': ['alice@example.com', 'bob@example.com']}
stop_reason: end_turn
I've scheduled your 30-minute sync with Alice and Bob for Monday, March 30 at 10am.
```
The first `stop_reason` is `tool_use` because Claude is waiting for the calendar result. After you send the result, the second `stop_reason` is `end_turn` and the content is natural language for the user.
## Ring 2: The agentic loop
Ring 1 assumed Claude would call the tool exactly once. Real tasks often need several calls: Claude might create an event, read the confirmation, then create another. The fix is a `while` loop that keeps running tools and feeding results back until `stop_reason` is no longer `"tool_use"`.
The other change is conversation history. Instead of rebuilding the `messages` array from scratch on each request, keep a running list and append to it. Every turn sees the complete prior context.
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
# Ring 2: The agentic loop.
import json
import anthropic
client = anthropic.Anthropic()
tools = [
{
"name": "create_calendar_event",
"description": "Create a calendar event with attendees and optional recurrence.",
"input_schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"start": {"type": "string", "format": "date-time"},
"end": {"type": "string", "format": "date-time"},
"attendees": {
"type": "array",
"items": {"type": "string", "format": "email"},
},
"recurrence": {
"type": "object",
"properties": {
"frequency": {"enum": ["daily", "weekly", "monthly"]},
"count": {"type": "integer", "minimum": 1},
},
},
},
"required": ["title", "start", "end"],
},
}
]
def run_tool(name, tool_input):
if name == "create_calendar_event":
return {
"event_id": "evt_123",
"status": "created",
"title": tool_input["title"],
}
return {"error": f"Unknown tool: {name}"}
# Keep the full conversation history in a list so each turn sees prior context.
messages = [
{
"role": "user",
"content": "Schedule a weekly team standup every Monday at 9am for the next 4 weeks, starting Monday, March 30, 2026. Invite the whole team: alice@example.com, bob@example.com, carol@example.com.",
}
]
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=messages,
)
# Loop until Claude stops asking for tools. Each iteration runs the requested
# tool, appends the result to history, and asks Claude to continue.
while response.stop_reason == "tool_use":
tool_use = next(block for block in response.content if block.type == "tool_use")
result = run_tool(tool_use.name, tool_use.input)
messages.append({"role": "assistant", "content": response.content})
messages.append(
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": tool_use.id,
"content": json.dumps(result),
}
],
}
)
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=messages,
)
final_text = next(block for block in response.content if block.type == "text")
print(final_text.text)
```
**What to expect**
Output
``` block
I've set up your weekly team standup for the next 4 Mondays at 9am with Alice, Bob, and Carol invited.
```
The loop might run once or several times depending on how Claude breaks down the task. Your code no longer needs to know in advance.
## Ring 3: Multiple tools, parallel calls
Agents rarely have just one capability. Add a second tool, `list_calendar_events`, so Claude can check the existing schedule before creating something new.
When Claude has multiple independent tool calls to make, it might return several `tool_use` blocks in a single response. Your loop needs to process all of them and send back all results together in one user message. Iterate over every `tool_use` block in `response.content`, not just the first.
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
# Ring 3: Multiple tools, parallel calls.
import json
import anthropic
client = anthropic.Anthropic()
tools = [
{
"name": "create_calendar_event",
"description": "Create a calendar event with attendees and optional recurrence.",
"input_schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"start": {"type": "string", "format": "date-time"},
"end": {"type": "string", "format": "date-time"},
"attendees": {
"type": "array",
"items": {"type": "string", "format": "email"},
},
"recurrence": {
"type": "object",
"properties": {
"frequency": {"enum": ["daily", "weekly", "monthly"]},
"count": {"type": "integer", "minimum": 1},
},
},
},
"required": ["title", "start", "end"],
},
},
{
"name": "list_calendar_events",
"description": "List all calendar events on a given date.",
"input_schema": {
"type": "object",
"properties": {
"date": {"type": "string", "format": "date"},
},
"required": ["date"],
},
},
]
def run_tool(name, tool_input):
if name == "create_calendar_event":
return {
"event_id": "evt_123",
"status": "created",
"title": tool_input["title"],
}
if name == "list_calendar_events":
return {
"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]
}
return {"error": f"Unknown tool: {name}"}
messages = [
{
"role": "user",
"content": "Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts.",
}
]
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
messages=messages,
)
while response.stop_reason == "tool_use":
# A single response can contain multiple tool_use blocks. Process all of
# them and return all results together in one user message.
tool_results = []
for block in response.content:
if block.type == "tool_use":
result = run_tool(block.name, block.input)
tool_results.append(
{
"type": "tool_result",
"tool_use_id": block.id,
"content": json.dumps(result),
}
)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
messages=messages,
)
final_text = next(block for block in response.content if block.type == "text")
print(final_text.text)
```
**What to expect**
Output
``` block
I checked your calendar for Monday, March 30 and found an existing meeting from 2pm to 3pm. I've scheduled the planning session for 10am to 11am to avoid the conflict.
```
For more on concurrent execution and ordering guarantees, see [Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md).
## Ring 4: Error handling
Tools fail. A calendar API might reject an event with too many attendees, or a date might be malformed. When a tool raises an error, send the error message back with `is_error: true` instead of crashing. Claude reads the error and can retry with corrected input, ask the user for clarification, or explain the limitation.
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
# Ring 4: Error handling.
import json
import anthropic
client = anthropic.Anthropic()
tools = [
{
"name": "create_calendar_event",
"description": "Create a calendar event with attendees and optional recurrence.",
"input_schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"start": {"type": "string", "format": "date-time"},
"end": {"type": "string", "format": "date-time"},
"attendees": {
"type": "array",
"items": {"type": "string", "format": "email"},
},
"recurrence": {
"type": "object",
"properties": {
"frequency": {"enum": ["daily", "weekly", "monthly"]},
"count": {"type": "integer", "minimum": 1},
},
},
},
"required": ["title", "start", "end"],
},
},
{
"name": "list_calendar_events",
"description": "List all calendar events on a given date.",
"input_schema": {
"type": "object",
"properties": {
"date": {"type": "string", "format": "date"},
},
"required": ["date"],
},
},
]
def run_tool(name, tool_input):
if name == "create_calendar_event":
if "attendees" in tool_input and len(tool_input["attendees"]) > 10:
raise ValueError("Too many attendees (max 10)")
return {
"event_id": "evt_123",
"status": "created",
"title": tool_input["title"],
}
if name == "list_calendar_events":
return {
"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]
}
raise ValueError(f"Unknown tool: {name}")
messages = [
{
"role": "user",
"content": "Schedule a one-hour all-hands on Monday, March 30, 2026 at 10am with everyone: "
+ ", ".join(f"user{i}@example.com" for i in range(15)),
}
]
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
messages=messages,
)
while response.stop_reason == "tool_use":
tool_results = []
for block in response.content:
if block.type == "tool_use":
try:
result = run_tool(block.name, block.input)
tool_results.append(
{
"type": "tool_result",
"tool_use_id": block.id,
"content": json.dumps(result),
}
)
except Exception as exc:
# Signal failure so Claude can retry or ask for clarification.
tool_results.append(
{
"type": "tool_result",
"tool_use_id": block.id,
"content": str(exc),
"is_error": True,
}
)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
messages=messages,
)
final_text = next(block for block in response.content if block.type == "text")
print(final_text.text)
```
**What to expect**
Output
```python
I tried to schedule the all-hands but the calendar only allows 10 attendees per event. I can split this into two sessions, or you can let me know which 10 people to prioritize.
```
The `is_error` flag is the only difference from a successful result. Claude sees the flag and the error text, and responds accordingly. See [Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md) for the full error-handling reference.
## Ring 5: The Tool Runner SDK abstraction
Rings 2 through 4 wrote the same loop by hand: call the API, check `stop_reason`, run tools, append results, repeat. The Tool Runner does this for you. Define each tool as a function, pass the list to `client.beta.messages.tool_runner()`, and retrieve the final message once the loop completes. Error wrapping, result formatting, and conversation management are handled internally.
Each SDK provides a helper that turns an ordinary function into a runnable tool and derives the input schema from its signature; the following tabs show the idiomatic form for each language.
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
# Ring 5: The Tool Runner SDK abstraction.
import json
import anthropic
from anthropic import beta_tool
client = anthropic.Anthropic()
@beta_tool
def create_calendar_event(
title: str,
start: str,
end: str,
attendees: list[str] | None = None,
recurrence: dict | None = None,
) -> str:
"""Create a calendar event with attendees and optional recurrence.
Args:
title: Event title.
start: Start time in ISO 8601 format.
end: End time in ISO 8601 format.
attendees: Email addresses to invite.
recurrence: Dict with 'frequency' (daily, weekly, monthly) and 'count'.
"""
if attendees and len(attendees) > 10:
raise ValueError("Too many attendees (max 10)")
return json.dumps({"event_id": "evt_123", "status": "created", "title": title})
@beta_tool
def list_calendar_events(date: str) -> str:
"""List all calendar events on a given date.
Args:
date: Date in YYYY-MM-DD format.
"""
return json.dumps(
{"events": [{"title": "Existing meeting", "start": "14:00", "end": "15:00"}]}
)
final_message = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
tools=[create_calendar_event, list_calendar_events],
messages=[
{
"role": "user",
"content": "Check what I have on Monday, March 30, 2026, then schedule a one-hour planning session that day that avoids any conflicts.",
}
],
).until_done()
for block in final_message.content:
if block.type == "text":
print(block.text)
```
**What to expect**
Output
``` block
I checked your calendar for Monday, March 30 and found an existing meeting from 2pm to 3pm. I've scheduled the planning session for 10am to 11am to avoid the conflict.
```
The output is identical to Ring 3. The difference is in the code: roughly half the lines, no manual loop, and the schema lives next to the implementation.
## What you built
You started with a single hardcoded tool call and ended with a production-shaped agent that handles multiple tools, parallel calls, and errors, then collapsed all of that into the Tool Runner. Along the way you saw every piece of the tool-use protocol: `tool_use` blocks, `tool_result` blocks, `tool_use_id` matching, `stop_reason` checking, and `is_error` signaling.
## Next steps
[Define tools](agents-and-tools-tool-use-implement-tool-use.md)
Schema specification and best practices.
[Tool Runner](agents-and-tools-tool-use-tool-runner.md)
The full SDK abstraction reference.
[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Fix common tool-use errors.
---
## Code execution tool - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-code-execution-tool.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fcode-execution-tool)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
Code execution tool
[ZDR](../Other/manage-claude-api-and-data-retention.md)
Not eligible
# Code execution tool
Copy page
Run Python and bash code in a sandboxed container to analyze data, generate files, and iterate on solutions.
Copy page
Claude can analyze data, create visualizations, perform complex calculations, run system commands, create and edit files, and process uploaded files directly within the API conversation. The code execution tool allows Claude to run Bash commands and manipulate files, including writing code, in a secure, sandboxed environment.
**Code execution is free when used with web search or web fetch (`web_search_20260209`, `web_fetch_20260209`, or later).** When one of those tools is in your request, there are no additional charges for code execution in that request beyond standard token costs. This covers both the code execution behind dynamic filtering and any code Claude runs directly. Standard code execution pricing applies when they are not included.
Code execution also powers dynamic filtering in the [web search](agents-and-tools-tool-use-web-search-tool.md) and [web fetch](agents-and-tools-tool-use-web-fetch-tool.md) tools: Claude filters results inside the code execution environment before they reach the context window. When dynamic filtering runs, the API provisions the code execution it needs for the request automatically, so you don't add the code execution tool to your request for it.
Reach out through the [feedback form](https://forms.gle/LTAU6Xn2puCJMi1n6) to share your feedback on this feature.
## Tool versions
The code execution tool has three current versions, and every [supported model](#compatibility) accepts all three. Each version builds on the previous one:
- `code_execution_20250825` supports Bash commands and file operations.
- `code_execution_20260120` adds REPL state persistence and [programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md) from within the sandbox. Claude Haiku 4.5 accepts the `code_execution_20260120` and `code_execution_20260521` tool types, but programmatic tool calling and the REPL state persistence that depends on it aren't available on it, so the newer versions behave like `code_execution_20250825` there.
- `code_execution_20260521` is the same runtime as `code_execution_20260120`. The difference is that the tool description tells Claude about the 90-second wall-clock limit on each Python cell in programmatic tool calling, so Claude can budget long-running cells. A cell that exceeds the limit returns a normal code execution result with a non-zero `return_code` and a `detection_timeout` status message in its output. This is separate from the `execution_time_exceeded` [error code](#errors), which the API returns when a whole tool invocation exceeds the maximum execution time.
None of the three tool versions requires an `anthropic-beta` header. The legacy code execution beta headers remain valid opt-ins.
The examples on this page use `code_execution_20250825`, which covers the Bash and file operations they demonstrate and behaves the same way on every supported model; use `code_execution_20260120` or later when you need programmatic tool calling or REPL state persistence. The current [web search](agents-and-tools-tool-use-web-search-tool.md) and [web fetch](agents-and-tools-tool-use-web-fetch-tool.md) tools (`web_search_20260209`, `web_fetch_20260209`, and later) require `code_execution_20260120` or later as their code execution version.
Older tool versions aren't guaranteed to stay compatible with newer models. When you adopt a new model, check [Tool versions](#tool-versions) and [Compatibility](#compatibility), and prefer the newest tool version your integration supports.
To check whether a model accepts the code execution tool before you send a request, read its `capabilities.server_tools.code_execution.supported` value from the Models API. Don't use the top-level `capabilities.code_execution` value for this. It reports whether code running in this tool can call your request's other tools, as in programmatic tool calling. [Using the Models API](../../20-Models/about-claude-models-overview.md#using-the-models-api) describes both fields.
If you're still using the legacy `code_execution_20250522` (Python only), see [Upgrade to latest tool version](#upgrade-to-latest-tool-version) to migrate from it.
## Quick start
Here's an example that asks Claude to perform a calculation:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Use the code execution tool to calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response.to_json())
```
The response interleaves `server_tool_use` blocks (the commands Claude ran) with their tool result blocks, followed by Claude's text. The top level also includes a `container` object whose `id` you can [reuse across requests](#container-reuse). See [Response format](#response-format) for the block shapes.
## How code execution works
When you add the code execution tool to your API request:
1. Claude evaluates whether code execution would help answer your question
2. The tool automatically provides Claude with the following capabilities:
- **Bash commands:** Run shell commands for system operations
- **File operations:** Create, view, and edit files directly, including writing code
3. Claude can use any combination of these capabilities in a single request
4. All operations run in a secure, sandboxed container. The container has no internet access, so Claude can't download packages at runtime: only the [pre-installed libraries](#pre-installed-libraries) are available
5. The API runs every command server-side and returns the results to Claude within the same request, so you never execute code or send back `tool_result` blocks yourself. One exception is when Claude calls one of your client tools alongside code execution: the API returns the code execution call without its result. The result arrives in a later response, after you send back the `tool_result` blocks for your client tools
6. Each request runs in a new container unless you pass an earlier response's container ID back (see [Container reuse](#container-reuse))
7. Claude provides results with any generated charts, calculations, or analysis
The container has Python pre-installed. Claude writes Python with the file operations sub-tool and runs it with a Bash command. With `code_execution_20260120` or later and [programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md), the Python interpreter state (such as variable bindings) also persists across requests that reuse the container.
### When Claude runs code
Claude runs code when the request benefits from computation or file handling:
- Non-trivial math (large numbers, many steps, precision-sensitive results)
- Data analysis, file parsing, or visualization
- Algorithm execution or simulation
- Explicit requests to "run", "compute", or "execute"
Claude answers directly without running code for:
- Simple arithmetic and well-known math facts
- Factual, conversational, or creative requests
- Simple unit conversions or translations
If you want Claude to run code for a borderline request, ask explicitly (for example, "run code to verify this").
## Work with files
### Upload and analyze your own files
To analyze your own data files (such as CSV, Excel, or images), upload them through the Files API and reference them in your request.
The Python environment can process various file types uploaded through the Files API, including:
- CSV
- Excel (.xlsx, .xls)
- JSON
- XML
- Images (JPEG, PNG, GIF, WebP)
- Text files (.txt, .md, .py, and others)
#### Upload and analyze files
1. **Upload your file** using the [Files API](../Guides/build-with-claude-files.md)
2. **Reference the file** in your message using a `container_upload` content block
3. **Include the code execution tool** in your API request
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
# Upload a file
file_object = client.files.upload(file=Path("data.csv"))
# Use the file_id with code execution
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Analyze this CSV data"},
{"type": "container_upload", "file_id": file_object.id},
],
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response.to_json())
```
### Retrieve generated files
When Claude saves files to its output directory during code execution (see [How generated files are captured](#how-generated-files-are-captured)), each file's ID appears in the code execution tool result, and you can download it with the [Files API](../Guides/build-with-claude-files.md):
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = Anthropic()
# Request code execution that creates files
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Create a matplotlib visualization and save it as output.png",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Extract file IDs from the response
def extract_file_ids(response: Message) -> list[str]:
file_ids: list[str] = []
for item in response.content:
if item.type == "bash_code_execution_tool_result":
content_item = item.content
if content_item.type == "bash_code_execution_result":
for output_block in content_item.content:
file_ids.append(output_block.file_id)
return file_ids
# Download the created files
for file_id in extract_file_ids(response):
file_metadata = client.files.retrieve_metadata(file_id)
file_content = client.files.download(file_id)
file_content.write_to_file(file_metadata.filename)
print(f"Downloaded: {file_metadata.filename}")
```
#### How generated files are captured
Each `bash_code_execution` call gets a new, empty directory, available to the command as `$OUTPUT_DIR`. When the command finishes, the files at the top level of that directory are captured and returned as the `file_id` entries in the result's `content` list. Files written anywhere else stay in the container and aren't returned.
The tool description tells Claude to share files by copying them into `$OUTPUT_DIR`. If your application depends on receiving a file, prompt Claude to copy it into `$OUTPUT_DIR` and list the directory in the same command, so the `ls` output confirms the capture (Claude doesn't see the `content` list):
```python
python /tmp/make_report.py && cp /tmp/report.pdf "$OUTPUT_DIR/" && ls "$OUTPUT_DIR"
```
A file Claude wrote elsewhere is still in the container, so you can [reuse the container](#container-reuse) and ask Claude to copy it into `$OUTPUT_DIR`.
### Content Credentials on generated files
On the Claude API, supported image, video, and audio files that Claude produces in the code execution sandbox carry [C2PA](https://c2pa.org/) Content Credentials when you download them through the [Files API](../Guides/build-with-claude-files.md). [Supported formats](https://opensource.contentauthenticity.org/docs/sdk-repos/c2pa-python/docs/supported-formats/) include PNG, JPEG, GIF, WebP, TIFF, HEIC, AVIF, SVG, MP4, MOV, MP3, WAV, FLAC, and M4A. The credential is a cryptographically signed manifest embedded in the file's metadata. It identifies Anthropic as the issuer, carries a timestamp, and records the action description "Claude provided this file at the request of a user and may have created or modified the file contents."
Signing requires no changes to your requests or response handling, and the manifest records nothing about you, your organization, or your request. The file's visible content is unchanged. The manifest adds a few kilobytes, so the downloaded file's size and checksum differ from the file as it exists inside the container. Text files, PDFs, and office documents are not signed because they are not supported formats for signing. Files you upload are stored as-is, including any Content Credentials they already carry.
To verify a credential, inspect the file with any C2PA-compatible tool, such as the open-source [c2patool command-line utility](https://github.com/contentauth/c2pa-rs). Re-encoding, format conversion, screenshots, and tools that strip metadata remove the credential, so a missing credential doesn't mean a file wasn't produced with Claude. For more on why a credential can be missing, see [How Claude marks AI-generated content](../../15-Claude-AI-Features/how-claude-marks-ai-generated-content.md).
## Tool definition
The code execution tool requires no additional parameters:
JSON
```python
{
"type": "code_execution_20250825",
"name": "code_execution"
}
```
Both fields are fixed: `type` selects the tool version, and `name` must be `code_execution`.
When you provide this tool, Claude automatically gains access to two sub-tools:
- `bash_code_execution`: Run shell commands
- `text_editor_code_execution`: View, create, and edit files, including writing code
When Claude runs code, the response also includes a top-level `container` object with the container's `id` and `expires_at` timestamp. Pass that ID back in the top-level `container` request parameter to keep using the same container. See [Container reuse](#container-reuse).
## Response format
The code execution tool can return two types of results depending on the operation:
### Bash command response
Output
```python
{
"type": "server_tool_use",
"id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
"name": "bash_code_execution",
"input": {
"command": "ls -la | head -5"
}
},
{
"type": "bash_code_execution_tool_result",
"tool_use_id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
"content": {
"type": "bash_code_execution_result",
"stdout": "total 24\ndrwxr-xr-x 2 user user 4096 Jan 1 12:00 .\ndrwxr-xr-x 3 user user 4096 Jan 1 11:00 ..\n-rw-r--r-- 1 user user 220 Jan 1 12:00 data.csv\n-rw-r--r-- 1 user user 180 Jan 1 12:00 config.json",
"stderr": "",
"return_code": 0,
"content": []
}
}
```
### File operation responses
**View file:**
Output
```python
{
"type": "server_tool_use",
"id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
"name": "text_editor_code_execution",
"input": {
"command": "view",
"path": "config.json"
}
},
{
"type": "text_editor_code_execution_tool_result",
"tool_use_id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
"content": {
"type": "text_editor_code_execution_view_result",
"file_type": "text",
"content": "{\n \"setting\": \"value\",\n \"debug\": true\n}",
"num_lines": 4,
"start_line": 1,
"total_lines": 4
}
}
```
**Create file:**
Output
```python
{
"type": "server_tool_use",
"id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
"name": "text_editor_code_execution",
"input": {
"command": "create",
"path": "new_file.txt",
"file_text": "Hello, World!"
}
},
{
"type": "text_editor_code_execution_tool_result",
"tool_use_id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
"content": {
"type": "text_editor_code_execution_create_result",
"is_file_update": false
}
}
```
**Edit file (str_replace):**
Output
```python
{
"type": "server_tool_use",
"id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
"name": "text_editor_code_execution",
"input": {
"command": "str_replace",
"path": "config.json",
"old_str": "\"debug\": true",
"new_str": "\"debug\": false"
}
},
{
"type": "text_editor_code_execution_tool_result",
"tool_use_id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
"content": {
"type": "text_editor_code_execution_str_replace_result",
"old_start": 3,
"old_lines": 1,
"new_start": 3,
"new_lines": 1,
"lines": ["- \"debug\": true", "+ \"debug\": false"]
}
}
```
### Results
Bash command results (`bash_code_execution_result`) include:
- `stdout`: Output from successful execution
- `stderr`: Error messages if execution fails
- `return_code`: 0 for success, non-zero for failure
- `content`: A list with an entry for each file the command left in `$OUTPUT_DIR` (see [How generated files are captured](#how-generated-files-are-captured)). Each entry carries the `file_id` to [retrieve the file](#retrieve-generated-files) with the Files API
File operation results have their own fields:
- **View** (`text_editor_code_execution_view_result`): `file_type`, `content`, `num_lines`, `start_line`, `total_lines`
- **Create** (`text_editor_code_execution_create_result`): `is_file_update` (whether the file already existed)
- **Edit** (`text_editor_code_execution_str_replace_result`): `old_start`, `old_lines`, `new_start`, `new_lines`, `lines` (diff format)
### Errors
Each tool type can return specific errors:
**Common errors (all tools):**
Output
```python
{
"type": "bash_code_execution_tool_result",
"tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
"content": {
"type": "bash_code_execution_tool_result_error",
"error_code": "unavailable"
}
}
```
**Error codes by tool type:**
| Tool | Error code | Description |
|-------------|---------------------------|---------------------------------------------------------|
| All tools | `unavailable` | The tool is temporarily unavailable |
| All tools | `execution_time_exceeded` | The tool invocation exceeded the maximum execution time |
| All tools | `invalid_tool_input` | Invalid parameters provided to the tool |
| All tools | `too_many_requests` | Rate limit exceeded for tool usage |
| bash | `output_file_too_large` | Command output exceeded the maximum size |
| text_editor | `file_not_found` | File doesn't exist (for view/edit operations) |
An expired container can't be reused: requests that reference it return an error instead of restoring it. Send the request again without the `container` parameter to get a new container.
### `pause_turn` stop reason
The response might include a `pause_turn` stop reason, which indicates that the API paused a long-running turn. You may provide the response back as-is in a subsequent request to let Claude continue its turn, or modify the content if you want to interrupt the conversation.
## Containers
The code execution tool runs in a secure, containerized environment designed specifically for code execution, with a higher focus on Python.
### Runtime environment
- **Python version:** 3.11
- **Operating system:** Linux-based container
- **Architecture:** x86_64 (AMD64)
### Resource limits
- **Memory:** 5 GiB RAM
- **Disk space:** 5 GiB workspace storage
- **CPU:** 1 CPU
- **Execution time:** A tool invocation that runs past the maximum execution time returns an `execution_time_exceeded` [error](#errors). With [programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md), each REPL cell also has a 90-second wall-clock limit
### Networking and security
- **Internet access:** Completely disabled for security
- **External connections:** No outbound network requests permitted
- **Sandbox isolation:** Full isolation from host system and other containers
- **File access:** Limited to workspace directory only
- **Workspace scoping:** Like the [Files API](../Guides/build-with-claude-files.md), containers are scoped to the request's workspace
- **Expiration:** Containers expire 30 days after creation
### Pre-installed libraries
The sandboxed Python environment includes these commonly used libraries:
- **Data science:** pandas, numpy, scipy, scikit-learn, statsmodels
- **Visualization:** matplotlib, seaborn
- **File processing:** pyarrow, openpyxl, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab\[pycairo\], Img2pdf
- **Math and computing:** sympy, mpmath
- **Utilities:** tqdm, python-dateutil, pytz, joblib
The container also includes command-line tools such as unzip, unrar, 7zip, bc, rg (ripgrep), fd, and sqlite.
The container has no internet access, so Claude can't download or install additional packages at runtime: only the pre-installed libraries are available.
## Container reuse
You can reuse an existing container across multiple API requests by providing the container ID from a previous response. This allows you to maintain created files between requests. With `code_execution_20260120` or later and [programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md), the Python interpreter state persists as well.
Containers expire 30 days after creation. After about 5 minutes of inactivity a container is checkpointed, and sending a request with its ID inside the 30-day window restores it. The `expires_at` timestamp in the response's `container` object is a shorter rolling value and doesn't report the 30-day limit. A container that has expired can't be reused. Send the request again without the `container` parameter to get a new container.
### Example
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
# First request: create a file with a random number in a new container
response1 = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Write a file with a random number and save it to '/tmp/number.txt'",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
# Second request: pass the container ID back so Claude reuses the same container
response2 = client.messages.create(
container=response1.container.id,
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Read the number from '/tmp/number.txt' and calculate its square",
}
],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response2.to_json())
```
## Using code execution with other execution tools
When you provide code execution alongside client-provided tools that also run code (such as a [Bash tool](agents-and-tools-tool-use-bash-tool.md) or custom REPL), Claude is operating in a multicomputer environment. The code execution tool runs in Anthropic's sandboxed container, while your client-provided tools run in a separate environment that you control. Claude can sometimes confuse these environments, attempting to use the wrong tool or assuming state is shared between them.
To avoid this, add instructions to your system prompt that clarify the distinction:
```python
When multiple code execution environments are available, be aware that:
- Variables, files, and state do NOT persist between different execution environments
- Use the code_execution tool for general-purpose computation in Anthropic's sandboxed environment
- Use client-provided execution tools (e.g., bash) when you need access to the user's local system, files, or data
- If you need to pass results between environments, explicitly include outputs in subsequent tool calls rather than assuming shared state
```
This is especially important when combining code execution with [web search](agents-and-tools-tool-use-web-search-tool.md) or [web fetch](agents-and-tools-tool-use-web-fetch-tool.md), which enable code execution automatically. If your application already provides a client-side shell tool, the automatic code execution creates a second execution environment that Claude needs to distinguish between.
When Claude calls one of your client tools alongside code execution, the API returns the code execution call without its result. The result arrives in a later response, after you send back the `tool_result` blocks for your client tools.
## Streaming
With [streaming](../Guides/build-with-claude-streaming.md) enabled (`"stream": true`), you'll receive code execution events as they occur. The sub-tool input streams as `input_json_delta` events, and each result block arrives whole in a single `content_block_start` event:
```python
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "bash_code_execution"}}
// Tool input streamed as partial JSON
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"command\": \"python analyze.py\"}"}}
// Pause while the command runs
// Execution result delivered as a complete block
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "bash_code_execution_result", "stdout": " A B C\n0 1 2 3\n1 4 5 6", "stderr": "", "return_code": 0, "content": []}}}
```
## Batch requests
You can include the code execution tool in the [Messages Batches API](../Guides/build-with-claude-batch-processing.md). Code execution tool calls through the Messages Batches API are priced the same as those in regular Messages API requests.
## Usage and pricing
**Code execution is free when used with web search or web fetch.** When `web_search_20260209` (or later) or `web_fetch_20260209` (or later) is included in your API request, there are no additional charges for code execution tool calls beyond the standard input and output token costs.
When used without these tools, code execution is billed by execution time, tracked separately from token usage:
- Execution time has a minimum of 5 minutes
- Each organization receives **1,550 free hours** of usage per month
- Additional usage beyond 1,550 hours is billed at **\$0.05 USD per hour, per container**
- If files are included in the request, execution time is billed even if the tool is not called, because files are preloaded onto the container
Code execution usage is tracked in the response:
```python
{
"usage": {
"input_tokens": 105,
"output_tokens": 239,
"server_tool_use": {
"code_execution_requests": 1
}
}
}
```
## Upgrade to latest tool version
The latest tool version is `code_execution_20260521`. To move between the three current versions, update the `type` string in your request: all three return the response blocks documented in [Response format](#response-format). See [Tool versions](#tool-versions) for what each version adds and [Compatibility](#compatibility) for the models that support them.
The rest of this section covers migrating from the legacy Python-only `code_execution_20250522` to the current tool versions.
### What's changed
| Component | Legacy | Current |
|----------------|-----------------------------|---------------------------------------------------------------------|
| Beta header | `code-execution-2025-05-22` | None required |
| Tool type | `code_execution_20250522` | `code_execution_20250825` or later |
| Capabilities | Python only | Bash commands, file operations |
| Response types | `code_execution_result` | `bash_code_execution_result`, `text_editor_code_execution_*_result` |
### Backward compatibility
- All existing Python code execution continues to work exactly as before
- No changes required to existing Python-only workflows
### Upgrade steps
To upgrade, update the tool type in your API requests:
```python
- "type": "code_execution_20250522"
+ "type": "code_execution_20250825"
```
**Review response handling** (if parsing responses programmatically):
- The API no longer sends the previous blocks for Python execution responses
- Instead, the API sends new response types for Bash and file operations (see [Response format](#response-format))
## Data retention
Code execution runs in server-side sandbox containers. Container data, including execution artifacts, uploaded files, and outputs, is retained for up to 30 days. This retention applies to all data processed within the container environment. Files that code execution creates in the [Files API](../Guides/build-with-claude-files.md) (retrievable with `client.files.download()`) persist until explicitly deleted.
For ZDR eligibility across all features, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
## Next steps
[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)
Pair a faster executor model with a higher-intelligence advisor model that provides strategic guidance mid-generation.
[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)
Call your own tools from code that runs inside the code execution container.
[Files API](../Guides/build-with-claude-files.md)
Upload files for analysis and download the files that code execution creates.
[Using Agent Skills with the API](../Guides/build-with-claude-skills-guide.md)
Learn how to use Agent Skills to extend Claude's capabilities through the API.
## Compatibility
Supported models
- Fable 5 and 5.1
- Mythos 5 and 5.1
- Opus 4.5, 4.6, 4.7, 4.8, 5, and 5.5
- Sonnet 4.5, 4.6, 5, and 5.5
- Haiku 4.5 and 5.5
Supported platforms
- Claude API
- Claude Platform on AWS
- Microsoft Foundry^([1](#compat-fn-1))
1. On [Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md), code execution requires a [Hosted on Anthropic deployment](../Guides/build-with-claude-claude-in-microsoft-foundry.md#additional-features-not-supported-when-hosted-on-azure). [↩](#compat-fnref-1)
- Every supported model accepts all three [tool versions](#tool-versions). On Claude Haiku 4.5, programmatic tool calling and REPL state persistence aren't available, so the newer versions behave like `code_execution_20250825` there.
- For [Claude Mythos Preview(opens in new tab)](../../22-Safety-Policy/glasswing.md), code execution is supported on the Claude API and Microsoft Foundry.
---
## Computer use tool - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-computer-use-tool.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fcomputer-use-tool)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
Computer use tool
[ZDR](../Other/manage-claude-api-and-data-retention.md)
Eligible
excludes [Covered Models](../Other/manage-claude-api-and-data-retention.md#model-specific-data-retention-requirements)
# Computer use tool
Copy page
Give Claude screenshot, mouse, and keyboard control of a desktop environment with the computer use tool, the computer_toolset_20260801 client toolset.
Copy page
**Start with the SDK toolsets:** For `computer_toolset_20260801`, the Python and TypeScript SDKs have a computer toolset class, in beta. Start from [a partner's integration](agents-and-tools-tool-use-browser-use-sdk.md#partner-integrations), or see the [computer toolset](agents-and-tools-tool-use-browser-use-sdk.md#computer-toolset) section of the SDK toolsets page. Use this page as the tool reference, or when you handle the tool calls yourself.
Claude can interact with computer environments through the computer use tool, which provides screenshot capabilities and mouse/keyboard control for autonomous desktop interaction.
The computer use tool is an Anthropic-defined [client toolset](agents-and-tools-tool-use-tool-reference.md#client-toolsets): one `{"type": "computer_toolset_20260801"}` entry in `tools` gives Claude 17 member tools such as `screenshot`, `left_click`, `type`, and `zoom`, and your application runs every call in an environment you control. It isn't currently available in [Claude Managed Agents](../Other/managed-agents-tools.md). Claude's calls are `tool_use` blocks whose `name` is the member and which carry `"toolset_name": "computer"`, often several per turn (a [batch action](#batch-actions)).
For tasks that stay inside webpages, the [browser use tool](agents-and-tools-tool-use-browser-use-tool.md) is the closer fit: its member tools read and act on the page itself, and it doesn't need a full desktop environment.
Computer use is available on the Claude API and [Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md) as the `computer_toolset_20260801` toolset; see [Compatibility](#compatibility) for the supported models.
Existing `computer_20251124` integrations keep working on the models listed for it under [Earlier tool versions](#earlier-tool-versions), and earlier tool versions remain available in beta for models and platforms that don't support the toolset. See [Migrate from `computer_20251124`](#migrate-from-computer-20251124) to upgrade, or [Earlier tool versions](#earlier-tool-versions) for the beta headers.
## Security considerations
Computer use has unique risks distinct from standard API features. These risks are heightened when interacting with the internet.
To minimize risks, consider taking precautions such as:
1. Using a dedicated virtual machine or container with minimal privileges to prevent direct system attacks or accidents.
2. Avoiding giving the model access to sensitive data, such as account login information, to prevent information theft.
3. Limiting internet access to an allowlist of domains to reduce exposure to malicious content.
4. Asking a human to confirm decisions that might result in meaningful real-world consequences and any tasks requiring affirmative consent, such as accepting cookies, completing financial transactions, or agreeing to terms of service.
In some circumstances, Claude will follow commands found in content even when they conflict with your instructions. For example, instructions on webpages or contained in images might override your instructions or cause Claude to make mistakes. Take precautions to isolate Claude from sensitive data and actions to avoid risks related to prompt injection.
Anthropic has trained the model to resist these prompt injections and has added an extra layer of defense. If you use the computer use tools, classifiers will automatically scan what the tools return, such as screenshots, to flag potential prompt injections. When these classifiers identify a potential prompt injection, they will automatically steer the model to check whether the instruction really came from you before acting on it.
This extra protection won't be ideal for every use case (for example, use cases without a human in the loop), so if you'd like to opt out and turn it off, [contact support](https://support.claude.com/en/). The precautions above remain important even with these classifiers in place.
Inform end users of relevant risks and obtain their consent prior to enabling computer use in your own products.
## Quick start
Add the computer use toolset to the `tools` array of a [Messages API](../Endpoints/messages-create.md) request as `{"type": "computer_toolset_20260801"}`. The request needs no beta header. This example also declares the [text editor tool](agents-and-tools-tool-use-text-editor-tool.md) and [bash tool](agents-and-tools-tool-use-bash-tool.md), which Claude typically uses alongside computer use:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[
{"type": "computer_toolset_20260801"},
{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"},
{"type": "bash_20250124", "name": "bash"},
],
messages=[{"role": "user", "content": "Save a picture of a cat to my desktop."}],
)
print(response)
```
When Claude acts on the desktop, the response has a `stop_reason` of `tool_use` and contains one or more member `tool_use` blocks, each naming a member tool and carrying `"toolset_name": "computer"`. Partway through this task, after Claude has seen a screenshot of the desktop, a response might look like this:
Output
```python
{
"id": "msg_01UZ3bXcQH8mTqNhVfL9eK2p",
"type": "message",
"role": "assistant",
"model": "claude-opus-5-5",
"content": [
{
"type": "text",
"text": "I'll open the web browser to find a picture of a cat."
},
{
"type": "tool_use",
"id": "toolu_01WkoTUvSHDzTBu2xnGk8Ep8",
"name": "left_click",
"toolset_name": "computer",
"input": { "coordinate": [512, 742] }
},
{
"type": "tool_use",
"id": "toolu_017nJn3RgSCkTMwuZDb4uUov",
"name": "screenshot",
"toolset_name": "computer",
"input": {}
}
],
"stop_reason": "tool_use",
"stop_sequence": null
}
```
Your application runs each call in order in your own environment, returns one `tool_result` block per `tool_use` block, and calls the API again; [How computer use works](#how-computer-use-works) describes that loop, and the rest of this page shows how to implement it.
------------------------------------------------------------------------
## How computer use works
1. 1
### Provide Claude with the computer use tool and a user prompt
- Add the computer use toolset (and optionally other tools) to the `tools` array of your API request.
- Include a user prompt that requires desktop interaction, for example, "Save a picture of a cat to my desktop."
2. 2
### Claude responds with member tool calls
- Claude assesses whether acting on the desktop can help with the user's query.
- If so, Claude responds with one or more member `tool_use` blocks, such as `screenshot`, `left_click`, or `type`, each carrying `"toolset_name": "computer"`. A response with several of these blocks is a [batch action](#batch-actions).
- The API response has a `stop_reason` of `tool_use`, signaling a tool use request.
3. 3
### Run the calls in order and return results
- Iterate over every `tool_use` block in the response, in order. For each one, dispatch on the member `name` together with `toolset_name`, and perform that action with the block's `input` on your container or virtual machine.
- Continue the conversation with a new `user` message that contains one `tool_result` block per `tool_use` block, matched by `tool_use_id` and each echoing `"toolset_name": "computer"`. Return an image for `screenshot` and `zoom`; a short text such as `OK` is enough for the other actions.
- If an action fails, return `is_error: true` for that block and answer the rest of the batch as described in [Batch actions](#batch-actions).
4. 4
### Claude continues until the task is complete
- Claude analyzes the tool results to determine if more actions are needed or the task has been completed.
- If Claude determines more actions are needed, it responds with another `tool_use` `stop_reason` and you should return to step 3.
- Otherwise, it returns a text response to the user.
The repetition of steps 3 and 4 without user input is referred to as the "agent loop" (that is, Claude responding with a tool use request and your application responding to Claude with the results of evaluating that request).
### Batch actions
Claude can plan a short sequence of actions, such as click, type, and then take a screenshot, and return them together in one response. This is called a batch action; it uses the same response shape as [parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md) with one difference: you run the blocks in order rather than concurrently.
A response with a three-action batch looks like this:
```python
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
"name": "left_click",
"toolset_name": "computer",
"input": { "coordinate": [640, 60] }
},
{
"type": "tool_use",
"id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
"name": "type",
"toolset_name": "computer",
"input": { "text": "pictures of cats" }
},
{
"type": "tool_use",
"id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
"name": "screenshot",
"toolset_name": "computer",
"input": {}
}
]
}
```
Return one `tool_result` block for each `tool_use` block, matched by `tool_use_id`, all in the next `user` message. Every result for a member tool must carry `"toolset_name": "computer"`; a result that omits it, or that names a different toolset than its `tool_use` block, is rejected. Only `screenshot` and `zoom` results need an image; for the other members, a short text acknowledgment such as `OK` is enough (`cursor_position` returns the coordinates as text):
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
"toolset_name": "computer",
"content": [{ "type": "text", "text": "OK" }]
},
{
"type": "tool_result",
"tool_use_id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
"toolset_name": "computer",
"content": [{ "type": "text", "text": "OK" }]
},
{
"type": "tool_result",
"tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
"toolset_name": "computer",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": "iVBORw0KGgo..."
}
}
]
}
]
}
```
**Run blocks in order and stop at the first failure.** Later actions in a batch usually depend on earlier ones: the `type` in this example enters text into whatever the preceding click focused. Run the blocks sequentially in the order they appear in `content`, and if one fails, don't run the rest. Every `tool_use` block still needs a `tool_result`, so answer the batch as follows:
- For each action that succeeded, return its normal result.
- For the action that failed, return `is_error: true` with a text description of what went wrong.
- For every later action in the batch, return `is_error: true` with exactly this text (the browser use tool uses its own [halt text](agents-and-tools-tool-use-browser-use-tool.md#batch-actions)):
```python
{
"type": "tool_result",
"tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
"toolset_name": "computer",
"is_error": true,
"content": "Not executed: an earlier computer action in this turn failed."
}
```
Claude then sees which actions succeeded, which one failed, and which were skipped, and replans on its next turn. A request that leaves any `tool_use` block in the batch unanswered is rejected with an `invalid_request_error`, so an agent loop that reads only the first block fails on its next call. If your application asks a human to confirm consequential actions, make that check before each block runs, because a batch can complete a multistep action within one turn.
Claude typically finishes a batch with `screenshot` so it can observe the outcome before determining what to do next. When a batch doesn't end with one, your application can attach a screenshot as an extra `image` block on the last result in the batch so that Claude always sees the current state of the screen, which saves a round trip compared with waiting for Claude to ask. You can also prompt Claude to end every batch with a screenshot (see [Optimize model performance with prompting](#optimize-model-performance-with-prompting)).
### The computing environment
Computer use requires a sandboxed computing environment where Claude can safely interact with applications and the web. This environment includes:
1. **Virtual display:** A virtual X11 display server (using Xvfb) that renders the desktop interface Claude will see through screenshots and control with mouse/keyboard actions.
2. **Desktop environment:** A lightweight UI with window manager (Mutter) and panel (Tint2) running on Linux, which provides a consistent graphical interface for Claude to interact with.
3. **Applications:** Pre-installed Linux applications such as Firefox, LibreOffice, text editors, and file managers that Claude can use to complete tasks.
4. **Tool implementations:** Integration code that translates Claude's abstract tool requests (such as "move mouse" or "take screenshot") into actual operations in the virtual environment.
5. **Agent loop:** A program that handles communication between Claude and the environment, sending Claude's actions to the environment and returning the results (screenshots, command outputs) back to Claude.
When you use computer use, Claude doesn't directly connect to this environment. Instead, your application:
1. Receives Claude's tool use requests
2. Translates them into actions in your computing environment
3. Captures the results (such as screenshots and command outputs)
4. Returns these results to Claude
For security and isolation, the reference implementation runs all of this inside a Docker container with appropriate port mappings for viewing and interacting with the environment.
------------------------------------------------------------------------
## How to implement computer use
Upgrading an existing `computer_20251124` integration? Start with [Migrate from `computer_20251124`](#migrate-from-computer-20251124); the rest of this section applies to both new and migrated integrations.
The [computer use reference implementation](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo) is a complete working example: a [containerized environment](https://github.com/anthropics/anthropic-quickstarts/blob/main/computer-use-demo/Dockerfile) suitable for computer use, implementations of [the computer use tools](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo/computer_use_demo/tools), an [agent loop](https://github.com/anthropics/anthropic-quickstarts/blob/main/computer-use-demo/computer_use_demo/loop.py) that calls the Claude API and runs the tools, and a web interface for the container, loop, and tools.
### Understand the agent loop
The core of computer use is the "agent loop": a cycle where Claude requests tool actions, your application runs them, and returns results to Claude. The loop uses the client you created in the [Quick start](#quick-start), a `tools` array that declares only the computer use toolset, and the tool-call processing helper under [Implement the computer use tool](#implement-the-computer-use-tool). If you also declare other tools, such as the Quick start's bash and text editor tools, dispatch their `tool_use` blocks in the same pass; the helper answers only computer use member calls, and the loop treats a turn with no answered calls as finished. Here's a simplified example:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
def sampling_loop(model: str, messages: list[MessageParam], max_iterations: int = 10):
"""
Run the computer-use agent loop until Claude stops requesting tools
or the iteration limit is reached.
"""
for _ in range(max_iterations):
response = client.messages.create(
model=model,
max_tokens=4096,
messages=messages,
tools=TOOLS,
)
# Add Claude's response to the conversation history
messages.append({"role": "assistant", "content": response.content})
# Run the actions Claude requested, in order, and collect the results
tool_results = process_tool_calls(response)
if not tool_results:
return messages # No more tool use; task complete
# Send every result back to Claude in a single user message
messages.append({"role": "user", "content": tool_results})
return messages
```
The loop continues until either Claude responds without requesting any tools (task completion) or the maximum iteration limit is reached. This safeguard prevents potential infinite loops that could result in unexpected API costs.
### Optimize model performance with prompting
1. Specify simple, well-defined tasks and provide explicit instructions for each step.
2. Claude sometimes assumes outcomes of its actions without explicitly checking their results. To prevent this you can prompt Claude with `After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. State in one sentence what the screenshot shows and whether the step succeeded. If it didn't, try again. Only when you confirm a step was executed correctly should you move on to the next one.`
3. Some UI elements (such as dropdowns and scrollbars) might be tricky for Claude to manipulate using mouse movements. If you experience this, try prompting the model to use keyboard shortcuts.
4. For repeatable tasks or UI interactions, include example screenshots and tool calls of successful outcomes in your prompt.
5. If you need the model to log in, provide it with the username and password in your prompt inside XML tags such as ``. Using computer use within applications that require login increases the risk of bad outcomes as a result of prompt injection. Review [Mitigate jailbreaks and prompt injections](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-mitigate-jailbreaks.md) before providing the model with login credentials.
6. When constructing a user turn's `content` array, place the instruction text *before* the screenshot image. Providing the target description before the image is processed improves click accuracy.
7. Claude uses the `zoom` action to inspect a region at full resolution when asked about small text or specific UI elements that aren't legible at the screenshot's default resolution, such as file names in a sidebar, tab titles, status-bar text, line numbers, or button labels. If Claude isn't zooming when you expect, ask about a specific region or element rather than the screen as a whole.
8. If you want every [batch action](#batch-actions) to end with a screenshot, say so in the system prompt, for example, `End each group of actions with a screenshot so you can verify the result before continuing.`
If you repeatedly encounter a clear set of issues or know in advance the tasks Claude will need to complete, use the system prompt to provide Claude with explicit tips or instructions on how to do the tasks successfully.
For agents that span multiple sessions, run end-to-end verification at the start of each session, not only after implementation. Browser-based checks catch regressions from prior sessions that code-level review alone misses. See [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) for details.
### System prompts
When you include the computer use tool in a request, the API generates a computer use-specific system prompt. It's similar to the [tool use system prompt](agents-and-tools-tool-use-implement-tool-use.md#tool-use-system-prompt) but starts with:
> You have access to a set of functions you can use to answer the user's question. This includes access to a sandboxed computing environment. You do NOT currently have the ability to inspect files or interact with external resources, except by invoking the below functions.
As with regular tool use, the user-provided `system` parameter is still respected and used in the construction of the combined system prompt.
### Available actions
Each action is a member tool of the computer use toolset: Claude names the member in a `tool_use` block that carries `"toolset_name": "computer"`, and the block's `input` holds only that member's parameters, with no `action` field. The toolset has 17 member tools:
| Member | Input | Description |
|---------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `screenshot` | None (`{}`) | Capture the full display and return it as an image. |
| `zoom` | `region`: `[x0, y0, x1, y1]`, the top-left and bottom-right corners of the area to inspect | Capture only that region of the display at full resolution and return it as an image, scaled to fit within your usual screenshot dimensions with its aspect ratio preserved. This lets Claude read small text or dense UI that isn't legible in a downscaled full screenshot. |
| `left_click` | `coordinate` (optional): `[x, y]`; `text` (optional): modifier keys to hold during the click: `shift`, `ctrl`, `alt`, `super` (the Command or Windows key), or a `+`-joined combination such as `ctrl+shift` | Click the left mouse button at `coordinate`, or at the current cursor position when `coordinate` is omitted. |
| `right_click`, `middle_click`, `double_click`, `triple_click` | Same as `left_click` | Other mouse buttons and multiple clicks. |
| `left_click_drag` | `start_coordinate`: `[x, y]`; `coordinate`: `[x, y]`; `text` (optional): modifier keys | Press at `start_coordinate`, drag to `coordinate`, and release. |
| `mouse_move` | `coordinate`: `[x, y]` | Move the cursor without clicking, for example, to hover. |
| `left_mouse_down`, `left_mouse_up` | None (`{}`) | Press or release the left mouse button at the current cursor position, for drags that `left_click_drag` can't express. Move the cursor with `mouse_move` first. |
| `cursor_position` | None (`{}`) | Report the cursor's current `[x, y]` position as text. |
| `scroll` | `scroll_direction`: `"up"`, `"down"`, `"left"`, or `"right"`; `scroll_amount`: number of scroll-wheel clicks; `coordinate` (optional): `[x, y]`; `text` (optional): modifier keys | Scroll at `coordinate`, or at the current cursor position. |
| `type` | `text`: the string to type | Type literal text at the current keyboard focus. |
| `key` | `text`: a key or a `+`-joined combination such as `"Return"`, `"ctrl+s"`, or `"alt+Tab"`; `repeat` (optional): 1 to 100, default 1 | Press a key or key combination, `repeat` times. |
| `hold_key` | `text`: a key or combination; `duration`: seconds, up to 300 | Hold a key down for the given duration. |
| `wait` | `duration`: seconds, up to 300 | Pause before the next action, for example, while an application loads. |
Keep the following in mind when implementing the members:
- **Coordinates are in screenshot pixels.** Every `coordinate`, `start_coordinate`, and `region` value, and the position that `cursor_position` reports, is in the pixel space of the full-display screenshots you return, with the origin at the top left. Zoom images don't change this: after a `zoom`, Claude still expresses coordinates in the full screenshot's space, never relative to the zoomed image. If you scale screenshots down before returning them, scale Claude's coordinates back up before applying them to the real display (see [Size screenshots to fit image limits](#handle-coordinate-scaling-for-higher-resolutions)).
- **All members are enabled by default, including `zoom`.** If your environment can't produce zoom images, withhold the member with `configs` (see [Tool parameters](#tool-parameters)) rather than leaving it enabled and returning errors. If Claude calls a member that you have withheld or don't implement, return a `tool_result` with `is_error: true` for that block.
- **Dispatch on the pair (`toolset_name`, `name`).** `toolset_name` is what marks a block as a computer action: a custom tool in the same request can share a member's name, and a later toolset version can add members (see [Client toolsets](agents-and-tools-tool-use-tool-reference.md#client-toolsets)).
### Example actions
Each example is a complete `tool_use` block as it appears in Claude's response.
Shift+click at a position, for example, to extend a selection. Unlike `hold_key`, `text` holds the modifiers only for the duration of that click or scroll:
```python
{
"type": "tool_use",
"id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
"name": "left_click",
"toolset_name": "computer",
"input": { "coordinate": [500, 300], "text": "shift" }
}
```
Drag from one point to another:
```python
{
"type": "tool_use",
"id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
"name": "left_click_drag",
"toolset_name": "computer",
"input": {
"start_coordinate": [200, 300],
"coordinate": [600, 300]
}
}
```
Scroll down three clicks of the wheel:
```python
{
"type": "tool_use",
"id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
"name": "scroll",
"toolset_name": "computer",
"input": {
"coordinate": [500, 400],
"scroll_direction": "down",
"scroll_amount": 3
}
}
```
Press Tab four times:
```python
{
"type": "tool_use",
"id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
"name": "key",
"toolset_name": "computer",
"input": { "text": "Tab", "repeat": 4 }
}
```
Zoom in to inspect a region at full resolution:
```python
{
"type": "tool_use",
"id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
"name": "zoom",
"toolset_name": "computer",
"input": { "region": [100, 200, 400, 350] }
}
```
Report the cursor position. Answer this call with a short text result that gives the position in screenshot pixels, for example, `X=512, Y=384`:
```python
{
"type": "tool_use",
"id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
"name": "cursor_position",
"toolset_name": "computer",
"input": {}
}
```
### Tool parameters
The toolset entry in the `tools` array accepts four parameters; the rules they share with the browser use toolset are listed under [Client toolsets](agents-and-tools-tool-use-tool-reference.md#client-toolsets).
| Parameter | Required | Description |
|-------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `type` | Yes | `computer_toolset_20260801` |
| `configs` | No | Per-member settings keyed by member name; each member accepts `enabled` (default `true` for all 17, including `zoom`) and `defer_loading` (default `false`, for [tool search](agents-and-tools-tool-use-tool-search-tool.md#deferred-tool-loading)), and members you omit keep their defaults. |
| `cache_control` | No | [Prompt caching](../Guides/build-with-claude-prompt-caching.md) breakpoint at the toolset definition; entry only. A breakpoint on any `tool_use` or `tool_result` block in a batch takes effect at the end of that batch; see [Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md#cache-control-on-tool-definitions). |
| `allowed_callers` | No | `["direct"]` only. |
For example, this entry withholds `zoom` for an environment that doesn't implement it and sets a cache breakpoint at the toolset definition:
```python
{
"type": "computer_toolset_20260801",
"configs": {
"zoom": { "enabled": false }
},
"cache_control": { "type": "ephemeral" }
}
```
If your agent loop can run only one action per round trip, set `disable_parallel_tool_use` to `true` in `tool_choice`; Claude then returns at most one member `tool_use` block per turn (see [Disable parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md#disable-parallel-tool-use)).
The entry rejects these parameters from earlier tool versions, and a request that includes any of them returns an `invalid_request_error`:
- `name`: member names are fixed by the toolset version.
- `display_width_px`, `display_height_px`, and `display_number`: coordinates are always in the pixel space of the screenshots you return.
- `enable_zoom`: zoom is a member tool that you control through `configs`.
The entry also can't be declared in the same request as a `computer_20251124` entry or another tool named `computer`. For `strict`, `input_examples`, `defer_loading` placement, `tool_choice`, streaming, and caller restrictions, see [Client toolsets](agents-and-tools-tool-use-tool-reference.md#client-toolsets).
### Combining with thinking
To combine computer use with thinking, see [Thinking](../Guides/build-with-claude-thinking.md).
For the earlier `computer_20251124` tool, internal benchmarking on the models that use it suggests these `effort` settings:
- **Claude Opus 4.7:** use `high` as the default; use `low` for high-throughput or cost-sensitive workloads.
- **Claude Sonnet 4.6 and Claude Opus 4.6:** use `medium` as the default (best accuracy-to-cost ratio). Avoid `max`, which adds token cost without improving accuracy on UI tasks. On these models, `low` uses *fewer* output tokens than disabling thinking entirely (fewer mistakes mean fewer retries), making it a strong option for cost-sensitive loops.
### Augmenting computer use with other tools
To add other tools alongside computer use, include them in the same `tools` array. The [Quick start](#quick-start) section shows this pattern with the [bash tool](agents-and-tools-tool-use-bash-tool.md) and [text editor tool](agents-and-tools-tool-use-text-editor-tool.md). You can add your own [custom tool definitions](agents-and-tools-tool-use-implement-tool-use.md) the same way.
For tasks that stay inside webpages, you can also [declare the browser use tool in the same request](agents-and-tools-tool-use-browser-use-tool.md#combine-with-other-tools): the two toolsets work independently, each in its own coordinate frame, and calls to members that share a name, such as `screenshot` or `key`, are told apart by `toolset_name`.
### Build a custom computer use environment
The [reference implementation](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo) is meant to help you get started with computer use. It includes all of the components needed to have Claude use a computer. However, you can build your own environment for computer use to suit your needs. You'll need:
- A virtualized or containerized environment suitable for computer use with Claude
- An implementation of the computer use tool's actions
- An agent loop that interacts with the Claude API and runs the `tool_use` results using your tool implementations
- An API or UI that allows user input to start the agent loop
### Implement the computer use tool
The computer use tool is implemented as a schema-less tool. When using this tool, you don't need to provide an input schema as with other tools; the schema is built into Claude's model and can't be modified.
1. 1
### Set up your computing environment
Create a virtual display or connect to an existing display that Claude will interact with. This typically involves setting up Xvfb (X Virtual Framebuffer) or similar technology.
2. 2
### Implement action handlers
Create functions to handle each action type that Claude might request:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
``` shiki
# Placeholder image data; a real executor captures the screen and returns the PNG bytes
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
def capture_screenshot() -> list[ImageBlockParam]:
# screenshot answers with an image block rather than text: return the result content list
return [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": PLACEHOLDER_PNG,
},
}
]
def click(coordinate=None):
if coordinate is None:
return "clicked at current cursor"
x, y = coordinate
return f"clicked at ({x}, {y})"
def type_text(text):
return f"typed: {text}"
def handle_computer_action(name, tool_input):
match name:
case "screenshot":
return capture_screenshot()
case "left_click":
# coordinate is optional; without it, click where the cursor already is
return click(tool_input.get("coordinate"))
case "type":
return type_text(tool_input["text"])
# Handle other actions as needed
raise ValueError(f"Unknown or unimplemented member: {name}")
```
3. 3
### Process Claude's tool calls
Extract and run tool calls from Claude's responses:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
``` shiki
NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."
def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
"""
Run the computer actions in Claude's response in order and answer each
one. After the first failure the rest are skipped, because Claude planned
them assuming the earlier actions succeeded.
"""
tool_results: list[ToolResultBlockParam] = []
failed = False
for block in response.content:
# Only the computer toolset is declared; route other tools here if you add them
if block.type != "tool_use" or block.toolset_name != "computer":
continue
result: ToolResultBlockParam = {
"type": "tool_result",
"tool_use_id": block.id,
"toolset_name": "computer",
}
if failed:
result["content"] = NOT_EXECUTED
result["is_error"] = True
else:
try:
# A string, or a list of content blocks such as the screenshot image
result["content"] = handle_computer_action(block.name, block.input)
except Exception as err:
result["content"] = f"Error: {err}"
result["is_error"] = True
failed = True
tool_results.append(result)
return tool_results
```
4. 4
### Implement the agent loop
Wrap the two previous steps in a loop that sends the results back and repeats until Claude returns no member tool calls; [Understand the agent loop](#understanding-the-agentic-loop) shows this loop in each language.
### Handle errors
Report a failed action to Claude as a `tool_result` with `is_error: true` and a short description, and include `"toolset_name": "computer"` as on any other member result. If the failed action was part of a [batch action](#batch-actions), answer the remaining blocks in the batch with the halt text shown there instead of running them.
For example, when screenshot capture fails:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"toolset_name": "computer",
"content": "Error: Failed to capture screenshot. Display may be locked or unavailable.",
"is_error": true
}
]
}
```
Use the same shape for coordinates outside the display bounds and for actions that fail to run, with a message that says what went wrong.
### Size screenshots to fit image limits
Screenshots and zoom images that you return to the computer use toolset must already fit within your model's [image size limits](../Guides/build-with-claude-vision.md#evaluate-image-size): the toolset takes no display dimensions and the API doesn't downscale for you, so an oversized `tool_result` image is rejected with a validation error. Because Claude returns coordinates in the pixel space of the image it sees, keep the scale factor you used so you can map those coordinates back to your screen.
Limits vary by model. Claude Opus 4.7 and later models, including every model that supports `computer_toolset_20260801`, accept up to 2576 pixels on the long edge and 4784 visual tokens total (`⌈width / 28⌉ × ⌈height / 28⌉`, approximately 3.75 megapixels); earlier models accept up to 1568 pixels on the long edge and approximately 1.15 megapixels total (see [Resolution and token cost](../Guides/build-with-claude-vision.md#evaluate-image-size) for each model's tier). The following example uses the earlier-model 1568 px / 1.15 MP limits. For a high-resolution-tier model, size to the visual-token limit rather than a pixel total, for example with the resize helper in [Resize your image before uploading](../Guides/build-with-claude-vision-coordinates.md#resize-your-image-before-uploading).
If your screen is larger than the limit, resize each screenshot before returning it and scale Claude's returned coordinates back to the original screen space. Because the toolset takes no display dimensions, the resize and the coordinate scaling in your application code are all you need:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
import math
screen_width, screen_height = 1512, 982
def get_scale_factor(width, height):
"""Calculate scale factor to meet API constraints."""
long_edge = max(width, height)
total_pixels = width * height
long_edge_scale = 1568 / long_edge
total_pixels_scale = math.sqrt(1_150_000 / total_pixels)
return min(1.0, long_edge_scale, total_pixels_scale)
# When capturing screenshot
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)
# Resize image to scaled dimensions before sending to Claude
screenshot = capture_and_resize(scaled_width, scaled_height)
# When handling Claude's coordinates, scale them back up
def execute_click(x, y):
screen_x = x / scale
screen_y = y / scale
perform_click(screen_x, screen_y)
```
**macOS Retina displays** capture screenshots at a device pixel ratio of 2, so the image is twice the resolution of the logical screen coordinates. Either downscale the screenshot by 2x before sending, or halve the coordinates Claude returns before issuing the click.
When you choose a display resolution and return screenshots:
- For general desktop tasks, use 1024x768 or 1280x720; for web applications, use 1280x800 or 1366x768.
- Avoid resolutions above 1920x1080 to prevent performance issues.
- Encode screenshots as base64 PNG or JPEG, and consider compressing large screenshots to improve performance.
- Include relevant metadata such as timestamp or display state.
- If you use higher resolutions, ensure coordinates are accurately scaled.
### Manage screenshot history
Long agent loops accumulate screenshots quickly (roughly 1,000–1,800 input tokens each). The API's [request limits](../Guides/build-with-claude-vision.md#request-limits) also apply. Once a single request carries more than 20 images, every image in it is held to a stricter per-side limit. A loop that keeps its screenshot history reaches that count within a few dozen turns, so either resize each screenshot so that neither side exceeds 2000 px or prune older screenshots to keep 20 or fewer in the request.
To keep [Prompt caching](../Guides/build-with-claude-prompt-caching.md) effective while bounding context:
- Place one `cache_control` breakpoint after the system prompt and tool definitions, and up to three more on the last `tool_result` block of each of the most recent turns, advancing them each turn. Within a [batch action](#batch-actions), markers on several blocks act as a single breakpoint but each still counts toward the limit of four, so use one per turn.
- Prune old screenshots in *batches*, not one each turn. Dropping a screenshot every turn changes the prefix every turn and invalidates the cache. A reasonable default is to keep the last three screenshots and prune every 25 turns, so the prefix stays byte-identical between prune events; if your screenshots exceed 2000 px on either side, choose an interval that keeps each request at 20 or fewer images.
- On Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, avoid pruning on the client: removing an earlier screenshot [invalidates every later thinking block](../Guides/build-with-claude-thinking.md#preserved-in-conversation) in every request that still carries those turns. Resize screenshots to 2000 px or less per side instead, and use server-side [tool result clearing](../Guides/build-with-claude-context-editing.md#tool-result-clearing) to drop old ones from the context. If you must prune, keep [`prefix_mismatch_behavior: "drop_block"`](../Guides/build-with-claude-thinking.md#preserved-thinking-controls) set from then on; after each prune, Claude continues without the thinking produced since the pruned screenshot, on that request and every later one. On Claude Sonnet 5.5, `block_binding` works only with `thinking: {"type": "adaptive"}`. With `between_tools`, keep the history append-only, or strip the thinking blocks from the edited turn on. On Claude Haiku 5.5, `block_binding` works only with `thinking: {"type": "adaptive"}`; with `thinking: {"type": "disabled"}`, keep the history append-only, or strip the thinking blocks from the edited turn on.
### Diagnose click issues
If clicks miss their targets, the cause is usually one of the following:
| Symptom | Likely cause | Try |
|---------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Clicks consistently offset in one direction | Claude's coordinates, which are in the pixel space of the screenshots you return, are being applied to a display of a different size without scaling | Scale each coordinate by the ratio of your screen size to your screenshot size before clicking (see [Size screenshots to fit image limits](#handle-coordinate-scaling-for-higher-resolutions)); on macOS Retina displays, account for the 2x device pixel ratio |
| Clicks land in the right area but miss the target | Target is very small, detail was lost downscaling a 4K+ source, or aspect ratio was distorted | Keep the `zoom` member enabled and implement it so Claude can inspect the region at full resolution; capture at lower DPI or crop to the relevant region; preserve aspect ratio when resizing |
| Claude clicks the wrong element entirely | Ambiguous instruction, or visually similar elements nearby | Use positional prompts ("the blue Submit button in the bottom-right"); break the interaction into smaller steps |
| Accuracy is consistently poor | Resolution too low | Try 1280x720 as a baseline |
**Model choice affects click precision.** Among the models that use the earlier `computer_20251124` tool, Claude Sonnet 4.6 is more mechanically precise at clicking than Claude Opus 4.6 and is more robust when screenshots require heavy downscaling. Claude Opus 4.7 narrows that gap: its click precision is roughly comparable to Sonnet 4.6, and its higher resolution limit means less downscaling is needed.
### Follow implementation best practices
### Add action delays
Some applications need time to respond to actions:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
def click_and_wait(x, y, wait_time=0.5):
click_at(x, y)
time.sleep(wait_time) # Allow UI to update
```
### Validate actions before running them
Check that requested actions are safe and valid:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
display_width, display_height = 1024, 768
def validate_action(action_type, params):
if action_type == "left_click" and "coordinate" in params:
x, y = params["coordinate"]
if not (0 <= x < display_width and 0 <= y < display_height):
return False, "Coordinates out of bounds"
return True, None
```
### Log actions for debugging
Keep a log of all actions for troubleshooting:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
import logging
def log_action(action_type, params, result):
logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")
```
------------------------------------------------------------------------
## Migrate from `computer_20251124`
Upgrading from `computer_20251124` to the toolset is optional: the models listed for `computer_20251124` under [Earlier tool versions](#earlier-tool-versions) keep accepting it with its beta header, so an existing integration keeps working until you change it. Claude 5.5 and later models are the exception on the Claude API and Google Cloud: there they accept only the toolset. Upgrade an integration before you move it to one of them. On Amazon Bedrock, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5 accept `computer_20251124`. To upgrade, make the following changes together:
1. **Remove the beta header.** Drop `anthropic-beta: computer-use-2025-11-24` from your requests. With the SDK, remove `betas` and call the Messages API through the standard client rather than the beta namespace.
2. **Change the `tools` entry.** Set `type` to `computer_toolset_20260801` and delete `name`, `display_width_px`, `display_height_px`, `display_number`, and `enable_zoom`. The toolset rejects each of these fields.
3. **Choose whether to keep zoom enabled.** Zoom is enabled by default on the toolset, whereas `enable_zoom` defaults to `false`. If your environment doesn't implement zoom, add `"configs": {"zoom": {"enabled": false}}` to keep the previous behavior; otherwise implement it (see [Available actions](#available-actions)).
4. **Handle every block in a turn.** Update your agent loop to iterate over every `tool_use` block in a response rather than reading only the first, and to dispatch on the block's `name` together with `toolset_name` instead of on `input.action`. Member inputs no longer contain an `action` field; the remaining fields are unchanged.
5. **Run blocks in order and use the halt text.** Run the blocks sequentially, stop at the first failure, and answer the remaining blocks with `Not executed: an earlier computer action in this turn failed.` as described in [Batch actions](#batch-actions). If your loop can't run batches yet, [Tool parameters](#tool-parameters) explains how to limit Claude to one action per turn.
6. **Echo `toolset_name` on results.** Add `"toolset_name": "computer"` to every `tool_result` that answers a member call. Results may contain only `text` and `image` content.
7. **Support `repeat` on `key`.** The `key` member accepts an optional `repeat` count from 1 to 100. A handler that ignores unrecognized fields would press the key once, so make your `key` handler honor `repeat`.
8. **Resize screenshots yourself.** The toolset rejects a screenshot or zoom image that exceeds the model's image limits instead of downscaling it. Resize before returning the image and keep scaling coordinates as described in [Size screenshots to fit image limits](#handle-coordinate-scaling-for-higher-resolutions).
9. **Remove unsupported options.** Move any `defer_loading` from the entry into `configs`, with the same value on every enabled member. The other options not supported on toolset entries are listed under [Client toolsets](agents-and-tools-tool-use-tool-reference.md#client-toolsets).
This is the `tools` entry before the change, sent with the `anthropic-beta: computer-use-2025-11-24` header:
```python
{
"type": "computer_20251124",
"name": "computer",
"display_width_px": 1024,
"display_height_px": 768,
"display_number": 1
}
```
This is the `tools` entry after the change, sent with no beta header. The `configs` object keeps zoom off to match the earlier entry, which doesn't set `enable_zoom`; omit `configs` entirely to accept the default and let Claude zoom:
```python
{
"type": "computer_toolset_20260801",
"configs": {
"zoom": { "enabled": false }
}
}
```
The following pair shows a `tool_use` block before and after the change. The action name moves from `input.action` to `name`, and the block gains `toolset_name`:
```python
{
"type": "tool_use",
"id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
"name": "computer",
"input": { "action": "left_click", "coordinate": [500, 300] }
}
```
```python
{
"type": "tool_use",
"id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
"name": "left_click",
"toolset_name": "computer",
"input": { "coordinate": [500, 300] }
}
```
## Earlier tool versions
Two earlier versions of the computer use tool remain available in beta for existing integrations, for models that don't support the toolset, and on platforms where the toolset isn't currently available. Each requires its [beta header](../Endpoints/beta-headers.md) on every request, and their parameters are documented in the [beta Messages API reference](../Endpoints/beta-messages-create.md). With the SDK, pass the header through `betas` and use the beta namespace; only the computer use tool needs the header, not the bash or text editor tools in the same request.
| Tool version | Beta header | Use with | Parameters |
|---------------------|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|
| `computer_20251124` | `computer-use-2025-11-24` | Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, and Claude Opus 4.5; on Amazon Bedrock, also Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5 | [API reference](../Endpoints/beta-messages-create.md) |
| `computer_20250124` | `computer-use-2025-01-24` | Claude Sonnet 4.5 ([deprecated](../../20-Models/about-claude-model-deprecations.md)), Claude Haiku 4.5, Claude Opus 4.1 ([retired, except on Bedrock and Google Cloud](../../20-Models/about-claude-model-deprecations.md)), Claude Sonnet 4 ([retired, except on Bedrock and Google Cloud](../../20-Models/about-claude-model-deprecations.md)), and Claude Opus 4 ([retired, except on Google Cloud](../../20-Models/about-claude-model-deprecations.md)) | [API reference](../Endpoints/beta-messages-create.md) |
------------------------------------------------------------------------
## Limitations
1. **Latency:** The current computer use latency for human-AI interactions might be too slow compared to regular human-directed computer actions. Focus on use cases where speed isn't critical (for example, background information gathering, automated software testing) in trusted environments.
2. **Computer vision accuracy and reliability:** Claude might make mistakes or hallucinate when outputting specific coordinates while generating actions. Claude's [summarized thinking](../Guides/build-with-claude-thinking.md#summarized-thinking) output can help you understand the model's reasoning and identify potential issues; set `display: "summarized"` on the thinking configuration, because the models that support the toolset omit thinking text by default.
3. **Tool selection accuracy and reliability:** Claude might make mistakes or hallucinate when selecting tools while generating actions or take unexpected actions to solve problems. Additionally, reliability might be lower when interacting with niche applications or multiple applications at once. Prompt the model carefully when requesting complex tasks.
4. **Scrolling reliability:** The scroll action supports direction control (up, down, left, right) and a specified amount. In applications where scrolling doesn't take effect, keyboard alternatives such as Page Down can help.
5. **Spreadsheet interaction:** Use the fine-grained mouse control actions (`left_mouse_down`, `left_mouse_up`) and modifier-key combinations to select individual cells. Complex spreadsheet operations might still require multiple attempts.
6. **Account creation and content generation on social and communications platforms:** Although Claude visits websites, its ability to create accounts, generate and share content, or otherwise engage in human impersonation across social media websites and platforms is limited.
7. **Vulnerabilities:** Jailbreaks and prompt injection can affect computer use as they can any frontier AI system, including through instructions embedded in webpages or images; apply the precautions in [Security considerations](#security-considerations).
8. **Inappropriate or illegal actions:** Under Anthropic's Terms of Service, you must not employ computer use to violate any laws or the Acceptable Use Policy.
Always carefully review and verify Claude's computer use actions and logs. Do not use Claude for tasks requiring perfect precision or sensitive user information without human oversight.
## Data retention
Computer use is a client-side tool. All screenshots, mouse actions, keyboard inputs, and any files involved in a session are captured and stored in your environment, not by Anthropic. Anthropic processes the screenshot images and action requests in real time as part of the API call. Retention for those API requests is governed by [API and data retention](../Other/manage-claude-api-and-data-retention.md).
Because your application controls where and how computer use data is stored, computer use is ZDR eligible. For ZDR eligibility across all features, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
## Pricing
Computer use follows the standard [tool use pricing](agents-and-tools-tool-use-overview.md#pricing). When using the computer use tool:
**Toolset definition overhead:** Declaring `computer_toolset_20260801` with its default members adds about 4,500 input tokens to a request (about 4,590 on Claude Sonnet 5 and about 4,520 on the other supported models), which covers the member tool definitions and the tool use system prompt. Disabling `zoom` with `configs` removes about 410 of those tokens. The exact count for a request is reported in the response `usage`, and you can estimate it in advance with the [token counting endpoint](../Guides/build-with-claude-token-counting.md).
**Earlier tool versions:** The following figures apply to the `computer_20251124` and `computer_20250124` tool versions, not to `computer_toolset_20260801`:
- System prompt overhead: 466–499 tokens added to the system prompt
- Tool definition: about 735 input tokens per tool definition (measured with `computer_20250124`)
**Additional token consumption:**
- Screenshot and zoom images returned in tool results, billed as image input (see [Vision pricing](../Guides/build-with-claude-vision.md#evaluate-image-size))
- Tool execution results returned to Claude
If you're also using bash or text editor tools alongside computer use, those tools have their own token costs as documented in their respective pages.
## Next steps
[Computer toolset in the SDKs](agents-and-tools-tool-use-browser-use-sdk.md#computer-toolset)
Start from a partner's driver, or write your own in Python or TypeScript. The SDK runs the loop and the approval callback you pass.
[Troubleshooting tool use](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Fix the most common tool-use errors with symptom-to-fix diagnostic tables.
[Reference implementation](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo)
Get started with the complete Docker-based implementation
[Tool use with Claude](agents-and-tools-tool-use-overview.md)
Connect Claude to external tools and APIs. See where tools execute, when Claude calls them, and which tool fits your task.
[Best practices in detail](https://claude.com/blog/best-practices-for-computer-and-browser-use-with-claude)
Benchmarked recommendations for resolution, thinking effort, and context management
[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)
Let Claude navigate, read, and interact with webpages in your own browser environment, for tasks that stay inside the browser.
## Compatibility
Supported models
- Fable 5 and 5.1
- Mythos 5 and 5.1
- Opus 4.8, 5, and 5.5
- Sonnet 5 and 5.5
- Haiku 5.5
Supported platforms
- Claude API
- Claude Platform on AWSBeta
- Amazon BedrockBeta
- Google Cloud
- Microsoft FoundryBeta
- On the Claude API and Google Cloud, Claude 5.5 and later models support computer use only through the `computer_toolset_20260801` toolset and return an error for the earlier `computer_20251124` and `computer_20250124` tool versions. To move an existing integration, see [Migrate from `computer_20251124`](#migrate-from-computer-20251124). To move from `computer_20250124`, see [Move computer use to the toolset](../../20-Models/models-haiku-5-5-migration-guide.md#computer-use-toolset) in the Claude Haiku 5.5 migration guide.
- On Amazon Bedrock, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5 accept the earlier `computer_20251124` tool version as Claude Opus 5 and Claude Sonnet 5 do.
- Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, and Claude Opus 4.5 support computer use only through the earlier `computer_20251124` tool version, which requires a beta header; see [Earlier tool versions](#earlier-tool-versions).
- Platforms other than the Claude API and Google Cloud currently offer only the [earlier beta tool versions](#earlier-tool-versions).
---
## Fine-grained tool streaming - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-fine-grained-tool-streaming.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Ffine-grained-tool-streaming)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tool infrastructure
# Fine-grained tool streaming
Copy page
Stream tool inputs without server-side JSON buffering for latency-sensitive applications.
Copy page
To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
Fine-grained tool streaming delivers a tool's input to your client as Claude generates it, without server-side buffering or JSON validation. Skipping the buffering step reduces the time to the first fragment of a large parameter, such as a document or a block of code, and the fragments arrive through the same [Streaming messages](../Guides/build-with-claude-streaming.md) events as standard tool use.
Because the API does not buffer or validate a tool's input before streaming it, you might receive partial or invalid JSON. A response that ends with the [stop reason](../Guides/build-with-claude-handling-stop-reasons.md) `max_tokens` can also cut a parameter off midway. Accumulate the fragments, guard the parse, and see [Handling invalid JSON in tool responses](#handling-invalid-json-in-tool-responses) for how to return unparseable input to Claude.
## How to use fine-grained tool streaming
All models support fine-grained tool streaming on the Claude API, [Amazon Bedrock](../Guides/build-with-claude-claude-in-amazon-bedrock.md), [Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md), [Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md), and [Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md). To use it, set `eager_input_streaming` to `true` on any user-defined tool where you want fine-grained streaming enabled, and enable streaming on your request.
The `eager_input_streaming` field is optional. Setting it to `true` turns on fine-grained streaming for that tool, and omitting it gives you standard buffered streaming, in which the API buffers and validates each parameter value before streaming it back. The exception is a request that still sends the legacy `fine-grained-tool-streaming-2025-05-14` beta header, which turns fine-grained streaming on for tools that leave the field unset. The per-tool field replaces that header, and an explicit `false` keeps buffered streaming for a tool even when a request still sends it. The legacy header cannot be combined with a [computer use](agents-and-tools-tool-use-computer-use-tool.md) or [browser use](agents-and-tools-tool-use-browser-use-tool.md) toolset entry: the API rejects a request that sends both, so remove the header and set `eager_input_streaming` on the user-defined tools that need it. See [Tool reference](agents-and-tools-tool-use-tool-reference.md) for the field definition.
The following example turns on fine-grained streaming for a `make_file` tool and asks Claude for a long poem, so the tool input is large enough to watch it stream in:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
with client.messages.stream(
max_tokens=65536,
model="claude-opus-5-5",
tools=[
{
"name": "make_file",
"description": "Write text to a file",
"eager_input_streaming": True,
"input_schema": {
"type": "object",
"properties": {
"filename": {
"type": "string",
"description": "The filename to write text to",
},
"lines_of_text": {
"type": "array",
"description": "An array of lines of text to write to the file",
},
},
"required": ["filename", "lines_of_text"],
},
}
],
messages=[
{
"role": "user",
"content": "Can you write a long poem and make a file called poem.txt?",
}
],
) as stream:
for event in stream:
if event.type == "input_json":
print(event.partial_json, end="", flush=True)
final_message = stream.get_final_message()
print()
for block in final_message.content:
if block.type == "tool_use":
print(f"Complete tool input: {block.input}")
```
Each input fragment arrives the moment Claude writes it, and the fragments join into the full tool input, so the poem arrives piece by piece:
```python
{"filename": "poem.txt", "lines_of_text": ["The Wanderer's Journey", "", "I.", "", "Beneath the vast and star-strewn sky,", "Where silver moonbeams softly lie,", ...
Complete tool input: {"filename": "poem.txt", "lines_of_text": ["The Wanderer's Journey", ...]}
```
Without `eager_input_streaming`, the API buffers and validates each parameter value before streaming it back, so nothing prints for a large parameter until Claude has finished generating it. With it, fragments start arriving as soon as Claude begins the parameter, and they are typically longer, with fewer mid-word breaks.
## Accumulating tool input deltas
The accumulation contract is the same as for standard tool-use streaming, so this section applies with and without `eager_input_streaming`. See [Input JSON delta](../Guides/build-with-claude-streaming.md#input-json-delta) in Streaming messages for the event format. Fine-grained tool streaming changes what you can assume about the result: the server streams fragments without validating them, so the accumulated string might not be valid JSON.
When a `tool_use` content block streams, the initial `content_block_start` event contains `input: {}` (an empty object). This is a placeholder. The actual input arrives as a series of `input_json_delta` events, each carrying a `partial_json` string fragment. To assemble the full input, concatenate these fragments and parse the result when the block closes.
Where your SDK provides an accumulator helper (as the Python, TypeScript, Go, Java, and Ruby tabs in the previous example do), it handles this for you. Use the manual pattern when your SDK has no helper or when you want full control over how the input is assembled.
The accumulation contract:
1. On `content_block_start` with `type: "tool_use"`, initialize an empty string: `input_json = ""`
2. For each `content_block_delta` with `type: "input_json_delta"`, append: `input_json += event.delta.partial_json`
3. On `content_block_stop`, parse the accumulated string
Guard the parse, as the following SDK examples do. A response can also stop at `max_tokens` midway through a parameter. Check the [stop reason](../Guides/build-with-claude-handling-stop-reasons.md) and decide whether to retry the request with a higher `max_tokens` or repair the partial input.
The type mismatch between the initial `input: {}` (object) and `partial_json` (string) is by design. The empty object marks the slot in the content array. The delta strings build the real value.
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
tool_inputs: dict[int, str] = {} # index -> accumulated JSON string
with client.messages.stream(
model="claude-opus-5-5",
max_tokens=1024,
tools=[
{
"name": "get_weather",
"description": "Get current weather for a city",
"eager_input_streaming": True,
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
}
],
messages=[{"role": "user", "content": "Weather in Paris?"}],
) as stream:
for event in stream:
match event.type:
case "content_block_start" if event.content_block.type == "tool_use":
tool_inputs[event.index] = ""
case "content_block_delta" if event.delta.type == "input_json_delta":
tool_inputs[event.index] += event.delta.partial_json
case "content_block_stop" if event.index in tool_inputs:
raw_input = tool_inputs[event.index]
try:
parsed = json.loads(raw_input)
except json.JSONDecodeError:
# The accumulated string is not guaranteed to be valid JSON.
# See "Handling invalid JSON in tool responses" on this page.
print(f"Invalid tool input: {raw_input}")
else:
print(f"Tool input: {parsed}")
```
Reacting to fragments and assembling them are separate concerns. The first example reacts to each fragment as it arrives and still hands assembly to the SDK in the tabs that use an accumulator helper. Use the manual pattern when you are not using an accumulator helper or when you want full control over assembly.
## Handling invalid JSON in tool responses
With fine-grained tool streaming, the accumulated input for a tool call might be invalid or incomplete JSON. When it is, you cannot run the tool, so report the failure back to Claude instead. The `content` of a tool result does not have to be JSON, but wrapping the raw string in a JSON object under a single key makes it unambiguous to Claude that you received invalid JSON, and preserves the original input for debugging:
```python
{
"INVALID_JSON": ""
}
```
Return the wrapper, serialized to a string, as the `content` of a [tool result](agents-and-tools-tool-use-handle-tool-calls.md#handling-errors-with-is-error) content block with `is_error` set to `true`:
```python
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"is_error": true,
"content": "{\"INVALID_JSON\": \"\"}"
}
```
Build the wrapper with your JSON library rather than by concatenating strings, so quotes and other special characters in the invalid input are escaped correctly.
## Next steps
[Context windows](../Guides/build-with-claude-context-windows.md)
Understand how the context window works, how extended thinking and tool use count toward it, and how to manage context as conversations grow.
[Streaming messages](../Guides/build-with-claude-streaming.md)
Stream Messages API responses incrementally with server-sent events, including text, tool use, and extended thinking deltas.
[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)
Parse tool_use blocks, format tool_result responses, and handle errors with is_error.
[Tool reference](agents-and-tools-tool-use-tool-reference.md)
Directory of Anthropic-provided tools and reference for optional tool definition properties.
---
## Handle tool calls - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-handle-tool-calls.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fhandle-tool-calls)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Handle tool calls
Copy page
Parse tool_use blocks, format tool_result responses, and handle errors with is_error.
Copy page
This page covers the tool-call lifecycle: reading `tool_use` blocks from Claude's response, formatting `tool_result` blocks in your reply, and signaling errors. For the SDK abstraction that handles this automatically, see [Tool Runner](agents-and-tools-tool-use-tool-runner.md).
**Simpler with Tool Runner:** The manual tool handling described on this page is automatically managed by [Tool Runner](agents-and-tools-tool-use-tool-runner.md). Use this page when you need custom control over tool execution.
Claude's response differs based on whether it uses a [client or server tool](agents-and-tools-tool-use-overview.md#how-tool-use-works).
## Handling results from client tools
The response will have a `stop_reason` of `tool_use` and one or more `tool_use` content blocks that include:
- `id`: A unique identifier for this particular tool use block. This will be used to match up the tool results later.
- `name`: The name of the tool being used.
- `input`: An object containing the input being passed to the tool, conforming to the tool's `input_schema`.
A `tool_use` block for a member of the [computer use](agents-and-tools-tool-use-computer-use-tool.md) or [browser use](agents-and-tools-tool-use-browser-use-tool.md) toolset also carries a `toolset_name` field (`"computer"` or `"browser"`). Its `name` is the member tool Claude is calling, such as `screenshot` or `navigate`, so dispatch those blocks on both fields.
### Example API response with a \`tool_use\` content block
JSON
```python
{
"id": "msg_01Aq9w938a90dw8q",
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll check the current weather in San Francisco for you."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "San Francisco, CA", "unit": "celsius" }
}
]
}
```
When you receive a tool use response for a client tool, you should:
1. Extract the `name`, `id`, and `input` from the `tool_use` block.
2. Run the actual tool in your codebase corresponding to that tool name, passing in the tool `input`.
3. Continue the conversation by sending a new message with the `role` of `user`, and a `content` block containing the `tool_result` type and the following information:
- `tool_use_id`: The `id` of the tool use request this is a result for.
- `content` (optional): The result of the tool, as a string (for example, `"content": "15 degrees"`), a list of nested content blocks (for example, `"content": [{"type": "text", "text": "15 degrees"}]`), or a list of document blocks (for example, `"content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}]`). These content blocks can use the `text`, `image`, `document`, or [`search_result`](../Guides/build-with-claude-search-results.md) types.
- `is_error` (optional): Set to `true` if the tool execution resulted in an error.
A `tool_result` that answers a computer use or browser use member block must also echo the same `toolset_name` value as the `tool_use` block; a member result that omits it is rejected. Its `content` is also narrower: a member result may contain only `text` and `image` blocks, and a browser use result may add one [`browser_state`](agents-and-tools-tool-use-browser-use-tool.md#track-tabs-and-page-state) block (the [tab-management members](agents-and-tools-tool-use-browser-use-tool.md#tab-management-results) return only that block).
**Important formatting requirements:**
- Tool result blocks must immediately follow their corresponding tool use blocks in the message history. You cannot include any messages between the assistant's tool use message and the user's tool result message.
- In the user message containing tool results, the tool_result blocks must come FIRST in the content array. Any text must come AFTER all tool results.
- If the assistant turn also called a [server tool](agents-and-tools-tool-use-server-tools.md) that has no result block yet, the user message must contain only `tool_result` blocks. Text after the results ends the turn early; for a server tool Claude called directly, the request then fails with a 400 error that names the unresolved server tool. See [Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md#tool-use).
For example, this will cause a 400 error:
```python
{
"role": "user",
"content": [
{ "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
{ "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
]
}
```
This is correct when the assistant turn calls only client tools:
```python
{
"role": "user",
"content": [
{ "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
{ "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
]
}
```
If you receive an error like "tool_use ids were found without tool_result blocks immediately after", check that your tool results are formatted correctly.
Tool results often carry content from sources outside your control: web pages, inbound email, user uploads, third-party APIs. Treat that content as untrusted: an attacker who can influence it may embed instructions that try to redirect Claude (indirect prompt injection). Keep untrusted content inside `tool_result` blocks rather than `system` prompts or plain user `text` blocks, and see [Mitigate jailbreaks and prompt injections](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-mitigate-jailbreaks.md#indirect-prompt-injection) for further hardening.
### Example of successful tool result
JSON
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}
```
### Example of tool result with images
JSON
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "15 degrees" },
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
}
]
}
]
}
```
### Example of empty tool result
JSON
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}
```
### Example of tool result with documents
JSON
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "The weather is" },
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "15 degrees"
}
}
]
}
]
}
```
After receiving the tool result, Claude will use that information to continue generating a response to the original user prompt.
## Handling results from server tools
Claude executes the tool internally and incorporates the results directly into its response without requiring additional user interaction.
A response can contain both a client `tool_use` block and a `server_tool_use` block that has no result block. That server tool call is not finished yet, and its result block arrives in a later response. Reply with a user message that contains only the `tool_result` blocks for the client tools and keep the same `tools` array; for a server tool Claude called directly, the API runs it on that request and the next response starts with its result block. See [Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md#tool-use).
**Differences from other APIs**
Unlike APIs that separate tool use or use special roles like `tool` or `function`, the Claude API integrates tools directly into the `user` and `assistant` message structure.
Messages contain arrays of `text`, `image`, `tool_use`, and `tool_result` blocks. `user` messages include client content and `tool_result`, while `assistant` messages contain AI-generated content and `tool_use`.
## Handling errors with is_error
There are a few different types of errors that can occur when using tools with Claude:
### Tool execution error
If the tool itself throws an error during execution (for example, a network error when fetching weather data), you can return the error message in the `content` along with `"is_error": true`:
JSON
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
"is_error": true
}
]
}
```
Claude will then incorporate this error into its response to the user. For example: "I'm sorry, I was unable to retrieve the current weather because the weather service API is not available. Please try again later."
Write instructive error messages. Instead of generic errors like `"failed"`, include what went wrong and what Claude should try next (for example, `"Rate limit exceeded. Retry after 60 seconds."`). This gives Claude the context it needs to recover or adapt without guessing.
### Invalid tool name
If Claude's attempted use of a tool is invalid (for example, missing required parameters), it usually means that there wasn't enough information for Claude to use the tool correctly. Your best bet during development is to try the request again with more-detailed `description` values in your tool definitions.
However, you can also continue the conversation forward with a `tool_result` that indicates the error, and Claude will try to use the tool again with the missing information filled in:
JSON
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}
```
If a tool request is invalid or missing parameters, Claude will retry 2-3 times with corrections before apologizing to the user.
To eliminate invalid tool calls entirely, use [strict tool use](agents-and-tools-tool-use-strict-tool-use.md) with `strict: true` on your tool definitions. This guarantees that tool inputs will always match your schema exactly, preventing missing parameters and type mismatches.
### Server tool errors
When server tools encounter errors (for example, network issues with Web Search), Claude will transparently handle these errors and attempt to provide an alternative response or explanation to the user. Unlike client tools, you do not need to handle `is_error` results for server tools.
For web search specifically, possible error codes include:
- `too_many_requests`: Rate limit exceeded
- `invalid_input`: Invalid search query parameter
- `max_uses_exceeded`: Maximum web search tool uses exceeded
- `query_too_long`: Query exceeds maximum length
- `unavailable`: An internal error occurred
## Next steps
[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)
Handle responses where Claude calls several tools in a single turn.
[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)
Let the SDK manage the `tool_use` loop, result formatting, and retries for you.
[Define tools](agents-and-tools-tool-use-implement-tool-use.md)
Write schemas and descriptions that steer Claude toward the right tool.
---
## How tool use works - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-how-tool-use-works.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fhow-tool-use-works)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# How tool use works
Copy page
Understand the tool use loop, where tools execute, and when to use tools instead of prose.
Copy page
This page explains the concepts behind tool use: where tools run, how the agentic loop works, and when tool use is the right approach. For hands-on guidance, start with the [Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md) tutorial or the [Define tools](agents-and-tools-tool-use-implement-tool-use.md) guide.
## The tool-use contract
Tool use is a contract between your application and the model. You specify what operations are available and what shape their inputs and outputs take; Claude determines when and how to call them. The model never executes anything on its own. It emits a structured request, your code (or Anthropic's servers) runs the operation, and the result flows back into the conversation.
This contract makes the model behave less like a text generator and more like a function you call. Engineers with classical API experience can integrate tool use the same way they would any other typed interface: define the schema, handle the callback, return a result. The difference is that the caller on the other side is a language model choosing which function to call based on the conversation.
## Where tools run
The primary axis along which tools differ is where the code executes. Every tool falls into one of three buckets, and the bucket determines what your application is responsible for.
### User-defined tools (client-executed)
You write the schema, you execute the code, you return the results. This is the most common case: the vast majority of tool-use traffic is [user-defined tools](agents-and-tools-tool-use-implement-tool-use.md) calling into application-specific logic.
When Claude calls one of your tools, the API response contains a `tool_use` block with the tool name and a JSON object of arguments. Your application extracts those arguments, runs the operation (a database query, an HTTP call, a file write, whatever the tool does), and sends the output back in a `tool_result` block on the next request. Claude never sees your implementation; it only sees the schema you provided and the result you returned.
### Anthropic-schema tools (client-executed)
For a handful of common operations (managing scratchpad memory, running shell commands, editing files, controlling a desktop or a browser), Anthropic publishes the tool schema and your application handles execution. The tools in this category are [`memory`](agents-and-tools-tool-use-memory-tool.md), [`bash`](agents-and-tools-tool-use-bash-tool.md), [`text_editor`](agents-and-tools-tool-use-text-editor-tool.md), [`computer`](agents-and-tools-tool-use-computer-use-tool.md), and [`browser`](agents-and-tools-tool-use-browser-use-tool.md).
The execution model is identical to user-defined tools: the response contains a `tool_use` block, your code runs the operation, and you send back a `tool_result`. The reason to use an Anthropic-schema tool instead of defining your own equivalent is that these schemas are trained-in. Claude has been optimized on thousands of successful trajectories that use these exact tool signatures, so it calls them more reliably and recovers from errors more gracefully than it would with a custom tool that does the same thing. The schema is the interface the model already expects.
### Server-executed tools
For [`web_search`](agents-and-tools-tool-use-web-search-tool.md), [`web_fetch`](agents-and-tools-tool-use-web-fetch-tool.md), [`code_execution`](agents-and-tools-tool-use-code-execution-tool.md), and [`tool_search`](agents-and-tools-tool-use-tool-search-tool.md), Anthropic runs the code. You enable the tool in your request and the server handles everything else. You never construct a `tool_result` block for these tools. When a turn calls only [server tools](agents-and-tools-tool-use-server-tools.md), the server-side loop executes the operation and feeds the output back to the model before the response reaches you, unless the loop stops before it finishes, most often because it pauses.
The response you receive contains `server_tool_use` blocks showing what ran and what came back. In the common case, execution is already complete by the time you see them, and your application's job is to enable the tool and read the final answer rather than to participate in the execution loop; the main exceptions are a paused loop ([`pause_turn`](#the-server-side-loop)) and a turn that also calls a client tool.
## The agentic loop (client tools)
Client-executed tools (both user-defined and Anthropic-schema) require your application to drive a loop. The model can't run your code, so every tool call is a round trip: the model asks, you execute, you report back, the model continues.
The canonical shape is a `while` loop keyed on `stop_reason`:
1. Send a request with your `tools` array and the user message.
2. Claude responds with `stop_reason: "tool_use"` and one or more `tool_use` blocks.
3. Execute each tool. Format the outputs as `tool_result` blocks.
4. Send a new request containing the original messages, the assistant's response, and a user message with the `tool_result` blocks.
5. Repeat from step 2 while `stop_reason` is `"tool_use"`.
In practice this reads as: while `stop_reason == "tool_use"`, execute the tools and continue the conversation. The loop exits on any other stop reason (`"end_turn"`, `"max_tokens"`, `"stop_sequence"`, or `"refusal"`), which means Claude has either produced a final answer or stopped for another reason that your application should handle.
For the mechanics of building requests, handling parallel tool calls, and formatting results, see [Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md).
## The server-side loop
Server-executed tools run their own loop inside Anthropic's infrastructure. A single request from your application might trigger several web searches or code executions before a response comes back. The model searches, reads results, determines whether to search again, and iterates until it has what it needs, all without your application participating.
This internal loop has an iteration limit. If the model is still iterating when it hits the cap, the response comes back with `stop_reason: "pause_turn"` instead of `"end_turn"`. A paused turn means the work isn't finished; re-send the conversation (including the paused response) to let the model continue where it left off. See [Server tools](agents-and-tools-tool-use-server-tools.md) for the continuation pattern.
The loop also hands control back to you before a server tool runs if Claude calls that server tool and a client tool in the same group of parallel tool calls. The response then comes back with `stop_reason: "tool_use"` and a `server_tool_use` block that has no result block yet; the API runs it after you return the client tool results. See [Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md#tool-use) for the exact contract.
## When to use tools (and when not to)
Tool use fits when the task requires something the model can't do from text alone:
- **Actions with side effects.** Sending an email, writing a file, updating a record. The model can describe these actions, but only a tool can perform them.
- **Fresh or external data.** Current prices, today's weather, the contents of a database. Anything outside the training data or specific to your system needs a tool to fetch it.
- **Structured, guaranteed-shape outputs.** When you need a JSON object with specific fields rather than prose that happens to contain the information, a tool schema enforces the shape.
- **Calling into existing systems.** Databases, internal APIs, filesystems. Tool use is the bridge between natural-language requests and the systems that fulfill them.
A clear sign that you should be using tools: if you're writing a regex to extract a decision from model output, that decision should have been a tool call. Parsing free-form text to recover structured intent is a sign the structure belongs in the schema.
Tool use doesn't fit when:
- The model can answer from training alone. Summarization, translation, and general-knowledge questions don't need a tool round trip.
- The interaction is one-shot Q&A with no side effects. If there's nothing to execute, there's nothing for a tool to do.
- Tool-calling latency would dominate a trivial response. Every tool call is at least one extra round trip; for lightweight tasks the overhead can exceed the work.
## Choosing between approaches
| Approach | When to use it | What to expect | Learn more |
|-------------------------------|---------------------------------------------------------------------------|---------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| User-defined client tools | Custom business logic, internal APIs, proprietary data | You handle execution and the agentic loop | [Define tools](agents-and-tools-tool-use-implement-tool-use.md) |
| Anthropic-schema client tools | Standard dev operations (bash, file editing, desktop and browser control) | You handle execution; Claude calls the tool reliably because the schema is trained-in | [Tool reference](agents-and-tools-tool-use-tool-reference.md) |
| Server-executed tools | Web search, code sandbox, web fetch | Anthropic handles execution; you read the results instead of producing them | [Server tools](agents-and-tools-tool-use-server-tools.md) |
## Next steps
[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)
Build an agent step by step from a single tool call to production.
[Define tools](agents-and-tools-tool-use-implement-tool-use.md)
Schema specification, descriptions, and `tool_choice`.
[Tool reference](agents-and-tools-tool-use-tool-reference.md)
Directory of Anthropic-provided tools.
---
## Define tools - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-implement-tool-use.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fdefine-tools)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Define tools
Copy page
Specify tool schemas, write effective descriptions, and control when Claude calls your tools.
Copy page
## Prerequisites
- Familiarity with the [tool use overview](agents-and-tools-tool-use-overview.md)
- A Claude API key and a working SDK or cURL setup
If using Claude with tool use and thinking, see [Thinking](../Guides/build-with-claude-thinking.md) for more information.
## Specifying client tools
Client tools are specified in the `tools` top-level parameter of the API request. Anthropic-schema client tools, such as the bash and text editor tools, are declared by a date-versioned `type`; see each tool's page, linked from the [Tool reference](agents-and-tools-tool-use-tool-reference.md), for the fields it accepts. The computer use and browser use tools are [client toolsets](agents-and-tools-tool-use-tool-reference.md#client-toolsets): a single entry with no `name` that declares a fixed set of member tools. A user-defined tool definition includes:
| Parameter | Description |
|:-----------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `name` | The name of the tool. Must match the regex `^[a-zA-Z0-9_-]{1,128}$`. |
| `description` | A detailed plaintext description of what the tool does, when it should be used, and how it behaves. |
| `input_schema` | A [JSON Schema](https://json-schema.org/) object defining the expected parameters for the tool. |
| `input_examples` | (Optional) An array of example input objects to help Claude understand how to use the tool. See [Providing tool use examples](#providing-tool-use-examples). |
For the full set of optional properties available on any single tool definition, including `cache_control`, `strict`, `defer_loading`, and `allowed_callers`, see the [Tool reference](agents-and-tools-tool-use-tool-reference.md#tool-definition-properties). A client toolset entry accepts `cache_control` and `allowed_callers` on the entry and sets `defer_loading` per member; see [Client toolsets](agents-and-tools-tool-use-tool-reference.md#client-toolsets).
### Example simple tool definition
JSON
```python
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
}
},
"required": ["location"]
}
}
```
This tool, named `get_weather`, expects an input object with a required `location` string and an optional `unit` string that must be either "celsius" or "fahrenheit".
### Tool use system prompt
When you call the Claude API with the `tools` parameter, the API constructs a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt. The constructed prompt is designed to instruct the model to use the specified tool(s) and provide the necessary context for the tool to operate properly:
``` block
In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}
```
### Best practices for tool definitions
To get the best performance out of Claude when using tools, follow these guidelines:
- **Provide extremely detailed descriptions.** This is by far the most important factor in tool performance. Your descriptions should explain every detail about the tool, including:
- What the tool does
- When it should be used (and when it shouldn't)
- What each parameter means and how it affects the tool's behavior
- Any important caveats or limitations, such as what information the tool does not return if the tool name is unclear. The more context you can give Claude about your tools, the better it will be at determining when and how to use them. Aim for at least 3–4 sentences for each tool description, more if the tool is complex.
- **Prioritize descriptions, but consider using `input_examples` for complex tools.** Clear descriptions are most important, but for tools with complex inputs, nested objects, or format-sensitive parameters, you can use the `input_examples` field to provide schema-validated examples. See [Providing tool use examples](#providing-tool-use-examples) for details.
- **Consolidate related operations into fewer tools.** Rather than creating a separate tool for every action (`create_pr`, `review_pr`, `merge_pr`), group them into a single tool with an `action` parameter. Fewer, more capable tools reduce selection ambiguity and make your tool surface easier for Claude to navigate.
- **Use meaningful namespacing in tool names.** When your tools span multiple services or resources, prefix names with the service (for example, `github_list_prs`, `slack_send_message`). This makes tool selection unambiguous as your library grows, and is especially important when using [tool search](agents-and-tools-tool-use-tool-search-tool.md).
- **Design tool responses to return only high-signal information.** Return semantic, stable identifiers (for example, slugs or UUIDs) rather than opaque internal references, and include only the fields Claude needs to reason about its next step. Bloated responses waste context and make it harder for Claude to extract what matters.
- **Ask for an explanation, not reasoning.** If a parameter asks Claude why it is making the call, ask for a short explanation or the supporting evidence. A parameter that asks for the model's thinking or step-by-step reasoning may lead to a `reasoning_extraction` refusal. See [Keep reasoning in thinking blocks](../Guides/build-with-claude-refusals-and-fallback.md#keep-reasoning-in-thinking-blocks).
### Example of a good tool description
JSON
```python
{
"name": "get_stock_price",
"description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
"input_schema": {
"type": "object",
"properties": {
"ticker": {
"type": "string",
"description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
}
},
"required": ["ticker"]
}
}
```
### Example poor tool description
JSON
```python
{
"name": "get_stock_price",
"description": "Gets the stock price for a ticker.",
"input_schema": {
"type": "object",
"properties": {
"ticker": {
"type": "string"
}
},
"required": ["ticker"]
}
}
```
The good description clearly explains what the tool does, when to use it, what data it returns, and what the `ticker` parameter means. The poor description is too brief and leaves Claude with many open questions about the tool's behavior and usage.
For deeper guidance on tool design (consolidation, naming, and response shaping), see [Writing tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents).
## Providing tool use examples
You can provide concrete examples of valid tool inputs to help Claude understand how to use your tools more effectively. This is particularly useful for complex tools with nested objects, optional parameters, or format-sensitive inputs.
### Basic usage
Add an optional `input_examples` field to your tool definition with an array of example input objects. Each example must be valid according to the tool's `input_schema`:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA",
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "The unit of temperature",
},
},
"required": ["location"],
},
"input_examples": [
{"location": "San Francisco, CA", "unit": "fahrenheit"},
{"location": "Tokyo, Japan", "unit": "celsius"},
{
"location": "New York, NY" # 'unit' is optional
},
],
}
],
messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)
print(response)
```
Examples are included in the prompt alongside your tool schema, showing Claude concrete patterns for well-formed tool calls. This helps Claude understand when to include optional parameters, what formats to use, and how to structure complex inputs.
### Requirements and limitations
- **Schema validation** - Each example must be valid according to the tool's `input_schema`. Invalid examples return a 400 error
- **Not supported for server-side tools or client toolsets** - Input examples work on user-defined and Anthropic-schema client tools other than the [computer use](agents-and-tools-tool-use-computer-use-tool.md) and [browser use](agents-and-tools-tool-use-browser-use-tool.md) toolsets, but not on server tools such as web search or code execution
- **Token cost** - Examples add to prompt tokens: ~20–50 tokens for simple examples, ~100–200 tokens for complex nested objects
## Controlling Claude's output
### Forcing tool use
In some cases, you may want Claude to use a specific tool to answer the user's question, even if Claude would otherwise answer directly without calling a tool. You can do this by specifying the tool in the `tool_choice` field of the request.
Not every model and setting supports forced tool use. Where it isn't supported, `tool_choice: {"type": "any"}` and `tool_choice: {"type": "tool", "name": "..."}` fail, while `tool_choice: {"type": "auto"}` (the default) and `tool_choice: {"type": "none"}` still work:
| Model or setting | Restriction | What to use instead |
|--------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Manual [extended thinking](../Guides/build-with-claude-extended-thinking.md) (`thinking: {type: "enabled"}`) | `any` and `tool` are not supported and result in an error | `auto` or `none`. [Adaptive thinking](../Guides/build-with-claude-thinking.md) itself doesn't block forced tool use (models with thinking on by default, such as Claude Opus 5 and Claude Haiku 5.5, accept it, but a forced call skips thinking: the response starts with the tool call and has no `thinking` block); the models in the next row reject forced tool use regardless of thinking settings |
| Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and [Claude Mythos 5.1](../../20-Models/models-mythos-5-1-overview.md) | `any` and `tool` return a [400 error](../Endpoints/errors.md#forced-tool-use-not-supported) | `auto` with [strict tool use](agents-and-tools-tool-use-strict-tool-use.md) to guarantee schema-valid tool inputs, or [structured outputs](../Guides/build-with-claude-structured-outputs.md) when you need a response in a fixed JSON shape. Prompting still influences which tool `auto` picks. `none` is also supported |
On models that support it, the highlighted lines are the only difference from a standard tool use request:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
tools = [
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA",
}
},
"required": ["location"],
},
}
]
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "tool", "name": "get_weather"},
messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)
print(response)
```
When working with the `tool_choice` parameter, there are four possible options:
- `auto` allows Claude to determine whether to call any provided tools or not. This is the default value when `tools` are provided.
- `any` tells Claude that it must use one of the provided tools, but doesn't force a particular tool.
- `tool` forces Claude to always use a particular tool.
- `none` prevents Claude from using any tools. This is the default value when no `tools` are provided.
When using [prompt caching](../Guides/build-with-claude-prompt-caching.md#what-invalidates-the-cache), changes to the `tool_choice` parameter will invalidate cached message blocks. Tool definitions and system prompts remain cached, but message content must be reprocessed.
This diagram illustrates how each option works:
Note that when you have `tool_choice` as `any` or `tool`, the API prefills the assistant message to force a tool to be used. This means that the models will not emit a natural language response or explanation before `tool_use` content blocks, even if explicitly asked to do so.
Testing has shown that this should not reduce performance. If you would like the model to provide natural language context or explanations while still requesting that the model use a specific tool, you can use `{"type": "auto"}` for `tool_choice` (the default) and add explicit instructions in a `user` message. For example: `What's the weather like in London? Use the get_weather tool in your response.`
Forcing a tool also skips thinking on every model that accepts forced tool use: the response starts with the `tool_use` block and has no `thinking` block. To let the model think before it calls the tool, use `auto` with a prompt instruction in the same way.
**Guaranteed tool calls with strict tools**
On models that support forced tool use, combine `tool_choice: {"type": "any"}` with [strict tool use](agents-and-tools-tool-use-strict-tool-use.md) to guarantee both that one of your tools is called and that the tool inputs strictly follow your schema. Set `strict: true` on your tool definitions to enable schema validation.
### Model responses with tools
When using tools, Claude often comments on what it's doing or responds naturally to the user before calling tools.
For example, given the prompt "What's the weather like in San Francisco right now, and what time is it there?", Claude might respond with:
JSON
```python
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll help you check the current weather and time in San Francisco."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "San Francisco, CA" }
}
]
}
```
This natural response style helps users understand what Claude is doing and creates a more conversational interaction. You can guide the style and content of these responses through your system prompts and by providing `` in your prompts.
It's important to note that Claude may use various phrasings and approaches when explaining its actions. Your code should treat these responses like any other assistant-generated text, and not rely on specific formatting conventions.
## Next steps
[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)
Parse tool_use blocks and format tool_result responses.
[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)
Let the SDK handle the agentic loop automatically.
[Tool reference](agents-and-tools-tool-use-tool-reference.md)
Directory of Anthropic-provided tools and optional properties.
---
## Manage tool context - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/manage-tool-context
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-manage-tool-context.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fmanage-tool-context)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tool infrastructure
# Manage tool context
Copy page
Choose between tool search, programmatic tool calling, prompt caching, and context editing to manage context bloat.
Copy page
Tool definitions and accumulated `tool_result` blocks consume your context window. Long-running agents with many tools or many turns can exhaust available context before the task is finished. Four approaches address this at different points in the pipeline.
## The four approaches
Each approach targets a different source of context pressure. Pick the one that matches where your tokens are going.
| Approach | What it reduces | When it fits | Learn more |
|---------------------------|-----------------------------------------|----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
| Tool search | Tool definitions loaded upfront | Large toolsets (20+ tools) where most tools aren't needed every turn | [Tool search tool](agents-and-tools-tool-use-tool-search-tool.md) |
| Programmatic tool calling | `tool_result` roundtrips | Chains of tool calls that can execute as a single script | [Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md) |
| Prompt caching | Token cost of repeated tool definitions | Stable toolsets across many requests | [Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md) |
| Context editing | Old `tool_result` blocks in history | Long conversations where early results are no longer relevant | [Context editing](../Guides/build-with-claude-context-editing.md) |
### Tool search
Tool search keeps tool definitions out of the context window until Claude asks for them. Instead of sending 50 tool schemas upfront, you send a single `tool_search` tool and let Claude discover the rest on demand. This trades a small amount of latency (one extra turn to look up a tool) for a large reduction in baseline context usage.
### Programmatic tool calling
Programmatic tool calling collapses a sequence of tool calls into a single code block that Claude writes and Anthropic's code execution sandbox runs. Rather than five roundtrips of `tool_use` and `tool_result`, Claude emits one script that calls all five functions from within the sandbox. The intermediate results never enter the conversation history.
### Prompt caching
Prompt caching doesn't reduce the number of tokens in context, but it reduces what you pay for them on subsequent requests. If your tool definitions are stable, cache them once and reuse the cached prefix across thousands of requests. This is the right choice when the toolset is large but fixed.
### Context editing
Context editing removes old `tool_result` blocks from the conversation history once they've served their purpose. A long agent loop might produce hundreds of intermediate results that were useful at the time but are now dead weight. Context editing lets you trim them without restarting the conversation.
## Combining approaches
These approaches compose. A long-running agent might use tool search to keep the toolset lean, prompt caching to amortize the cost of the remaining definitions, and context editing to trim stale results as the conversation grows. Each solves a different part of the problem, so there's no conflict in using them together.
A reasonable starting point for a high-volume agent:
1. Enable prompt caching on your tool definitions from day one. Cache writes carry a 25% markup over base input pricing, which pays back on the second request that hits the cache.
2. Add tool search once your toolset grows past roughly 20 tools or your baseline context usage becomes noticeable.
3. Add context editing once individual conversations start running long enough that early results become irrelevant.
4. Consider programmatic tool calling if you notice repetitive chains of small tool calls that could run as a single batch.
## Next steps
[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)
Load tool definitions on demand instead of upfront.
[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)
Collapse tool-call chains into a single executable script.
[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)
Cache tool definitions across requests to cut token costs.
[Context editing](../Guides/build-with-claude-context-editing.md)
Trim stale tool results from long-running conversations.
---
## Memory tool - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-memory-tool.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fmemory-tool)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Memory tool
Copy page
Let Claude store and retrieve information across conversations by implementing the memory tool's file operations in your application.
Copy page
The memory tool lets Claude store and retrieve information across conversations in a directory of memory files. Claude can create, read, update, and delete files that persist between sessions, building up knowledge over time without keeping everything in the context window.
Memory supports just-in-time context retrieval. Rather than loading all relevant information up front, an agent records what it learns in memory files and reads them back on demand. This keeps the active context focused on the current task, which matters for long-running sessions that would otherwise overwhelm the context window. See [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) for the broader pattern.
The memory tool operates client-side: Claude requests file operations, and your application executes them. You control where and how the data is stored through your own infrastructure.
Reach out through the [feedback form](https://forms.gle/YXC2EKGMhjN1c4L88) to share your feedback on this feature.
To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
## Use cases
- Maintain project context across multiple agent sessions
- Apply lessons from past interactions, decisions, and feedback to new tasks
- Build up a knowledge base over time
## How it works
When the memory tool is enabled, Claude automatically checks its memory directory before starting a task. As it works, Claude stores what it learns in files under `/memories` and reads them back in later conversations to continue earlier work.
Because the memory tool is client-side, Claude only requests memory operations. Your application executes each request against storage you control and returns the result in a `tool_result` block (see [Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)). The `/memories` path is a prefix that your handler maps onto real storage, such as a per-user directory or keys in a database. Memory lives entirely in your application. A later conversation continues from the same memory when it sends the same `tools` entry and your handler serves the same store. For security, restrict all memory operations to the `/memories` directory (see [Path traversal protection](#path-traversal-protection)).
### Example: How memory tool calls work
A typical interaction looks like this:
**1. User request:**
``` block
"Help me respond to this customer service ticket."
```
**2. Claude checks the memory directory:**
``` block
"I'll help you respond to the customer service ticket. Let me check my memory for any previous context."
```
Claude calls the memory tool:
```python
{
"type": "tool_use",
"id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
"name": "memory",
"input": {
"command": "view",
"path": "/memories"
}
}
```
**3. Your application returns the directory contents:**
```python
{
"type": "tool_result",
"tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
"content": "Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/refund_policies.xml"
}
```
**4. Claude reads relevant files:**
```python
{
"type": "tool_use",
"id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
"name": "memory",
"input": {
"command": "view",
"path": "/memories/customer_service_guidelines.xml"
}
}
```
**5. Your application returns the file contents:**
```python
{
"type": "tool_result",
"tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
"content": "Here's the content of /memories/customer_service_guidelines.xml with line numbers:\n 1\t\n 2\t\n 3\t- Always address customers by their first name\n 4\t- Use empathetic language\n..."
}
```
**6. Claude uses the memory to help:**
``` block
"Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..."
```
The memory tool is available on all Claude 4 and later models. For the full list of Anthropic-provided tools, see the [Tool reference](agents-and-tools-tool-use-tool-reference.md).
## Getting started
Using the memory tool takes two steps:
1. Add the memory tool to your request. The `tools` entry `{"type": "memory_20250818", "name": "memory"}` is the entire configuration: the `name` must be `memory`, and you don't define an input schema for an Anthropic-provided tool.
2. Implement a client-side handler for each memory command. Your handler must reject paths outside `/memories`, so read [Path traversal protection](#path-traversal-protection) before you write it.
## Basic usage
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=2048,
messages=[
{
"role": "user",
"content": "Help me respond to this customer service ticket.",
}
],
tools=[{"type": "memory_20250818", "name": "memory"}],
)
print(message)
```
## Implement the memory handler
Claude's reply to a request like the previous one ends with a `tool_use` block that requests a memory operation, such as `view /memories`. Your application executes the operation and returns the result in a `tool_result` block, then sends the conversation back so Claude can continue: the standard [tool-use loop](agents-and-tools-tool-use-handle-tool-calls.md).
Four SDKs provide memory tool helpers that handle the tool interface and the loop. Subclass `BetaAbstractMemoryTool` (Python and C#), use `betaMemoryTool` (TypeScript), or implement `BetaMemoryToolHandler` (Java) to back memory with your own storage, such as files on disk, a database, cloud storage, or encrypted files. Python and TypeScript also ship a ready-made local-filesystem implementation, `BetaLocalFilesystemMemoryTool`. The helper and tool-runner surfaces live in your SDK's beta namespace even though the memory tool itself doesn't require a beta header. The Go and Ruby SDKs have no memory helper, so those examples run the tool-use loop themselves, and PHP wraps your handler closure in its generic `BetaRunnableTool`. All three use an in-memory store that you replace with your own storage.
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool
client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Remember that customer Acme Corp prefers email follow-ups.",
}
],
tools=[memory],
)
final_message = runner.until_done()
print(final_message.content)
```
The in-memory stores in the Go, PHP, and Ruby examples keep them self-contained: each one dispatches on the `command` field in the `tool_use` block's `input` and returns the strings described under [Tool commands](#tool-commands). A production handler also needs the [path validation](#path-traversal-protection) these demonstration stores skip. For the SDKs' own complete examples, see:
- Python: [examples/memory/basic.py](https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py)
- TypeScript: [examples/tools-helpers-memory.ts](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/examples/tools-helpers-memory.ts)
- C#: [MemoryToolExample](https://github.com/anthropics/anthropic-sdk-csharp/tree/main/examples/MemoryToolExample)
- Java: [BetaMemoryToolExample.java](https://github.com/anthropics/anthropic-sdk-java/blob/main/anthropic-java-example/src/main/java/com/anthropic/example/BetaMemoryToolExample.java)
## Tool commands
Your client-side implementation must handle the following commands. These specifications describe the recommended behaviors and return strings: Claude reads whatever text your tool result contains, so you can return different strings if your application needs to.
### view
Shows directory contents or file contents with optional line ranges:
```python
{
"command": "view",
"path": "/memories/notes.txt",
"view_range": [1, 10]
}
```
`view_range` is optional and applies to text-file views: `[start_line, end_line]` returns those lines, and `[start_line, -1]` returns everything from `start_line` to the end of the file.
#### Return values
**For directories:** Return a listing that shows files and directories with their sizes:
``` inline-block
Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:
{size}\t{path}
{size}\t{path}/{filename1}
{size}\t{path}/{filename2}
```
- Lists files up to 2 levels deep
- Shows human-readable sizes (for example, `5.5K`, `1.2M`)
- Excludes hidden items (files starting with `.`) and `node_modules`
- Uses a tab character between the size and the path
The first `view` of `/memories` on an empty store is not an error. Where your SDK ships a local-filesystem memory tool, `BetaLocalFilesystemMemoryTool`, it creates the memory root before Claude's first call and returns the listing header followed by a single size-and-path line for the empty directory itself.
**For files:** Return file contents with a header and line numbers:
``` block
Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}
```
Line number formatting:
- **Width:** 6 characters, right-aligned with space padding
- **Separator:** Tab character between line number and content
- **Indexing:** 1-indexed (first line is line 1)
- **Line limit:** Files with more than 999,999 lines should return an error: `"File {path} exceeds maximum line limit of 999,999 lines."`
**Example output:**
``` inline-block
Here's the content of /memories/notes.txt with line numbers:
1 Hello World
2 This is line two
10 Line ten
100 Line one hundred
```
Claude's tool description also says that `view` displays image files (`.jpg`, `.jpeg`, and `.png`) and truncates the text view of files longer than 16,000 characters. Expect `view` calls on image paths and follow-up ranged views of long files.
#### Error handling
- **File or directory does not exist:** `"The path {path} does not exist. Please provide a valid path."`
### create
Creates a new file:
```python
{
"command": "create",
"path": "/memories/notes.txt",
"file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}
```
#### Return values
- **Success:** `"File created successfully at: {path}"`
#### Error handling
- **File already exists:** `"Error: File {path} already exists"`
Claude's tool description says `create` "creates or overwrites" a file, so expect `create` calls on paths that already exist. Returning the error is the reference behavior, and overwriting instead is a valid implementation choice.
### str_replace
Replaces text in a file:
```python
{
"command": "str_replace",
"path": "/memories/preferences.txt",
"old_str": "Favorite color: blue",
"new_str": "Favorite color: green"
}
```
`new_str` is optional for `str_replace`: when it's omitted, `old_str` is deleted without a replacement.
#### Return values
- **Success:** `"The memory file has been edited."` followed by a snippet of the edited file with line numbers
#### Error handling
- **File does not exist:** `"Error: The path {path} does not exist. Please provide a valid path."`
- **Text not found:** `` "No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}." ``
- **Duplicate text:** When `old_str` appears multiple times, return: `` "No replacement was performed. Multiple occurrences of old_str `\{old_str}` in lines: {line_numbers}. Please ensure it is unique" ``
#### Directory handling
If the path is a directory, return a "file does not exist" error.
### insert
Inserts text at a specific line:
```python
{
"command": "insert",
"path": "/memories/todo.txt",
"insert_line": 2,
"insert_text": "- Review memory tool documentation\n"
}
```
`insert_text` is inserted after line `insert_line`, and `0` inserts at the beginning of the file.
#### Return values
- **Success:** `"The file {path} has been edited."`
#### Error handling
- **File does not exist:** `"Error: The path {path} does not exist"`
- **Invalid line number:** `` "Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]" ``
#### Directory handling
If the path is a directory, return a "file does not exist" error.
### delete
Deletes a file or directory:
```python
{
"command": "delete",
"path": "/memories/old_file.txt"
}
```
#### Return values
- **Success:** `"Successfully deleted {path}"`
#### Error handling
- **File or directory does not exist:** `"Error: The path {path} does not exist"`
#### Directory handling
Deletes the directory and all its contents recursively. The tool description tells Claude it cannot delete the `/memories` directory itself, so reject a `delete` whose path is the memory root.
### rename
Renames or moves a file or directory:
```python
{
"command": "rename",
"old_path": "/memories/draft.txt",
"new_path": "/memories/final.txt"
}
```
#### Return values
- **Success:** `"Successfully renamed {old_path} to {new_path}"`
#### Error handling
- **Source does not exist:** `"Error: The path {old_path} does not exist"`
- **Destination already exists:** Return an error (do not overwrite): `"Error: The destination {new_path} already exists"`
#### Directory handling
Renames the directory. The tool description tells Claude it cannot rename the `/memories` directory itself, so reject a `rename` whose `old_path` is the memory root.
## Prompting guidance
When the memory tool is present in your request's `tools`, the API automatically adds this instruction to the system prompt. You don't need to send it yourself:
``` block
IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
- As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.
```
Claude's tool description already tells it to keep the memory directory organized, so you don't need to repeat that instruction. If Claude still creates cluttered memory files, you can reinforce it in your prompt:
```python
Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. You can rename or delete files that are no longer relevant. Do not create new files unless necessary.
```
You can also guide what Claude writes to memory. For example: "Only write down information relevant to \ in your memory system."
## Security considerations
Your application executes every file operation Claude requests, so these safeguards are your responsibility:
### Sensitive information
Claude usually refuses to write sensitive information to memory files. For stronger guarantees, add validation that strips sensitive data before your handler writes the file.
### File storage size
Track memory file sizes and cap how large a file can grow. Consider capping how many characters the `view` command returns, and let Claude page through the rest with `view_range`.
### Memory expiration
Periodically delete memory files that haven't been accessed in a long time.
### Path traversal protection
A malicious path such as `/memories/../../secrets.env` can reach files outside the `/memories` directory. Your implementation must validate every path in every command to prevent directory traversal attacks.
Consider these safeguards:
- Validate that all paths start with `/memories`
- Resolve paths to their canonical form and verify they remain within the memory directory
- Reject paths containing sequences such as `../`, `..\\`, or other traversal patterns
- Watch for URL-encoded traversal sequences (`%2e%2e%2f`)
- Use your language's built-in path security utilities (for example, Python's `pathlib.Path.resolve()` and `relative_to()`)
## Error handling
The memory tool uses similar error-handling patterns to the [text editor tool](agents-and-tools-tool-use-text-editor-tool.md#handle-errors). Each command's error messages are listed under [Tool commands](#tool-commands). To return an error to Claude, set `is_error` to `true` on the tool result and put the message in `content`:
```python
{
"type": "tool_result",
"tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
"content": "Error: The path /memories/notes.txt does not exist",
"is_error": true
}
```
## Context editing integration
The memory tool pairs with context editing to manage long-running conversations. For details, see [Context editing](../Guides/build-with-claude-context-editing.md).
## Using with compaction
The memory tool can also be paired with [compaction](../Guides/build-with-claude-compaction.md), which summarizes older conversation context server-side. Context editing clears specific tool results on the client. Compaction automatically summarizes the whole conversation on the server when the conversation approaches the context window limit.
For long-running agents, consider using both: compaction keeps the active context small without client-side bookkeeping, and memory preserves the information that must survive summarization.
## Multisession software development pattern
For software projects that span multiple agent sessions, set up memory files deliberately instead of writing them ad hoc as work progresses. The following pattern turns memory into a recovery mechanism: each new session resumes from the state the last one recorded.
### How the pattern works
1. **Initializer session:** The first session sets up the memory files before any substantive work begins. This includes a progress log (tracking what has been done and what comes next), a feature checklist (defining the scope of work), and a reference to any startup or initialization script the project needs.
2. **Subsequent sessions:** Each new session opens by reading those memory files. This restores the project state without re-exploring the code base or retracing earlier decisions.
3. **End-of-session update:** Before a session ends, it updates the progress log with what was completed and what remains. This ensures the next session has an accurate starting point.
### Key principle
Work on one feature at a time. Mark a feature complete only after end-to-end verification confirms it works, not when the code is written. This keeps the progress log accurate from session to session.
For a detailed case study of this pattern in practice, including the initializer script, progress file structure, and git-based recovery, see [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents).
## Next steps
[Bash tool](agents-and-tools-tool-use-bash-tool.md)
Execute shell commands in a persistent bash session.
[Context editing](../Guides/build-with-claude-context-editing.md)
Automatically manage conversation context as it grows with context editing.
[Compaction](../Guides/build-with-claude-compaction.md)
Server-side context compaction for managing long conversations that approach context window limits.
[Tool reference](agents-and-tools-tool-use-tool-reference.md)
Directory of Anthropic-provided tools and reference for optional tool definition properties.
---
## Tool use with Claude - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-overview.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Foverview)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Tool use with Claude
Copy page
Connect Claude to external tools and APIs. See where tools execute, when Claude calls them, and which tool fits your task.
Copy page
Tool use (also called function calling) lets Claude call functions that you define or that Anthropic provides. Claude determines when to call a tool based on the user's request and the tool's description. It then returns a structured call that your application executes (client tools) or that Anthropic executes (server tools).
Here's a minimal example using a server tool, the [Web search tool](agents-and-tools-tool-use-web-search-tool.md), which Anthropic executes for you:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[{"type": "web_search_20260209", "name": "web_search"}],
messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)
```
Claude runs the search on Anthropic's infrastructure and returns the cited results in the same response. To have Claude call a function that you define, pass a tool with an `input_schema`, then execute the call when Claude returns a `tool_use` block. [How tool use works](#how-tool-use-works) shows that round trip end to end. Learn more about [defining tools](agents-and-tools-tool-use-implement-tool-use.md) and [handling tool calls](agents-and-tools-tool-use-handle-tool-calls.md).
## How tool use works
Tools differ primarily by where the code executes. **Client tools** (including user-defined tools and tools with Anthropic-defined schemas, such as `bash` and `text_editor`) run in your application. Claude responds with `stop_reason: "tool_use"` and one or more `tool_use` blocks. Your code executes the operation and sends back a `tool_result`. **Server tools** (such as `web_search`, `web_fetch`, `code_execution`, and `tool_search`) run on Anthropic's infrastructure: you see the results directly without handling execution, unless Claude calls the tool in the same group of parallel tool calls as one of your client tools (see [Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md#tool-use)).
Here's that round trip in full for a client tool. The first request defines a `get_weather` tool, and Claude answers the question by calling it: the response carries a `tool_use` block, your code runs the lookup, and a second request sends the result back in a `tool_result` block so Claude can reply with the answer.
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
tools = [
{
"name": "get_weather",
"description": "Get the current weather for a given location.",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and state, e.g. San Francisco, CA",
}
},
"required": ["location"],
},
}
]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]
# Claude replies with a tool_use block naming the tool and its arguments.
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
# Ask for at most one tool call per turn.
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=messages,
)
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")
# Run the tool, then send the result back in a tool_result block.
weather = "15 degrees Celsius, partly cloudy" # your weather lookup goes here
messages += [
{"role": "assistant", "content": response.content},
{
"role": "user",
"content": [
{"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
],
},
]
followup = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=messages,
)
# Claude uses the result to answer the original question.
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)
```
Output
``` block
Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.
```
[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md) covers each step in detail, including result formatting and error signaling; [Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md) covers responses that call several tools at once. To skip writing this round trip yourself, use [Tool Runner](agents-and-tools-tool-use-tool-runner.md): the SDK executes your tools and sends the results back automatically.
For the full conceptual model including the agentic loop and when to choose each approach, see [How tool use works](agents-and-tools-tool-use-how-tool-use-works.md).
To connect to Model Context Protocol (MCP) servers, see the [MCP connector](agents-and-tools-mcp-connector.md). To build your own MCP client, see the Model Context Protocol guide to [building an MCP client](../../06-MCP-Tools/Tutorials/develop-build-client.md).
## When Claude uses tools
With the default `tool_choice` of `{"type": "auto"}`, Claude determines on each turn whether to call a tool or respond directly. It calls a tool when the request maps to that tool's described capability and the answer isn't already in context. It responds directly for stable knowledge, creative tasks, and conversational turns.
This boundary is steerable through your system prompt. If Claude isn't calling tools when you expect, a light instruction such as `"Use the tools to investigate before responding."` increases tool use. A stronger form such as `"Always call a tool first before responding."` pushes further. Conversely, `"Use your judgment about whether to call a tool or respond directly."` keeps triggering behavior conservative.
To require a tool call rather than rely on prompting, set [`tool_choice`](agents-and-tools-tool-use-implement-tool-use.md#forcing-tool-use).
**Guarantee schema conformance with strict tool use**
Add `strict: true` to your custom tool definitions to ensure Claude's tool calls always match your schema exactly. See [Strict tool use](agents-and-tools-tool-use-strict-tool-use.md).
Each server tool's page describes its own trigger boundary in more detail.
### When required parameters are missing
If the user's prompt doesn't include enough information to fill all the required parameters for a tool, Claude Opus is much more likely to recognize that a parameter is missing and ask for it. Claude Sonnet might ask, especially when prompted to think before outputting a tool request. But it might also infer a reasonable value.
For example, given a `get_weather` tool that requires a `location` parameter, if you ask Claude "What's the weather?" without specifying a location, Claude (particularly Claude Sonnet) might guess values you didn't supply:
JSON
```python
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "New York, NY", "unit": "fahrenheit" }
}
```
This behavior is not guaranteed, especially for more ambiguous prompts and for less capable models.
## Choose a tool
For `type` strings, versions, and beta headers, see [Tool reference](agents-and-tools-tool-use-tool-reference.md).
### Your own tools
For tools you define, you write the schema and your application executes each call.
[Define tools](agents-and-tools-tool-use-implement-tool-use.md)
Specify tool schemas, write descriptions, and control when Claude calls your tools.
[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)
Parse `tool_use` blocks, format `tool_result` responses, and handle errors.
### Anthropic-schema client tools
Anthropic publishes the schema and trains Claude on it. Your application still executes each call and returns the `tool_result`.
[Memory tool](agents-and-tools-tool-use-memory-tool.md)
Store and retrieve information across conversations in files you control.
[Bash tool](agents-and-tools-tool-use-bash-tool.md)
Run shell commands in a persistent session that maintains state.
[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)
View and modify text files to debug, fix, and improve code.
[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)
Take screenshots and control the mouse and keyboard in a desktop environment.
[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)
Navigate, read, and interact with webpages in your own browser environment.
### Server tools
Server tools run on Anthropic's infrastructure, with no handler code in your application. See [Server tools](agents-and-tools-tool-use-server-tools.md) for the mechanics they share.
[Web search tool](agents-and-tools-tool-use-web-search-tool.md)
Search the web for information beyond the knowledge cutoff, with cited sources.
[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)
Retrieve the full content of specified web pages and PDF documents.
[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)
Run Python and bash code in a sandboxed container to analyze data and generate files.
[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)
Let a faster executor model consult a higher-intelligence advisor model mid-generation.
[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)
Work with thousands of tools by discovering and loading them on demand.
[MCP connector](agents-and-tools-mcp-connector.md)
Connect to remote MCP servers from the Messages API without a separate MCP client.
[Claude Managed Agents](../Other/managed-agents-overview.md) provides a built-in toolset that Claude uses autonomously within a session. For that toolset and the Managed Agents way to add custom tools, see its [Tools](../Other/managed-agents-tools.md) page.
## Pricing
Tool use requests are priced based on:
1. The total number of input tokens sent to the model (including in the `tools` parameter)
2. The number of output tokens generated
3. For server-side tools, additional usage-based pricing (for example, web search charges per search performed)
Client-side tools are priced the same as any other Claude API request, although server-side tools can incur additional charges based on their specific usage.
The additional tokens from tool use come from:
- The `tools` parameter in API requests (tool names, descriptions, and schemas)
- `tool_use` content blocks in API requests and responses
- `tool_result` content blocks in API requests
When you use `tools`, the API also automatically includes a special system prompt for the model that enables tool use. The number of tool use tokens required for each model is listed in the following table (excluding the additional tokens listed earlier). Note that the table assumes at least 1 tool is provided. If no `tools` are provided, then a tool choice of `none` uses 0 additional system prompt tokens.
[TABLE]
These token counts are added to your normal input and output tokens to calculate the total cost of a request.
See the [Models overview](../../20-Models/about-claude-models-overview.md#latest-models-comparison) table for current per-model prices.
When you send a tool use prompt, like any other API request, the response includes both input and output token counts in the reported `usage` metrics.
Some server tools add usage-based charges on top of tokens: see [Web search tool](agents-and-tools-tool-use-web-search-tool.md#usage-and-pricing) and [Code execution tool](agents-and-tools-tool-use-code-execution-tool.md#usage-and-pricing) for their rates.
## Next steps
[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)
Understand the tool use loop, where tools execute, and when to use tools instead of prose.
[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)
A guided walkthrough from a single tool call to a production-ready agentic loop.
[Tool reference](agents-and-tools-tool-use-tool-reference.md)
Directory of Anthropic-provided tools and reference for optional tool definition properties.
---
## Parallel tool use - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-parallel-tool-use.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fparallel-tool-use)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Parallel tool use
Copy page
Enable, format, and disable parallel tool calls, with message-history guidance and troubleshooting.
Copy page
By default, Claude may call multiple tools in a single response. This page covers how to run those calls, how to format the message history so parallelism keeps working, and how to disable parallel tool use when you need to. For the single-call flow, see [Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md).
## Execution semantics
When Claude calls tools, the response has a `stop_reason` of `tool_use` and can contain several `tool_use` blocks in a single assistant turn. How you run those calls is your decision. The API doesn't prescribe an execution order: you can run the calls concurrently (`Promise.all`, `asyncio.gather`), sequentially in the order they appear, or in any combination that suits your tools.
Choose the strategy based on what your tools do. Independent, read-only operations are usually safe to run in parallel for lower latency. Tools with side effects, shared state, or ordering requirements might be better run sequentially.
Whichever strategy you use, return one `tool_result` for each `tool_use` block, all together in the next user message. Match each result to its call with `tool_use_id`, and put every `tool_result` block before any text content in that message. See [Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md) for the full formatting rules. If you choose not to run a particular call (for example, because you ran the batch sequentially and an earlier call failed), still return a `tool_result` for it with `is_error: true` and a brief explanation.
```python
{
"type": "tool_result",
"tool_use_id": "toolu_02",
"is_error": true,
"content": "Not executed: the preceding write_file call failed."
}
```
The [computer use tool](agents-and-tools-tool-use-computer-use-tool.md#batch-actions) and the [browser use tool](agents-and-tools-tool-use-browser-use-tool.md#batch-actions) are stricter. When Claude returns several of their member tool calls in one turn (a batch action), run them sequentially in the order they appear and stop at the first failure; each tool defines the exact text to return for the calls you skip.
## Test parallel tool calls
**Use the Tool Runner for most applications:** the SDK [Tool Runner](agents-and-tools-tool-use-tool-runner.md) handles responses with multiple tool calls and formats the results for you, so you don't write this handling yourself. Use the manual pattern on this page when you need direct control over how the calls run, such as custom batching, ordering, or error handling.
The following script sends a request that should trigger parallel tool calls, verifies the response contains them, and formats the tool results so parallelism keeps working. Run it with `ANTHROPIC_API_KEY` set in your environment:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = Anthropic()
# Define tools
tools = [
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA",
}
},
"required": ["location"],
},
},
{
"name": "get_time",
"description": "Get the current time in a given timezone",
"input_schema": {
"type": "object",
"properties": {
"timezone": {
"type": "string",
"description": "The timezone, e.g. America/New_York",
}
},
"required": ["timezone"],
},
},
]
# Test conversation with parallel tool calls
messages = [
{
"role": "user",
"content": "What's the weather in SF and NYC, and what time is it there?",
}
]
# Make initial request
print("Requesting parallel tool calls...")
response = client.messages.create(
model="claude-opus-5-5", max_tokens=1024, messages=messages, tools=tools
)
# Check for parallel tool calls
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude made {len(tool_uses)} tool calls")
if len(tool_uses) > 1:
print("✓ Parallel tool calls detected!")
for tool in tool_uses:
print(f" - {tool.name}: {tool.input}")
else:
print("✗ No parallel tool calls detected")
# Simulate tool execution and format results correctly
tool_results = []
for tool_use in tool_uses:
if tool_use.name == "get_weather":
if "San Francisco" in str(tool_use.input):
result = "San Francisco: 68°F, partly cloudy"
else:
result = "New York: 45°F, clear skies"
else: # get_time
if "Los_Angeles" in str(tool_use.input):
result = "2:30 PM PST"
else:
result = "5:30 PM EST"
tool_results.append(
{"type": "tool_result", "tool_use_id": tool_use.id, "content": result}
)
# Continue conversation with tool results
messages.extend(
[
{"role": "assistant", "content": response.content},
{"role": "user", "content": tool_results}, # All results in one message!
]
)
# Get final response
print("\nGetting final response...")
final_response = client.messages.create(
model="claude-opus-5-5", max_tokens=1024, messages=messages, tools=tools
)
final_text = next(
block.text for block in final_response.content if block.type == "text"
)
print(f"\nClaude's response:\n{final_text}")
# Verify formatting
print("\n--- Verification ---")
print(f"✓ Tool results sent in single user message: {len(tool_results)} results")
print("✓ No text before tool results in content array")
print("✓ Conversation formatted correctly for future parallel tool use")
```
The summary lines at the end restate the two formatting rules that keep parallelism working: every tool result returns in a single user message, and no text content appears before the tool results in that message.
## Maximizing parallel tool use
Claude 4 and later models make parallel tool calls by default when a request benefits from multiple tools. For all models, you can increase the likelihood of parallel tool calls with targeted prompting:
### System prompts for parallel tool use
For Claude 4 and later models, add this to your system prompt:
``` block
For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
```
For even stronger parallel tool use (recommended if the default isn't sufficient), use:
```python
For maximum efficiency, whenever you perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. Prioritize calling tools in parallel whenever possible. For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into context at the same time. When running multiple read-only commands like `ls` or `list_dir`, always run all of the commands in parallel. Err on the side of maximizing parallel tool calls rather than running too many tools sequentially.
```
### User message prompting
You can also encourage parallel tool use within specific user messages:
``` block
Instead of:
"What's the weather in Paris? Also check London."
Use:
"Check the weather in Paris and London simultaneously."
Or be explicit:
"Please use parallel tool calls to get the weather for Paris, London, and Tokyo at the same time."
```
**Claude Fable 5.1 in long agent loops**
Claude Fable 5.1 may issue fewer parallel tool calls than earlier models, most noticeably in long agent loops where the next reads are only implied (custom coding agents, bash and text editor harnesses, computer use). Standard function calling is unaffected. For the batching instruction to add and where to put it, see [Batch independent tool calls in agent loops](../../10-Prompting-Guides/build-with-claude-prompt-engineering-prompting-claude-fable-5-1.md#batch-independent-tool-calls-in-agent-loops).
## Disable parallel tool use
Parallel tool use is on by default. To turn it off, set `disable_parallel_tool_use: true` inside the [`tool_choice`](agents-and-tools-tool-use-implement-tool-use.md#forcing-tool-use) object. It is not a top-level request parameter. The effect depends on the `tool_choice` type.
### At most one tool call
When `tool_choice` type is `auto` (the default), setting `disable_parallel_tool_use: true` means Claude calls at most one tool per response. Claude can still answer in plain text without calling any tool. The highlighted lines are the only change from a standard tool use request:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA",
}
},
"required": ["location"],
},
}
],
tool_choice={"type": "auto", "disable_parallel_tool_use": True},
messages=[
{
"role": "user",
"content": "What is the weather in San Francisco and New York?",
}
],
)
print(response.content)
```
### Exactly one tool call
When `tool_choice` type is `any` or `tool`, setting `disable_parallel_tool_use: true` means Claude calls exactly one tool. Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and Claude Mythos 5.1 don't support these `tool_choice` types (see [Forcing tool use](agents-and-tools-tool-use-implement-tool-use.md#forcing-tool-use)). The following example uses `any`. The same field works with `tool`:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = Anthropic()
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
tools=[
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA",
}
},
"required": ["location"],
},
}
],
tool_choice={"type": "any", "disable_parallel_tool_use": True},
messages=[
{
"role": "user",
"content": "What is the weather in San Francisco and New York?",
}
],
)
print(response.content)
```
## Troubleshooting
If Claude isn't making parallel tool calls when expected, check these common issues:
**1. Incorrect tool result formatting**
The most common issue is formatting tool results incorrectly in the conversation history. This "teaches" Claude to avoid parallel calls.
Specifically for parallel tool use:
- **Wrong:** a separate user message for each tool result
- **Correct:** all tool results together in a single user message
```python
// Wrong: separate user messages reduce parallel tool use
[
{"role": "assistant", "content": [tool_use_1, tool_use_2]},
{"role": "user", "content": [tool_result_1]},
{"role": "user", "content": [tool_result_2]} // Separate message
]
// Correct: one user message with all results maintains parallel tool use
[
{"role": "assistant", "content": [tool_use_1, tool_use_2]},
{"role": "user", "content": [tool_result_1, tool_result_2]} // Single message
]
```
See [Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md) for other formatting rules.
**2. Weak prompting**
Default prompting might not be sufficient. Use the stronger system prompt from [Maximizing parallel tool use](#maximizing-parallel-tool-use).
**3. Measuring parallel tool usage**
To verify parallel tool calls are working:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
messages = [] # Message objects returned by client.messages.create across your run
tool_call_messages = [
msg for msg in messages if any(block.type == "tool_use" for block in msg.content)
]
total_tool_calls = sum(
len([block for block in msg.content if block.type == "tool_use"])
for msg in tool_call_messages
)
avg_tools_per_message = (
total_tool_calls / len(tool_call_messages) if tool_call_messages else 0.0
)
print(f"Average tools per message: {avg_tools_per_message}")
# Should be > 1.0 if parallel calls are working
```
**4. Calls in a batch appear to depend on each other**
Execution order is your choice. If your tools have ordering dependencies, running the batch sequentially and stopping on the first failure is a valid strategy (and the required one for the [computer use](agents-and-tools-tool-use-computer-use-tool.md#batch-actions) and [browser use](agents-and-tools-tool-use-browser-use-tool.md#batch-actions) tools): return `is_error: true` for any call you didn't run. If you run in parallel and a call fails because its prerequisite hadn't completed, return `is_error: true` with the natural error message. Claude will reissue the call on the next turn. To reduce dependent calls appearing together, add this to your system prompt: "Only batch tool calls that are independent of each other."
## Next steps
[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)
Use the SDK's Tool Runner abstraction to handle the agentic loop, error wrapping, and type safety automatically.
[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)
Parse tool_use blocks, format tool_result responses, and handle errors with is_error.
[Define tools](agents-and-tools-tool-use-implement-tool-use.md)
Specify tool schemas, write effective descriptions, and control when Claude calls your tools.
---
## Programmatic tool calling - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-programmatic-tool-calling.md
# Programmatic tool calling
Copy page
Let Claude call your tools from code in the code execution container, cutting model round trips and token use in multi-tool workflows.
Copy page
Programmatic tool calling allows Claude to write code that calls your tools programmatically within a [code execution](agents-and-tools-tool-use-code-execution-tool.md) container, rather than requiring round trips through the model for each tool invocation. This reduces latency for multi-tool workflows and decreases token consumption by allowing Claude to filter or process data before it reaches the model's context window. On agentic search benchmarks like [BrowseComp](https://arxiv.org/abs/2504.12516) and [DeepSearchQA](https://github.com/google-deepmind/deepsearchqa), which test multistep web research and complex information retrieval, adding programmatic tool calling on top of basic search tools improved performance by an average of 11% while using 24% fewer input tokens (see [Improved web search with dynamic filtering](https://claude.com/blog/improved-web-search-with-dynamic-filtering)).
Consider checking budget compliance across 20 employees: the traditional approach requires 20 separate model round-trips, pulling thousands of expense line items into the context along the way. With programmatic tool calling, a single script runs all 20 lookups, filters the results, and returns only the employees who exceeded their limits, shrinking what Claude needs to reason over from hundreds of kilobytes down to a handful of lines.
For a deeper look at the inference and context costs that programmatic tool calling addresses, see [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use).
Programmatic tool calling requires the [code execution tool](agents-and-tools-tool-use-code-execution-tool.md) with tool version `code_execution_20260120` or later. To check whether a model supports programmatic tool calling before you send a request, read its `capabilities.code_execution.supported` value from the Models API. [Using the Models API](../../20-Models/about-claude-models-overview.md#using-the-models-api) describes the field.
## Quick start
Here's an example where Claude programmatically queries a database multiple times and aggregates results. Adding `allowed_callers: ["code_execution_20260120"]` to a tool definition is what makes that tool callable from within code execution (see [The `allowed_callers` field](#the-allowed-callers-field)):
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue",
}
],
tools=[
{"type": "code_execution_20260120", "name": "code_execution"},
{
"name": "query_database",
"description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
"input_schema": {
"type": "object",
"properties": {
"sql": {"type": "string", "description": "SQL query to execute"}
},
"required": ["sql"],
},
"allowed_callers": ["code_execution_20260120"],
},
],
)
print(response)
```
The response stops with `stop_reason: "tool_use"`, a `container` ID, and a `tool_use` block for `query_database` whose `caller` field identifies the code execution run that called it. Return the result as shown in [Step 3 of the example workflow](#step-3-provide-tool-result) so the code can finish.
## How programmatic tool calling works
When you configure a tool to be callable from code execution and Claude determines that tool is needed:
1. Claude writes Python code that invokes the tool as a function, potentially including multiple tool calls and pre/post-processing logic
2. Claude runs this code in a sandboxed container through code execution
3. When a tool function is called, code execution pauses and the API returns a `tool_use` block
4. You provide the tool result, and code execution continues (intermediate results are not loaded into Claude's context window)
5. Once all code execution completes, Claude receives the final output and continues working on the task
This approach is particularly useful for:
- **Large data processing:** Filter or aggregate tool results before they reach Claude's context
- **Multistep workflows:** Save tokens and latency by calling tools serially or in a loop without sampling Claude in-between tool calls
- **Conditional logic:** Make decisions based on intermediate tool results
Tools that allow a code execution caller are exposed to Claude's code as async Python functions, so Claude can run them in parallel with `asyncio.gather`. Each function takes a single dict of arguments and returns a string: the text of the `tool_result` you send back. Claude's code awaits these functions with top-level `await` and parses results that it needs as structured data, for example `rows = json.loads(await query_database({"sql": ""}))`.
## Core concepts
### The `allowed_callers` field
The `allowed_callers` field specifies which contexts can invoke a tool:
```python
{
"name": "query_database",
"description": "Execute a SQL query against the database",
"input_schema": {
// ...
},
"allowed_callers": ["code_execution_20260120"]
}
```
**Possible values:**
- `["direct"]` - Claude is guided to call this tool directly (default if omitted)
- `["code_execution_20260120"]` - Claude is guided to call this tool only from within code execution
- `["direct", "code_execution_20260120"]` - Claude may call this tool directly or from within code execution
Both `"code_execution_20260120"` and `"code_execution_20260521"` are accepted in `allowed_callers` and are interchangeable: a request using either code-execution tool version satisfies tools that list either caller. Response blocks always tag the caller as `code_execution_20260120` regardless of which version the request declared.
Choose either `["direct"]` or `["code_execution_20260120"]` for each tool rather than enabling both, as this provides clearer guidance to Claude for how best to use the tool.
`allowed_callers` controls how the tool is presented to Claude and is validated against `tool_choice`, but it is not a hard API-level block on direct invocation. Claude is strongly guided to respect it, but your client should still be prepared to handle a direct `tool_use` for any tool it defines. Do not rely on `allowed_callers` as a security boundary.
### The `caller` field in responses
Every tool use block includes a `caller` field indicating how it was invoked:
**Direct invocation (traditional tool use):**
```python
{
"type": "tool_use",
"id": "toolu_abc123",
"name": "query_database",
"input": { "sql": "" },
"caller": { "type": "direct" }
}
```
**Programmatic invocation:**
```python
{
"type": "tool_use",
"id": "toolu_xyz789",
"name": "query_database",
"input": { "sql": "" },
"caller": {
"type": "code_execution_20260120",
"tool_id": "srvtoolu_abc123"
}
}
```
The `tool_id` is the `id` of the code execution `server_tool_use` block that made the call, so you can match each programmatic `tool_use` to the code execution run that produced it.
### Container lifecycle
Programmatic tool calling uses the same containers as code execution:
- **Container creation:** A new container is created for each request unless you reuse an existing one
- **Container ID:** Returned in responses in the `container` field, along with an `expires_at` timestamp
- **Reuse:** Pass the container ID back on the next request to keep state. While a programmatic tool call is waiting for your result, the container ID is required on that request, not optional: the API rejects the request without it.
- **Expiration:** `expires_at` tells you how long the container has left. Idle containers are currently reclaimed after about 5 minutes, and no container can be reused more than 30 days after it was created.
While Claude's code is waiting for a programmatic tool result, the pending call times out after about 4 minutes and raises a `TimeoutError` inside the code. Return each tool result well before the `expires_at` timestamp on the paused response. See [Container expiration during tool call](#container-expiration-during-tool-call).
## Example workflow
Here's how a complete programmatic tool calling flow works:
### Step 1: Initial request
Send a request with code execution and a tool that allows programmatic calling. To enable programmatic calling, add the `allowed_callers` field to your tool definition.
Provide detailed descriptions of your tool's output format in the tool description. If you specify that the tool returns JSON, Claude attempts to deserialize and process the result in code. The more detail you provide about the output schema, the better Claude can handle the response programmatically.
The request shape is identical to the [Quick start](#quick-start) example: include `code_execution` in your tools list, add `allowed_callers: ["code_execution_20260120"]` to any tool you want Claude to invoke from code, and send your user message. The remaining steps in this workflow use the user message `"Query customer purchase history from the last quarter and identify our top 5 customers by revenue"`.
### Step 2: API response with tool call
Claude writes code that calls your tool. The API pauses and returns:
Output
```python
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll query the purchase history and analyze the results."
},
{
"type": "server_tool_use",
"id": "srvtoolu_abc123",
"name": "code_execution",
"input": {
"code": "import json\n\nrows = json.loads(await query_database({'sql': ''}))\ntop_customers = sorted(rows, key=lambda x: x['revenue'], reverse=True)[:5]\nprint(f'Top 5 customers: {top_customers}')"
}
},
{
"type": "tool_use",
"id": "toolu_def456",
"name": "query_database",
"input": { "sql": "" },
"caller": {
"type": "code_execution_20260120",
"tool_id": "srvtoolu_abc123"
}
}
],
"container": {
"id": "container_xyz789",
"expires_at": "2026-01-20T14:30:00Z"
},
"stop_reason": "tool_use"
}
```
### Step 3: Provide tool result
Send the full conversation history plus your tool result. Three details matter on this request:
- The user message that carries your result can contain only `tool_result` blocks. See [Message formatting restrictions](#message-formatting-restrictions).
- Pass the `container` ID from the paused response. The API rejects a continuation that has pending programmatic tool calls but no container ID.
- Send the same `tools` array as the original request. The code execution tool must still be present for the paused code to resume, and the tools you send on this request are the definitions Claude and the running code can use for the rest of the turn.
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
container="container_xyz789", # Reuse the container
messages=[
{
"role": "user",
"content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue",
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll query the purchase history and analyze the results.",
},
{
"type": "server_tool_use",
"id": "srvtoolu_abc123",
"name": "code_execution",
"input": {"code": "..."},
},
{
"type": "tool_use",
"id": "toolu_def456",
"name": "query_database",
"input": {"sql": ""},
"caller": {
"type": "code_execution_20260120",
"tool_id": "srvtoolu_abc123",
},
},
],
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_def456",
"content": '[{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...]',
}
],
},
],
# Same tools array as the original request
tools=[
{"type": "code_execution_20260120", "name": "code_execution"},
{
"name": "query_database",
"description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
"input_schema": {
"type": "object",
"properties": {
"sql": {"type": "string", "description": "SQL query to execute"}
},
"required": ["sql"],
},
"allowed_callers": ["code_execution_20260120"],
},
],
)
print(response)
```
### Step 4: Next tool call or completion
The code picks up where it paused and processes your result. Each continuation response either pauses again with more programmatic `tool_use` blocks, or completes the code execution and lets Claude continue the turn (Step 5). Check `stop_reason` and each `tool_use` block's `caller` to tell the two apart: a response that pauses for you has `stop_reason: "tool_use"` and a `tool_use` block whose `caller` names a code execution version, and you repeat Step 3 with a `tool_result` for every pending programmatic call in one user message.
### Step 5: Final response
Once the code execution completes, Claude provides the final response:
Output
```python
{
"content": [
{
"type": "code_execution_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "code_execution_result",
"stdout": "Top 5 customers: [{'customer_id': 'C1', 'revenue': 45000}, {'customer_id': 'C2', 'revenue': 38000}, {'customer_id': 'C5', 'revenue': 32000}, {'customer_id': 'C8', 'revenue': 28500}, {'customer_id': 'C3', 'revenue': 24000}]",
"stderr": "",
"return_code": 0,
"content": []
}
},
{
"type": "text",
"text": "I've analyzed the purchase history from last quarter. Your top 5 customers generated $167,500 in total revenue, with Customer C1 leading at $45,000."
}
],
"stop_reason": "end_turn"
}
```
## Advanced patterns
### Batch processing with loops
Claude can write code that processes multiple items efficiently:
```python
regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
rows = json.loads(await query_database({"sql": f""}))
results[region] = sum(row["revenue"] for row in rows)
# Process results programmatically
top_region = max(results.items(), key=lambda x: x[1])
print(f"Top region: {top_region[0]} with ${top_region[1]:,} in revenue")
```
This pattern:
- Reduces model round-trips from N (one per region) to 1
- Processes large result sets programmatically before returning to Claude
- Saves tokens by only returning aggregated conclusions instead of raw data
### Early termination
Claude can stop processing as soon as success criteria are met:
```python
endpoints = ["us-east", "eu-west", "apac"]
for endpoint in endpoints:
status = await check_health({"endpoint": endpoint})
if status == "healthy":
print(f"Found healthy endpoint: {endpoint}")
break # Stop early, don't check remaining
```
### Conditional tool selection
```python
path = "/tmp/example.txt"
file_info = json.loads(await get_file_info({"path": path}))
if file_info["size"] < 10000:
content = await read_full_file({"path": path})
else:
content = await read_file_summary({"path": path})
print(content)
```
### Data filtering
```python
server_id = "srv-01"
log_text = await fetch_logs({"server_id": server_id})
errors = [line for line in log_text.splitlines() if "ERROR" in line]
print(f"Found {len(errors)} errors")
for error in errors[-10:]: # Only return last 10 errors
print(error)
```
## Response format
### Programmatic tool call
When code execution calls a tool:
```python
{
"type": "tool_use",
"id": "toolu_abc123",
"name": "query_database",
"input": { "sql": "" },
"caller": {
"type": "code_execution_20260120",
"tool_id": "srvtoolu_xyz789"
}
}
```
### Tool result handling
Your tool result is passed back to the running code:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_abc123",
"content": "[{\"customer_id\": \"C1\", \"revenue\": 45000, \"orders\": 23}, {\"customer_id\": \"C2\", \"revenue\": 38000, \"orders\": 18}, ...]"
}
]
}
```
### Code execution completion
When all tool calls are satisfied and code completes:
```python
{
"type": "code_execution_tool_result",
"tool_use_id": "srvtoolu_xyz789",
"content": {
"type": "code_execution_result",
"stdout": "Analysis complete. Top 5 customers identified from 847 total records.",
"stderr": "",
"return_code": 0,
"content": []
}
}
```
## Error handling
### Common errors
| Error | Where it appears | Description | Solution |
|--------------------------------------------|------------------------------------------------------------------------------|--------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
| `invalid_tool_input` | `error_code` on the `code_execution_tool_result` error block in the response | Invalid parameters were passed to the code execution tool | See the [code execution tool errors](agents-and-tools-tool-use-code-execution-tool.md#errors) |
| `invalid_request_error` (on `tool_choice`) | HTTP 400 error response | `tool_choice` names a tool whose `allowed_callers` does not include `"direct"` | Either add `"direct"` to that tool's `allowed_callers`, or remove the tool from `tool_choice` and let Claude invoke it from code |
### Container expiration during tool call
If your tool result doesn't arrive within about 4 minutes, the pending call raises a `TimeoutError` inside Claude's running code. Claude sees the error in `stderr` and typically retries the call:
```python
{
"type": "code_execution_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "code_execution_result",
"stdout": "",
"stderr": "TimeoutError: Calling tool ['query_database'] timed out (no response after 270s).",
"return_code": 0,
"content": []
}
}
```
To prevent timeouts:
- Monitor the `expires_at` field in responses
- Implement timeouts for your tool execution
- Consider breaking long operations into smaller chunks
### Tool execution errors
If your tool returns an error:
```python
{
"type": "tool_result",
"tool_use_id": "toolu_abc123",
"content": "Error: Query timeout - table lock exceeded 30 seconds"
}
```
Claude's code receives this error and can handle it appropriately.
## Constraints and limitations
### Feature incompatibilities
- **Structured outputs:** Tools with `strict: true` are not supported with programmatic calling
- **Tool choice:** You cannot force programmatic calling of a specific tool through `tool_choice`
- **Parallel tool use:** `disable_parallel_tool_use: true` is not supported with programmatic calling
### Input schema limitations
Custom tools whose `input_schema` contains a recursive `$ref` (a reference cycle, such as a schema that refers to itself) cannot be enabled for programmatic calling. Including a code execution tool version in `allowed_callers` for such a tool causes the request to fail with a `400 invalid_request_error` whose message contains `Circular $ref detected`. The same schema is accepted for direct tool calling.
To work around this, do one of the following:
- Keep the tool direct-only by omitting `allowed_callers` (or setting it to `["direct"]`). Other tools in the same request can still use programmatic calling.
- Remove the cycle from the schema. For example, unroll the recursion to a fixed depth and describe any deeper nesting in the `description` of the innermost level, or replace the recursive property with a plain `{"type": "object"}` whose `description` explains the expected shape.
### Tool restrictions
The following tools cannot be called programmatically:
- Tools provided by an [MCP connector](agents-and-tools-mcp-connector.md)
- The [computer use](agents-and-tools-tool-use-computer-use-tool.md) and [browser use](agents-and-tools-tool-use-browser-use-tool.md) toolsets (`computer_toolset_20260801` and `browser_toolset_20260801`), whose `allowed_callers` field accepts only `"direct"`
### Message formatting restrictions
When responding to programmatic tool calls, there are strict formatting requirements:
**Tool result only responses:** If there are pending programmatic tool calls waiting for results, your response message must contain **only** `tool_result` blocks. You cannot include any text content, even after the tool results.
Invalid - Cannot include text when responding to programmatic tool calls:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01",
"content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
},
{ "type": "text", "text": "What should I do next?" }
]
}
```
Valid - Only tool results when responding to programmatic tool calls:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01",
"content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
}
]
}
```
This restriction only applies when responding to programmatic (code execution) tool calls. For regular client-side tool calls, you can include text content after tool results.
**Text-only tool result content:** The `content` of each `tool_result` that answers a programmatic call must be a string or `text` blocks. Image, document, and other content block types are rejected.
### Rate limits
Programmatic tool calls are subject to the same rate limits as regular tool calls. Each tool call from code execution counts as a separate invocation.
### Validate tool results before use
When implementing user-defined tools that will be called programmatically:
- **Tool results are returned as strings:** They can contain any content, including code snippets or executable commands that may be processed by the execution environment.
- **Validate external tool results:** If your tool returns data from external sources or accepts user input, be aware of code injection risks if the output will be interpreted or executed as code.
## Token efficiency
Programmatic tool calling reduces token consumption in three ways:
- **Tool results from programmatic calls are not added to Claude's context** - only the final code output is
- **Intermediate processing happens in code** - filtering, aggregation, and other transformations don't consume model tokens
- **Multiple tool calls in one code execution** - reduces overhead compared to separate model turns
For example, calling 10 tools directly uses ~10x the tokens of calling them programmatically and returning a summary.
In Anthropic's internal evaluations on a production Claude model:
- On a 75-tool project-management agent benchmark, enabling programmatic tool calling reduced billed input tokens by roughly 38% with no change in task accuracy.
- On [τ²-bench](https://arxiv.org/abs/2506.07982) (airline, retail, and telecom domains), where each turn makes one or two sequential tool calls, programmatic tool calling left scores unchanged and cost roughly 8% more. Sequential single-call workflows do not benefit.
- Across production API traffic, requests whose `tools` array contains 10 to 49 tool definitions see typical token savings of 20% to 40% with programmatic tool calling enabled.
Actual savings vary with workload shape. See [When to use programmatic calling](#when-to-use-programmatic-calling).
## Usage and pricing
Programmatic tool calling uses the same pricing as code execution. See the [code execution pricing](agents-and-tools-tool-use-code-execution-tool.md#usage-and-pricing) for details.
Token counting for programmatic tool calls: Tool results from programmatic invocations do not count toward your input/output token usage. Only the final code execution result and Claude's response count.
## Best practices
### Tool design
- **Provide detailed output descriptions:** Because Claude deserializes tool results in code, document the format (JSON structure and field types)
- **Return structured data:** JSON or other machine-readable formats work best for programmatic processing
- **Keep responses concise:** Return only necessary data to minimize processing overhead
### When to use programmatic calling
Programmatic tool calling trades a small fixed overhead (container startup, script generation) for large savings on tool-result tokens and model round-trips. Whether that trade pays off depends on workload shape.
**Strong fit:**
- Fan-out or parallel operations across many items (for example, checking 50 endpoints or looking up 20 records)
- Large tool results that can be filtered, aggregated, or summarized before reaching Claude's context
- Agentic search and retrieval, where iterative querying and result filtering dominate the workflow
**Weak fit:**
- Strictly sequential workflows where each call depends on Claude reasoning over the previous result, because the script cannot skip the model round-trip in that case
- A small number of tool calls with small responses, especially on the first turn of a conversation, where container and script overhead can exceed the savings
- Tools that require immediate user feedback between calls
If you are unsure, measure billed input tokens with and without `allowed_callers` on a representative sample of your traffic before enabling it broadly.
### Performance optimization
- **Reuse containers** when making multiple related requests to maintain state
- **Batch similar operations** in a single code execution when possible
## Troubleshooting
### Common issues
**`invalid_request_error` when setting `tool_choice`**
- `tool_choice` cannot name a tool whose `allowed_callers` omits `"direct"`. Either add `"direct"` to that tool's `allowed_callers`, or remove the tool from `tool_choice` and let Claude invoke it from code.
**Container expiration**
- Respond to each programmatic tool call well before the paused response's `expires_at` timestamp. Claude's code stops waiting for a result after about 4 minutes, and idle containers are currently reclaimed after about 5 minutes.
- Consider implementing faster tool execution
**Tool result not parsed correctly**
- Ensure your tool returns string data that Claude can deserialize
- Provide clear output format documentation in your tool description
### Debugging tips
1. **Log all tool calls and results** to track the flow
2. **Check the `caller` field** to confirm programmatic invocation
3. **Monitor container IDs** to ensure proper reuse
4. **Test tools independently** before enabling programmatic calling
## Why programmatic tool calling works
Claude is trained on large amounts of code, so presenting tools as callable Python functions lets it use that strength:
- **Tool composition:** Chained calls, loops, and conditionals are ordinary Python control flow instead of a series of model round trips
- **Result processing:** Claude's code filters and aggregates large tool outputs, or writes them to files, and only the final output enters the context window
- **Latency:** The model is not re-sampled between the tool calls inside one code execution
## Alternative implementations
Programmatic tool calling is a generalizable pattern that can also be implemented on your own infrastructure. Here's how the approaches compare:
### Client-side direct execution
Provide Claude with a code execution tool and describe what functions are available in that environment. When Claude invokes the tool with code, your application executes it locally where those functions are defined.
**Advantages:**
- Minimal re-architecting of your application
- Full control over the environment and instructions
**Disadvantages:**
- Executes untrusted code outside of a sandbox
- Tool invocations can be vectors for code injection
**Use when:** Your application can safely execute arbitrary code, you want the smallest implementation, and Anthropic's managed offering doesn't fit your needs.
### Self-managed sandboxed execution
Same approach from Claude's perspective, but code runs in a sandboxed container with security restrictions (for example, no network egress). If your tools require external resources, you'll need a protocol for executing tool calls outside the sandbox.
**Advantages:**
- Safe programmatic tool calling on your own infrastructure
- Full control over the execution environment
**Disadvantages:**
- Complex to build and maintain
- Requires managing both infrastructure and inter-process communication
**Use when:** Security is critical and Anthropic's managed solution doesn't fit your requirements.
### Anthropic-managed execution
Anthropic's programmatic tool calling is a managed version of sandboxed execution with an opinionated Python environment tuned for Claude. Anthropic handles container management, code execution, and secure tool invocation communication.
**Advantages:**
- Safe and secure by default
- Enabled with a tool definition, with no infrastructure to run
- Environment and instructions optimized for Claude
Consider using Anthropic's managed solution if you're using the Claude API, [Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md), or [Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md). On Microsoft Foundry, programmatic tool calling requires a [Hosted on Anthropic deployment](../Guides/build-with-claude-claude-in-microsoft-foundry.md#additional-features-not-supported-when-hosted-on-azure).
## Data retention
Programmatic tool calling is built on the code execution infrastructure and uses the same sandbox containers. Container data, including execution artifacts and outputs, is retained for up to 30 days.
For ZDR eligibility across all features, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
## Next steps
[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Stream tool inputs without server-side JSON buffering for latency-sensitive applications.
[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)
Run Python and bash code in a sandboxed container to analyze data, generate files, and iterate on solutions.
[Tool use with Claude](agents-and-tools-tool-use-overview.md)
Connect Claude to external tools and APIs. See where tools execute, when Claude calls them, and which tool fits your task.
[Define tools](agents-and-tools-tool-use-implement-tool-use.md)
Specify tool schemas, write effective descriptions, and control when Claude calls your tools.
## Compatibility
Supported models
- Fable 5 and 5.1
- Mythos 5 and 5.1
- Opus 4.5, 4.6, 4.7, 4.8, 5, and 5.5
- Sonnet 4.5, 4.6, 5, and 5.5
- Haiku 5.5
Supported platforms
- Claude API
- Claude Platform on AWS
- Microsoft Foundry^([1](#compat-fn-1))
1. On [Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md), programmatic tool calling requires a [Hosted on Anthropic deployment](../Guides/build-with-claude-claude-in-microsoft-foundry.md#additional-features-not-supported-when-hosted-on-azure). [↩](#compat-fnref-1)
- Programmatic tool calling requires the code execution tool with the `code_execution_20260120` or later [tool version](agents-and-tools-tool-use-code-execution-tool.md#tool-versions).
- Claude Haiku 4.5 accepts the `code_execution_20260120` and later tool versions but doesn't support programmatic tool calling.
---
## Server tools - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-server-tools.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fserver-tools)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Server tools
Copy page
Work with Anthropic-executed tools: server_tool_use blocks, pause_turn continuation, mixed server and client tool turns, and domain filtering.
Copy page
Server-executed tools share these mechanics: the `server_tool_use` block, `pause_turn` continuation, turns that mix server and client tools, Zero Data Retention (ZDR) eligibility, and domain filtering. For individual tools, see the [tool reference](agents-and-tools-tool-use-tool-reference.md).
## The server_tool_use block
The `server_tool_use` block appears in Claude's response when a server-executed tool runs. Its `id` field uses the `srvtoolu_` prefix to distinguish it from client tool calls:
```python
{
"type": "server_tool_use",
"id": "srvtoolu_01A2B3C4D5E6F7G8H9",
"name": "web_search",
"input": { "query": "latest quantum computing breakthroughs" }
}
```
The API executes the tool internally. You see the call and its result in the response, but you don't handle execution. Unlike client `tool_use` blocks, you don't need to respond with a `tool_result`. The tool's result block (for example, `web_search_tool_result` for web search) follows the `server_tool_use` block in the same assistant turn, paired by `tool_use_id`. If Claude calls one of your client tools at the same time, the `server_tool_use` block appears without its result, and the response ends with `stop_reason: "tool_use"`. The API runs the tool when you return the client `tool_result` blocks in your next request.
## The server-side loop and pause_turn
When using server tools such as web search, the API executes tool calls in a server-side agentic loop. On a long-running turn, the API might pause that loop and return a `pause_turn` stop reason.
Here's how to handle the `pause_turn` stop reason:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
# Initial request with web search
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
}
],
tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
)
# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
# Continue the conversation with the paused content
messages = [
{
"role": "user",
"content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
},
{"role": "assistant", "content": response.content},
]
# Send the continuation request
continuation = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=messages,
tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
)
print(continuation)
else:
print(response)
```
When handling `pause_turn`:
- **Continue the conversation:** Pass the paused response back as-is in a subsequent request to let Claude continue its turn.
- **Preserve tool state:** Include the same tools in the continuation request. A paused turn can end with a `server_tool_use` block whose tool has not run yet, and the API returns a validation error if that tool is missing from the continuation.
- **Repeat as needed:** A continued turn can pause again. Check `stop_reason` on each response and continue until you get a different stop reason, capping the number of continuations as you would any retry loop.
For the other `stop_reason` values and general handling patterns, see [Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md).
## Mixing server tools and client tools in one turn
Claude can call a server tool and a client tool in the same group of parallel tool calls, for example, `web_fetch` together with a user-defined tool. A client tool is any tool that your code executes and that produces a `tool_use` block, whether it is user-defined or an Anthropic-schema client tool such as the [Bash tool](agents-and-tools-tool-use-bash-tool.md). When that happens, the API does not run the server tool. It returns immediately so that you can run the client tool first:
- `stop_reason` is `"tool_use"`, not `"pause_turn"`.
- `content` contains the `server_tool_use` block and the client `tool_use` block, but no result block for the server tool: that call is not finished.
- There is no other marker. Detect the state by looking for a `server_tool_use` block whose `id` has no matching result block in the response. An `mcp_tool_use` block from the [MCP connector](agents-and-tools-mcp-connector.md) behaves the same way. Server tool calls that already have their result block in the same response are complete and need nothing from you.
With [programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md), the same response shape means something different. The client `tool_use` block comes from code that is running in the `code_execution` tool rather than from Claude directly, and its `caller` field names the `code_execution` block that called it. That code has already started: it is paused waiting for your `tool_result` blocks, and sending them resumes the execution instead of starting a deferred tool. The `code_execution` block's own result block arrives once the code finishes, which can take more than one round of tool results. The follow-up user message itself is the same in both cases; with programmatic tool calling, also pass back the `id` from the response's `container` field, as that page shows.
```python
{
"stop_reason": "tool_use",
"content": [
{
"type": "text",
"text": "I'll fetch the article and check your system at the same time."
},
{
"type": "server_tool_use",
"id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
"name": "web_fetch",
"input": { "url": "https://example.com/article" }
},
{
"type": "tool_use",
"id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
"name": "run_command",
"input": { "command": "uname -a" }
}
]
}
```
To continue the turn, run the client tools and send a user message whose content is only the `tool_result` blocks, one for each `tool_use` block in that response. Keep the same `tools` array: a resume request that no longer defines the waiting server tool fails with a 400 whose message ends `` but no `web_fetch` tool was provided ``.
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
"content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
}
]
}
```
The API attaches your results to the still-open assistant turn, runs the deferred server tool (for paused code execution, resumes it), and then lets Claude continue. For a server tool Claude called directly, the next response begins with the result block that answers the previous response's `server_tool_use` `id`, followed by the newly generated content and a fresh `stop_reason`:
```python
{
"stop_reason": "end_turn",
"content": [
{
"type": "web_fetch_tool_result",
"tool_use_id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
"content": {
"type": "web_fetch_result",
"url": "https://example.com/article",
"content": {
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "Full text content of the article..."
}
}
}
},
{
"type": "text",
"text": "The article argues that... and your machine is running Linux..."
}
]
}
```
A `server_tool_use` block and its result block pair up by `tool_use_id`, not by position: in this flow they arrive in two different responses, and the `server_tool_use` block is not repeated in the second one. On later requests, keep the whole exchange in your `messages` array in order: the first response as an `assistant` message, the `tool_result` user message, and then the next response as another `assistant` message, the same way you accumulate any other tool-use exchange.
The follow-up user message must contain nothing except `tool_result` blocks. A block added after the results, such as text, tells the API that the assistant turn is over. For a server tool Claude called directly, that leaves the turn with an unresolved server tool call, and the request fails with a 400 `invalid_request_error`:
``` block
`web_fetch` tool use with id `srvtoolu_01HxbWnMRmbWyMfUtJKC45rA` was found without a corresponding `web_fetch_tool_result` block
```
A follow-up that puts content before the results, answers only some of the client `tool_use` IDs, or contains no `tool_result` blocks at all fails earlier, with the client tool error described in [Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md):
``` block
`tool_use` ids were found without `tool_result` blocks immediately after: toolu_01PjgRJLbXrXEMZwDNYLnBqk. Each `tool_use` block must have a corresponding `tool_result` block in the next message.
```
To give Claude more input, send it as a separate user message after the turn completes.
**How this differs from `pause_turn`:** A [`pause_turn` response](#the-server-side-loop-and-pause-turn) can also end with a `server_tool_use` block that has not run, but it never leaves a client `tool_use` block waiting on you, so you continue it by re-sending the assistant content as-is. A response that leaves a client `tool_use` block waiting on you never has a `stop_reason` of `pause_turn`: when Claude stops to call your tools, `stop_reason` is `tool_use`, and you continue it by sending the client `tool_result` blocks rather than by re-sending the response. In both cases the API runs the pending server tool at the start of the next request.
The following example enables web fetch together with a user-defined `run_command` tool and handles the mixed response:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
tools = [
{"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5},
{
"name": "run_command",
"description": "Run a shell command on this computer and return its output.",
"input_schema": {
"type": "object",
"properties": {
"command": {"type": "string", "description": "The command to run"}
},
"required": ["command"],
},
},
]
messages = [
{
"role": "user",
"content": "Summarize https://example.com/article and run uname -a to tell me what system this is on.",
}
]
response = client.messages.create(
model="claude-opus-5-5", max_tokens=1024, tools=tools, messages=messages
)
tool_results = [
{
"type": "tool_result",
"tool_use_id": block.id,
# Run your tool here. This example returns a fixed string.
"content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux",
}
for block in response.content
if block.type == "tool_use"
]
if response.stop_reason == "tool_use" and tool_results:
# A server_tool_use block with no result block in this response is not finished; its result arrives in a later response.
# Send back only the client tool_result blocks, with the same tools.
continuation = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=tools,
messages=[
*messages,
{"role": "assistant", "content": response.content},
{"role": "user", "content": tool_results},
],
)
# If a web_fetch was deferred, it runs on this request and its
# web_fetch_tool_result is the first block of continuation.content.
print(continuation)
else:
print(response)
```
This code is also correct when Claude does not mix the two kinds of call. A turn with only client `tool_use` blocks takes the same continuation path, and a turn with only server tool calls needs no client `tool_result` blocks from you: its result blocks are normally already present, and one that comes back suspended, such as a [`pause_turn` response](#the-server-side-loop-and-pause-turn), is re-sent as-is instead.
## ZDR and allowed_callers
The basic versions of web search (`web_search_20250305`) and web fetch (`web_fetch_20250910`) are eligible for [Zero Data Retention (ZDR)](../Other/manage-claude-api-and-data-retention.md).
The `_20260209` and later versions with dynamic filtering are **not** ZDR-eligible by default because dynamic filtering relies on code execution internally.
To use a `_20260209` or later server tool with ZDR, disable dynamic filtering by setting `"allowed_callers": ["direct"]` on the tool:
```python
{
"type": "web_search_20260209",
"name": "web_search",
"allowed_callers": ["direct"]
}
```
This restricts the tool to direct invocation only, bypassing the internal code execution step.
`allowed_callers` controls how a tool can be invoked: directly by Claude (`"direct"`), from inside a code execution container (for example, `"code_execution_20260120"`), or both. The `_20260209` versions of the web tools default to the code execution caller only; earlier versions default to `["direct"]`. On models that don't support programmatic tool calling, these versions require `allowed_callers: ["direct"]`; without it the API returns a validation error that says to set it.
Even when web fetch is used in a ZDR-eligible configuration, website publishers might retain any parameters passed to the URL if Claude fetches content from their site.
## Domain filtering
Server tools that access the web accept `allowed_domains` and `blocked_domains` parameters to control which domains Claude can reach. Both are fields on the tool object:
```python
{
"type": "web_search_20250305",
"name": "web_search",
"allowed_domains": ["example.com", "docs.python.org"]
}
```
When using domain filters:
- Domains should not include the HTTP/HTTPS scheme (use `example.com` instead of `https://example.com`).
- Subdomains are automatically included (`example.com` covers `docs.example.com`).
- Specific subdomains restrict results to only that subdomain (`docs.example.com` returns only results from that subdomain, not from `example.com` or `api.example.com`).
- Subpaths are supported for web search and match anything after the path (`example.com/blog` matches `example.com/blog/post-1`).
- Web fetch matches on the domain only: an entry that includes a path never matches a web fetch URL.
- You can use either `allowed_domains` or `blocked_domains`, but not both in the same request.
**Wildcard support:**
- Wildcards (`*`) are not allowed in the domain itself, only in the path after it.
- Valid: `example.com/*`, `example.com/*/articles`
- Invalid: `*.example.com`, `ex*.com`
Invalid domain formats are rejected at request time with a 400 `invalid_request_error`.
Request-level domain restrictions work together with any organization-level domain restrictions configured in Claude Console. Request-level `allowed_domains` must be a subset of the organization-level allowed list; entries outside it cause the API to return a validation error. A request-level allowed list that includes a domain your organization blocks is rejected with a `400` error that names the conflicting entries.
Unicode characters in domain names can bypass domain filters through homograph attacks: `аmazon.com` (with a Cyrillic `а`) looks identical to `amazon.com` but is a different domain. Use ASCII-only domain names in allow and block lists, and audit existing entries for non-ASCII characters.
[Claude Managed Agents](../Other/managed-agents-overview.md) uses the same `allowed_domains` and `blocked_domains` fields on the `web_search` and `web_fetch` entries of the agent toolset. On Managed Agents, each list holds at most 64 entries, domains listed for `web_fetch` cannot include a path, and fields specific to the Messages API tools, such as `max_uses`, `citations`, and `cache_control`, are not available. See [Domain list rules](../Other/managed-agents-tools-web-restrictions.md#domain-list-rules) for the full rules.
Organization-level web search and web fetch settings in the Claude Console apply to Messages API requests only. They do not apply to Managed Agents sessions, which use the per-tool lists on the agent toolset instead. For a session in a cloud environment with `limited` networking, the environment's `allowed_hosts` also applies to `web_search` and `web_fetch`; see [Networking](../Other/managed-agents-environments.md#networking). The per-tool lists restrict these tools further, within the hosts that `allowed_hosts` allows.
## Dynamic filtering with code execution
The `_20260209` and later versions of web search and web fetch use code execution internally to apply dynamic filters against search results.
You don't need to add a `code_execution` tool for these versions: when dynamic filtering runs, the API provisions code execution for the request automatically, and both tools share a single execution container. If you do include one, use `code_execution_20260120` or later; the API rejects older code execution versions alongside these web tool versions.
## Streaming server-tool events
Server-tool events stream as part of the normal server-sent events (SSE) flow. A `server_tool_use` block that Claude calls directly streams like a client `tool_use` block: a `content_block_start` event followed by `input_json_delta` events. The result block arrives complete in a single `content_block_start` event, with no deltas.
See [Streaming](../Guides/build-with-claude-streaming.md) for the full event reference. Individual tool pages document tool-specific event names where they differ.
## Batch requests
All server tools support batch processing. In a batch, the agentic loop runs just as it does for synchronous requests, with a higher per-turn iteration limit. If the loop reaches that limit, the response ends with `stop_reason: "pause_turn"`; you can continue it by submitting a follow-up request with the returned content. See [Server tools and the agentic loop](../Guides/build-with-claude-batch-processing.md#server-tools-and-the-agentic-loop) for details.
Common batch workloads include enriching a dataset with information from the web, checking a large set of documents against current sources, and running analysis code over many files.
## Next steps
[Troubleshooting tool use](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Fix the most common tool-use errors with symptom-to-fix diagnostic tables.
[Web search tool](agents-and-tools-tool-use-web-search-tool.md)
Search the web and cite results.
[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)
Fetch and read content from specific URLs to augment Claude's context with live web content.
[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)
Run Python and bash code in a sandboxed container to analyze data, generate files, and iterate on solutions.
[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)
Discover and load tools on demand.
---
## Strict tool use - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-strict-tool-use.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fstrict-tool-use)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Strict tool use
Copy page
Enforce JSON Schema compliance on Claude's tool inputs with grammar-constrained sampling.
Copy page
Setting `strict: true` on a tool definition guarantees Claude's tool inputs match your JSON Schema by constraining the model's token sampling to schema-valid outputs (a technique called grammar-constrained sampling). This page covers why strict mode matters for agents, how to enable it, and common use cases. For the supported JSON Schema subset, see [JSON Schema limitations](../Guides/build-with-claude-structured-outputs.md#json-schema-limitations). For non-strict schema guidance, see [Define tools](agents-and-tools-tool-use-implement-tool-use.md).
Strict tool use validates tool parameters, ensuring Claude calls your functions with correctly-typed arguments. Use strict tool use when you need to:
- Validate tool parameters
- Build agentic workflows
- Ensure type-safe function calls
- Handle complex tools with nested properties
## Why strict tool use matters for agents
Building reliable agentic systems requires guaranteed schema conformance. Without strict mode, Claude might return incompatible types (`"2"` instead of `2`) or omit required fields, breaking your functions and causing runtime errors.
Strict tool use guarantees type-safe parameters:
- Functions receive correctly-typed arguments every time
- No need to validate and retry tool calls
- Production-ready agents that work consistently at scale
For example, suppose a booking system needs `passengers: int`. Without strict mode, Claude might provide `passengers: "two"` or `passengers: "2"`. With `strict: true`, the response always contains `passengers: 2`.
## Quick start
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
tools=[
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"strict": True, # Enable strict mode
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA",
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "The unit of temperature, either 'celsius' or 'fahrenheit'",
},
},
"required": ["location"],
"additionalProperties": False,
},
}
],
)
print(response.content)
```
**Response format:** Tool use blocks with validated inputs in `response.content[x].input`
Output
```python
{
"type": "tool_use",
"name": "get_weather",
"input": {
"location": "San Francisco, CA"
}
}
```
**Guarantees:**
- Tool `input` strictly follows the `input_schema`
- Tool `name` is always valid (from provided tools or server tools)
## How it works
1. 1
### Define your tool schema
Create a JSON schema for your tool's `input_schema`. The schema uses standard JSON Schema format with some limitations (see [JSON Schema limitations](../Guides/build-with-claude-structured-outputs.md#json-schema-limitations)).
2. 2
### Add strict: true
Set `"strict": true` as a top-level property in your tool definition, alongside `name`, `description`, and `input_schema`.
3. 3
### Handle tool calls
When Claude uses the tool, the `input` field in the `tool_use` block strictly follows your `input_schema`, and the `name` is always valid.
The [computer use](agents-and-tools-tool-use-computer-use-tool.md) and [browser use](agents-and-tools-tool-use-browser-use-tool.md) toolset entries (`computer_toolset_20260801` and `browser_toolset_20260801`) don't accept `strict: true`; a request that sets it on either entry is rejected.
## Common use cases
### Validated tool inputs
Ensure tool parameters exactly match your schema:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Search for flights to Tokyo departing June 1, 2026",
}
],
tools=[
{
"name": "search_flights",
"strict": True,
"input_schema": {
"type": "object",
"properties": {
"destination": {"type": "string"},
"departure_date": {"type": "string", "format": "date"},
"passengers": {
"type": "integer",
"enum": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
},
},
"required": ["destination", "departure_date"],
"additionalProperties": False,
},
}
],
)
print(response)
```
### Agentic workflow with multiple validated tools
Build reliable multistep agents with guaranteed tool parameters:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Help me plan a trip from New York to Paris for 2 people, departing June 1, 2026",
}
],
tools=[
{
"name": "search_flights",
"strict": True,
"input_schema": {
"type": "object",
"properties": {
"origin": {"type": "string"},
"destination": {"type": "string"},
"departure_date": {"type": "string", "format": "date"},
"travelers": {"type": "integer", "enum": [1, 2, 3, 4, 5, 6]},
},
"required": ["origin", "destination", "departure_date"],
"additionalProperties": False,
},
},
{
"name": "search_hotels",
"strict": True,
"input_schema": {
"type": "object",
"properties": {
"city": {"type": "string"},
"check_in": {"type": "string", "format": "date"},
"guests": {"type": "integer", "enum": [1, 2, 3, 4]},
},
"required": ["city", "check_in"],
"additionalProperties": False,
},
},
],
)
print(response)
```
## Data retention
Strict tool use compiles tool `input_schema` definitions into grammars using the same pipeline as [structured outputs](../Guides/build-with-claude-structured-outputs.md). Tool schemas are temporarily cached for up to 24 hours since last use. Prompts and responses are not retained beyond the API response.
Strict tool use is HIPAA eligible, but **protected health information (PHI) must not be included in tool schema definitions**. The API caches compiled schemas separately from message content, and these cached schemas do not receive the same PHI protections as prompts and responses. Do not include PHI in `input_schema` property names, `enum` values, `const` values, or `pattern` regular expressions. PHI should only appear in message content (prompts and responses), where it is protected under HIPAA safeguards.
For ZDR and HIPAA eligibility across all features, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
## Next steps
[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)
Fetch and read content from specific URLs to bring live web content into Claude's context.
[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)
Cache tool definitions across turns to reduce cost and latency.
[Structured outputs](../Guides/build-with-claude-structured-outputs.md)
Get validated JSON responses using the same grammar-constrained sampling.
[Define tools](agents-and-tools-tool-use-implement-tool-use.md)
Specify tool schemas, write effective descriptions, and control when Claude calls your tools.
---
## Text editor tool - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-text-editor-tool.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Ftext-editor-tool)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Text editor tool
Copy page
Give Claude the Anthropic-defined text editor tool to view, create, and edit files, and handle its view, str_replace, create, and insert commands.
Copy page
To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
Claude can use an Anthropic-schema text editor tool to view and modify text files, helping you debug, fix, and improve your code or other text documents. This allows Claude to directly interact with your files, providing hands-on assistance rather than just suggesting changes.
For model support, see the [Tool reference](agents-and-tools-tool-use-tool-reference.md).
## When to use the text editor tool
Some examples of when to use the text editor tool are:
- **Code debugging:** Have Claude identify and fix bugs in your code, from syntax errors to logic issues.
- **Code refactoring:** Let Claude improve your code structure, readability, and performance through targeted edits.
- **Documentation generation:** Ask Claude to add docstrings, comments, or README files to your code base.
- **Test creation:** Have Claude create unit tests for your code based on its analysis of the implementation.
## Use the text editor tool
Provide the text editor tool (named `str_replace_based_edit_tool`) to Claude using the Messages API.
You can optionally specify a `max_characters` parameter to control truncation when viewing large files.
`max_characters` is only compatible with `text_editor_20250728` and later versions of the text editor tool.
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[
{
"type": "text_editor_20250728",
"name": "str_replace_based_edit_tool",
"max_characters": 10000,
}
],
messages=[
{
"role": "user",
"content": "There's a syntax error in my primes.py file. Can you help me fix it?",
}
],
)
print(response)
```
Use the text editor tool in the following way:
1. 1
### Provide Claude with the text editor tool and a user prompt
- Include the text editor tool in your API request
- Provide a user prompt that may require examining or modifying files, such as "Can you fix the syntax error in my code?"
2. 2
### Claude uses the tool to examine files or directories
- Claude assesses what it needs to look at and uses the `view` command to examine file contents or list directory contents
- The API response will contain a `tool_use` content block with the `view` command
3. 3
### Execute the view command and return results
- Extract the file or directory path from Claude's tool use request
- Read the file's contents or list the directory contents
- If a `max_characters` parameter was specified in the tool configuration, truncate the file contents to that length
- Return the results to Claude by continuing the conversation with a new `user` message containing a `tool_result` content block
4. 4
### Claude uses the tool to modify files
- After examining the file or directory, Claude may use a command such as `str_replace` to make changes or `insert` to add text at a specific line number.
- If Claude uses the `str_replace` command, Claude constructs a properly formatted tool use request with the old text and new text to replace it with
5. 5
### Execute the edit and return results
- Extract the file path, old text, and new text from Claude's tool use request
- Perform the text replacement in the file
- Return the results to Claude
6. 6
### Claude provides its analysis and explanation
- After examining and possibly editing the files, Claude provides a complete explanation of what it found and what changes it made
### Text editor tool commands
The text editor tool supports several commands for viewing and modifying files:
#### view
The `view` command allows Claude to examine the contents of a file or list the contents of a directory. It can read the entire file or a specific range of lines.
Parameters:
- `command`: Must be "view"
- `path`: The path to the file or directory to view
- `view_range` (optional): An array of two integers specifying the start and end line numbers to view. Line numbers are 1-indexed, and -1 for the end line means read to the end of the file. This parameter only applies when viewing files, not directories.
### Example view commands
Example for viewing a file:
```python
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "str_replace_based_edit_tool",
"input": {
"command": "view",
"path": "primes.py"
}
}
```
Example for viewing a directory:
```python
{
"type": "tool_use",
"id": "toolu_02B19r91rw91mr917835mr9",
"name": "str_replace_based_edit_tool",
"input": {
"command": "view",
"path": "src/"
}
}
```
#### str_replace
The `str_replace` command allows Claude to replace a specific string in a file with a new string. This is used for making precise edits.
Parameters:
- `command`: Must be "str_replace"
- `path`: The path to the file to modify
- `old_str`: The text to replace (must match exactly, including whitespace and indentation)
- `new_str`: The new text to insert in place of the old text
### Example str_replace command
```python
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "str_replace_based_edit_tool",
"input": {
"command": "str_replace",
"path": "primes.py",
"old_str": "for num in range(2, limit + 1)",
"new_str": "for num in range(2, limit + 1):"
}
}
```
#### create
The `create` command allows Claude to create a new file with specified content.
Parameters:
- `command`: Must be "create"
- `path`: The path where the new file should be created
- `file_text`: The content to write to the new file
### Example create command
```python
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "str_replace_based_edit_tool",
"input": {
"command": "create",
"path": "test_primes.py",
"file_text": "import unittest\nimport primes\n\nclass TestPrimes(unittest.TestCase):\n def test_is_prime(self):\n self.assertTrue(primes.is_prime(2))\n self.assertTrue(primes.is_prime(3))\n self.assertFalse(primes.is_prime(4))\n\nif __name__ == '__main__':\n unittest.main()"
}
}
```
#### insert
The `insert` command allows Claude to insert text at a specific location in a file.
Parameters:
- `command`: Must be "insert"
- `path`: The path to the file to modify
- `insert_line`: The line number after which to insert the text (0 for beginning of file)
- `insert_text`: The text to insert
### Example insert command
```python
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "str_replace_based_edit_tool",
"input": {
"command": "insert",
"path": "primes.py",
"insert_line": 0,
"insert_text": "\"\"\"Module for working with prime numbers.\n\nThis module provides functions to check if a number is prime\nand to generate a list of prime numbers up to a given limit.\n\"\"\"\n"
}
}
```
### Example: Fixing a syntax error with the text editor tool
This example demonstrates how Claude uses the text editor tool to fix a syntax error in a Python file.
First, your application provides Claude with the text editor tool and a prompt to fix a syntax error:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}],
messages=[
{
"role": "user",
"content": "There's a syntax error in my primes.py file. Can you help me fix it?",
}
],
)
print(response)
```
Claude uses the text editor tool first to view the file:
Output
```python
{
"id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue."
},
{
"type": "tool_use",
"id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
"name": "str_replace_based_edit_tool",
"input": {
"command": "view",
"path": "primes.py"
}
}
]
}
```
Your application should then read the file and return its contents to Claude:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}],
messages=[
{
"role": "user",
"content": "There's a syntax error in my primes.py file. Can you help me fix it?",
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue.",
},
{
"type": "tool_use",
"id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
"name": "str_replace_based_edit_tool",
"input": {"command": "view", "path": "primes.py"},
},
],
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
"content": '1: def is_prime(n):\n2: """Check if a number is prime."""\n3: if n <= 1:\n4: return False\n5: if n <= 3:\n6: return True\n7: if n % 2 == 0 or n % 3 == 0:\n8: return False\n9: i = 5\n10: while i * i <= n:\n11: if n % i == 0 or n % (i + 2) == 0:\n12: return False\n13: i += 6\n14: return True\n15: \n16: def get_primes(limit):\n17: """Generate a list of prime numbers up to the given limit."""\n18: primes = []\n19: for num in range(2, limit + 1)\n20: if is_prime(num):\n21: primes.append(num)\n22: return primes\n23: \n24: def main():\n25: """Main function to demonstrate prime number generation."""\n26: limit = 100\n27: prime_list = get_primes(limit)\n28: print(f"Prime numbers up to {limit}:")\n29: print(prime_list)\n30: print(f"Found {len(prime_list)} prime numbers.")\n31: \n32: if __name__ == "__main__":\n33: main()',
}
],
},
],
)
print(response)
```
**Line numbers**
In the preceding example, the `view` tool result includes file contents with line numbers prepended to each line (for example, "1: def is_prime(n):"). Line numbers are not required, but they are essential for successfully using the `view_range` parameter to examine specific sections of files and the `insert_line` parameter to add content at precise locations.
Claude identifies the syntax error and uses the `str_replace` command to fix it:
Output
```python
{
"id": "msg_01VwXyZAbCdEfGhIjKlMnO",
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you."
},
{
"type": "tool_use",
"id": "toolu_01PqRsTuVwXyZAbCdEfGh",
"name": "str_replace_based_edit_tool",
"input": {
"command": "str_replace",
"path": "primes.py",
"old_str": " for num in range(2, limit + 1)",
"new_str": " for num in range(2, limit + 1):"
}
}
]
}
```
Your application should then make the edit and return the result:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}],
messages=[
# Previous messages...
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you.",
},
{
"type": "tool_use",
"id": "toolu_01PqRsTuVwXyZAbCdEfGh",
"name": "str_replace_based_edit_tool",
"input": {
"command": "str_replace",
"path": "primes.py",
"old_str": " for num in range(2, limit + 1)",
"new_str": " for num in range(2, limit + 1):",
},
},
],
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01PqRsTuVwXyZAbCdEfGh",
"content": "Successfully replaced text at exactly one location.",
}
],
},
],
)
print(response)
```
Finally, Claude provides a complete explanation of the fix:
Output
```python
{
"id": "msg_01IjKlMnOpQrStUvWxYzAb",
"model": "claude-opus-5-5",
"stop_reason": "end_turn",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I've fixed the syntax error in your primes.py file. The issue was in the `get_primes` function at line 19. There was a missing colon (:) at the end of the for loop line.\n\nHere's what I changed:\n\nFrom:\n```python\nfor num in range(2, limit + 1)\n```\n\nTo:\n```python\nfor num in range(2, limit + 1):\n```\n\nIn Python, a colon is required at the end of statements that start a new code block, such as for loops, if statements, function definitions, etc. Without the colon, Python raises a syntax error because it doesn't know where the code block begins.\n\nYour code should now run correctly. The function will properly generate a list of prime numbers up to the specified limit."
}
]
}
```
## Implement the text editor tool
The text editor tool is implemented as a schema-less tool. When using this tool, you don't need to provide an input schema as with other tools; the schema is built into Claude's model and can't be modified.
The tool type is `type: "text_editor_20250728"` for Claude 4 and later models.
1. 1
### Initialize your editor implementation
Create helper functions to handle file operations like reading, writing, and modifying files. Consider implementing backup functionality to recover from mistakes.
2. 2
### Handle editor tool calls
Create a function that processes tool calls from Claude based on the command type:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
``` shiki
def handle_editor_tool(tool_call):
input_params = tool_call.input
command = input_params.get("command", "")
file_path = input_params.get("path", "")
match command:
case "view":
# Read and return file contents
pass
case "str_replace":
# Replace text in file
pass
case "create":
# Create new file
pass
case "insert":
# Insert text at location
pass
```
3. 3
### Implement security measures
Add validation and security checks:
- Validate file paths to prevent directory traversal
- Create backups before making changes
- Handle errors gracefully
- Implement permissions checks
4. 4
### Process Claude's responses
Extract and handle tool calls from Claude's responses:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
``` shiki
# Process tool use in Claude's response
for content in response.content:
if content.type == "tool_use":
# Execute the tool based on command
result = handle_editor_tool(content)
# Return result to Claude
tool_result = {
"type": "tool_result",
"tool_use_id": content.id,
"content": result,
}
```
When implementing the text editor tool, keep in mind:
1. **Security:** The tool has access to your local filesystem, so implement proper security measures.
2. **Backup:** Always create backups before allowing edits to important files.
3. **Validation:** Validate all inputs to prevent unintended changes.
4. **Unique matching:** Make sure replacements match exactly one location to avoid unintended edits.
### Handle errors
When using the text editor tool, various errors may occur. Here is guidance on how to handle them:
### File not found
If Claude tries to view or modify a file that doesn't exist, return an appropriate error message in the `tool_result`:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: File not found",
"is_error": true
}
]
}
```
### Multiple matches for replacement
If Claude's `str_replace` command matches multiple locations in the file, return an appropriate error message:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Found 3 matches for replacement text. Please provide more context to make a unique match.",
"is_error": true
}
]
}
```
### No matches for replacement
If Claude's `str_replace` command doesn't match any text in the file, return an appropriate error message:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: No match found for replacement. Please check your text and try again.",
"is_error": true
}
]
}
```
### Permission errors
If there are permission issues with creating, reading, or modifying files, return an appropriate error message:
```python
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Permission denied. Cannot write to file.",
"is_error": true
}
]
}
```
### Follow implementation best practices
### Provide clear context
When asking Claude to fix or modify code, be specific about what files need to be examined or what issues need to be addressed. Clear context helps Claude identify the right files and make appropriate changes.
**Less helpful prompt:** "Can you fix my code?"
**Better prompt:** "There's a syntax error in my primes.py file that prevents it from running. Can you fix it?"
### Be explicit about file paths
Specify file paths clearly when needed, especially if you're working with multiple files or files in different directories.
**Less helpful prompt:** "Review my helper file"
**Better prompt:** "Can you check my utils/helpers.py file for any performance issues?"
### Create backups before editing
Implement a backup system in your application that creates copies of files before allowing Claude to edit them, especially for important or production code.
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
def backup_file(file_path):
"""Create a backup of a file before editing."""
backup_path = f"{file_path}.backup"
if os.path.exists(file_path):
with open(file_path, "r") as src, open(backup_path, "w") as dst:
dst.write(src.read())
```
### Handle unique text replacement carefully
The `str_replace` command requires an exact match for the text to be replaced. Your application should ensure that there is exactly one match for the old text or provide appropriate error messages.
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
def safe_replace(file_path, old_text, new_text):
"""Replace text only if there's exactly one match."""
with open(file_path, "r") as f:
content = f.read()
count = content.count(old_text)
if count == 0:
return "Error: No match found"
elif count > 1:
return f"Error: Found {count} matches"
else:
new_content = content.replace(old_text, new_text)
with open(file_path, "w") as f:
f.write(new_content)
return "Successfully replaced text"
```
### Verify changes
After Claude makes changes to a file, verify the changes by running tests or checking that the code still works as expected.
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
def verify_changes(file_path):
"""Run tests or checks after making changes."""
try:
# For Python files, check for syntax errors
if file_path.endswith(".py"):
import ast
with open(file_path, "r") as f:
ast.parse(f.read())
return "Syntax check passed"
except Exception as e:
return f"Verification failed: {str(e)}"
```
------------------------------------------------------------------------
## Pricing and token usage
The text editor tool uses the same pricing structure as other tools used with Claude. It follows the standard input and output token pricing based on the Claude model you're using.
In addition to the base tokens, the following additional input tokens are needed for the text editor tool:
| Tool | Additional input tokens |
|--------------------------------------------------------------------------------|-------------------------|
| `text_editor_20250728` (Claude 4.7 and later models and Claude Mythos Preview) | 974 tokens |
| `text_editor_20250728` (Claude 4.6 and earlier models) | 745 tokens |
For more detailed information about tool pricing, see [Tool use pricing](agents-and-tools-tool-use-overview.md#pricing).
## Integrate the text editor tool with other tools
You can use the text editor tool alongside other Claude tools. When combining tools, ensure you:
- Match the tool version with the model you're using
- Account for the additional token usage for all tools included in your request
## Change log
| Date | Version | Changes |
|------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| July 28, 2025 | `text_editor_20250728` | Release of an updated text editor tool that fixes some issues and adds an optional `max_characters` parameter. It is otherwise identical to `text_editor_20250429`. |
| April 29, 2025 | `text_editor_20250429` | Release of the text editor tool for Claude 4. This version removes the `undo_edit` command but maintains all other capabilities. The tool name has been updated to reflect its str_replace-based architecture. |
| March 13, 2025 | `text_editor_20250124` | Introduction of standalone text editor tool documentation. This version is optimized for Claude Sonnet 3.7 but has identical capabilities to the previous version. |
| October 22, 2024 | `text_editor_20241022` | Initial release of the text editor tool with Claude Sonnet 3.5 (retired; see [Model deprecations](../../20-Models/about-claude-model-deprecations.md)). Provides capabilities for viewing, creating, and editing files through the `view`, `create`, `str_replace`, `insert`, and `undo_edit` commands. |
## Next steps
Here are some ideas for how to use the text editor tool in more convenient and powerful ways:
- **Integrate with your development workflow**: Build the text editor tool into your development tools or IDE
- **Create a code review system**: Have Claude review your code and make improvements
- **Build a debugging assistant**: Create a system where Claude can help you diagnose and fix issues in your code
- **Implement file format conversion**: Let Claude help you convert files from one format to another
- **Automate documentation**: Set up workflows for Claude to automatically document your code
The text editor tool enables Claude to work directly with your code base, supporting workflows from debugging to automated documentation.
[Tool use overview](agents-and-tools-tool-use-overview.md)
Learn how to implement tool workflows for use with Claude.
[Bash tool](agents-and-tools-tool-use-bash-tool.md)
Execute shell commands with Claude.
---
## Tool combinations - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-combinations
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-tool-combinations.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Ftool-combinations)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tool infrastructure
# Tool combinations
Copy page
Common Anthropic tool pairings for research agents, coding agents, and long-running agents.
Copy page
Anthropic-provided tools are designed to work together. Common agent patterns pair tools that cover complementary stages of a workflow: one tool gathers or discovers, another processes or acts. The combinations below are starting points, not prescriptions. Mix them to fit your task.
Each snippet shows only the `tools` array. See [Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md) for the full request shape.
## Research agent: web_search + code_execution
Search finds sources; code execution analyzes and synthesizes. Claude searches for data, then writes Python to process, tabulate, or visualize it. This pairing is a good fit for questions that require both up-to-date information and nontrivial computation over that information, such as "compare this quarter's earnings across the top five cloud providers."
```python
{
"tools": [
{ "type": "web_search_20260209", "name": "web_search" },
{ "type": "code_execution_20260521", "name": "code_execution" }
]
}
```
The flow is typically search, then execute, then optionally search again if the first pass surfaced a gap. Code execution runs server-side, so there's no client-side sandbox to manage.
## Coding agent: text_editor + bash
The text editor reads and modifies files; bash runs tests and build commands. This is the canonical software-development loop: inspect the code, make an edit, run the tests, repeat. Both tools are client-executed, so your application controls which files and commands are accessible.
```python
{
"tools": [
{ "type": "text_editor_20250728", "name": "str_replace_based_edit_tool" },
{ "type": "bash_20250124", "name": "bash" }
]
}
```
Pair this with a constrained working directory and a command allowlist if the agent operates on untrusted code. See [Text editor tool](agents-and-tools-tool-use-text-editor-tool.md) and [Bash tool](agents-and-tools-tool-use-bash-tool.md) for the execution contracts.
## Cite-then-fetch: web_search + web_fetch
Search surfaces candidate URLs; fetch retrieves full page content for the relevant ones. This avoids fetching everything upfront. Claude runs a search, inspects the snippets, picks the two or three results that actually look relevant, and fetches only those.
```python
{
"tools": [
{ "type": "web_search_20260209", "name": "web_search" },
{ "type": "web_fetch_20260209", "name": "web_fetch" }
]
}
```
This pairing is useful when the answer lives in long-form content (documentation pages, articles, specifications) that a search snippet can't fully capture. Fetch pulls the complete page so Claude can cite specific passages.
## Long-running agent: memory + any other tools
Memory persists state across conversations; the other tools do the work. Add memory to any agent that needs to remember prior sessions, such as a support agent that recalls a customer's earlier issues or a project assistant that tracks decisions made last week.
```python
{
"tools": [{ "type": "memory_20250818", "name": "memory" }]
}
```
Add your other tools alongside `memory` in the same array.
Memory is orthogonal to your other tools. It doesn't change how they behave; it gives Claude a place to write down and later retrieve facts that would otherwise be lost when the context window resets. See [Memory tool](agents-and-tools-tool-use-memory-tool.md) for the storage model.
## All-in-one: computer_use
The computer use tool subsumes most others by operating a full desktop. Claude sees screenshots and issues mouse and keyboard actions, which means it can drive any application a human can. Use this when the task requires arbitrary GUI interaction that more specific tools can't reach: legacy software without an API, visual verification steps, or workflows that span multiple desktop apps.
```python
{
"tools": [{ "type": "computer_toolset_20260801" }]
}
```
The toolset entry takes no `name` or display dimensions: coordinates are expressed in the pixel space of the screenshots you return, and you can turn individual actions off through the entry's `configs` field.
Computer use is the most general option and also the slowest, because Claude typically needs a fresh screenshot after each batch of actions. Prefer narrower tools when they cover your use case, and reach for computer use when nothing else fits. If the task stays inside a web browser, use the browser agent pattern in the next section. See [Computer use tool](agents-and-tools-tool-use-computer-use-tool.md) for the sandbox setup.
## Browser agent: browser_use
When the whole task happens inside webpages (filling forms, reading page content, working across tabs), the browser use tool is a closer fit than computer use. Your application drives a browser it controls and returns screenshots or page state; Claude calls page-aware member tools such as `read_page`, `find`, `form_input`, and `get_page_text` alongside clicks and typing, so it can act on element references in addition to pixel coordinates.
```python
{
"tools": [{ "type": "browser_toolset_20260801" }]
}
```
Like the computer use toolset, the entry takes no `name`, and you turn individual member tools off through its `configs` field. See [Browser use tool](agents-and-tools-tool-use-browser-use-tool.md) for the execution contract.
## Next steps
[Tool reference](agents-and-tools-tool-use-tool-reference.md)
Full catalog of Anthropic-provided tools with type strings and parameters.
[Tool use overview](agents-and-tools-tool-use-overview.md)
How tool use works and when to use Anthropic tools versus defining your own.
---
## Tool reference - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-tool-reference.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Ftool-reference)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tool infrastructure
# Tool reference
Copy page
Directory of Anthropic-provided server tools, client tools, and client toolsets, plus reference for optional tool definition properties.
Copy page
This page is a reference for the tools Anthropic provides and the optional properties you can set on any tool definition. For a conceptual introduction to tool use, see [Tool use with Claude](agents-and-tools-tool-use-overview.md). For guidance on implementing tool use in your application, see [Define tools](agents-and-tools-tool-use-implement-tool-use.md).
## Anthropic-provided tools
Anthropic provides two kinds of tools: **server tools** that execute on Anthropic's infrastructure, and **client tools** where Anthropic defines the schema but your application handles execution. Both kinds appear in your request's `tools` array alongside any user-defined tools.
[TABLE]
For model compatibility, see each tool's page. Supported models vary by tool and by tool version. To check from your code whether a model accepts web search or code execution, see [Using the Models API](../../20-Models/about-claude-models-overview.md#using-the-models-api).
The tool search `type` values also accept undated aliases: `tool_search_tool_regex` and `tool_search_tool_bm25`. These resolve to the latest dated version.
### Tool versioning
Most Anthropic-provided tools carry a `_YYYYMMDD` suffix in the `type` string. A new version is released when the tool's behavior, schema, or model support changes. Older versions remain available so that existing integrations continue to work.
When a tool has multiple active versions, the relationship between them varies:
- **Capability-keyed:** `web_search_20260209` and `web_fetch_20260209` add dynamic content filtering over their predecessors; `web_fetch_20260309` adds a cache-bypass option; `web_search_20260318` and `web_fetch_20260318` add response-inclusion control. `code_execution_20260120` adds [programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md) from within the sandbox; `code_execution_20260521` discloses the per-cell time limit in the tool description. In each case, both the new and old versions are current; which one you use depends on whether you need the new capability.
- **Model-keyed:** `text_editor_20250728` is for Claude 4 and later models and `text_editor_20250124` is for earlier models. The version you use depends on the model you target.
- **Variant, not version:** `tool_search_tool_regex_20251119` and `tool_search_tool_bm25_20251119` are two search algorithms released together. Neither supersedes the other.
- **Legacy:** `code_execution_20250522` supports only Python. `code_execution_20250825` adds Bash and file operations.
- **Successor:** `computer_toolset_20260801` is the stable successor to the beta `computer_20251124` and `computer_20250124` versions, which remain available on the models listed for them under [Earlier tool versions](agents-and-tools-tool-use-computer-use-tool.md#earlier-tool-versions). `browser_toolset_20260801` is the first version of the browser use tool. Both are [client toolsets](#client-toolsets).
The `mcp_toolset` type is not date-versioned; versioning is carried in the `anthropic-beta` header instead.
### Client toolsets
The [computer use tool](agents-and-tools-tool-use-computer-use-tool.md) and [browser use tool](agents-and-tools-tool-use-browser-use-tool.md) are Anthropic-defined client toolsets: one entry in `tools` declares a fixed set of member tools whose names, descriptions, and input schemas Anthropic defines, and your application executes every call. The entry takes no `name`, because the dated `type` fixes the member names. `configs`, `cache_control`, and `allowed_callers` (which accepts only `["direct"]`) are optional.
Client toolsets are Messages API tools. They aren't currently available as agent tools in [Claude Managed Agents](../Other/managed-agents-tools.md), which provides its own built-in agent toolset, MCP toolsets, and custom tools.
```python
{
"type": "browser_toolset_20260801",
"configs": {
"javascript_exec": { "enabled": true }
},
"cache_control": { "type": "ephemeral" }
}
```
`configs` adjusts individual members:
- Keys are member names, and each value accepts only `enabled` and `defer_loading`.
- A member you omit keeps its defaults. An absent value, `{}`, and a restated default are equivalent.
- An unknown member name or any other field in a member's value is rejected, as is a `configs` that disables every member (omit the entry instead).
- A disabled member is removed from the tools Claude sees. If Claude still names it, return an error `tool_result`.
Set `defer_loading` per member, never on the entry, and give every enabled member the same value: under [tool search](agents-and-tools-tool-use-tool-search-tool.md#deferred-tool-loading) the toolset loads and expands as one definition. When every enabled member defers, only a [tool search tool](agents-and-tools-tool-use-tool-search-tool.md) that isn't itself deferred can surface the toolset, so declare one in the same request. Don't put `cache_control` on a toolset entry whose members defer; set the breakpoint on a non-deferred tool instead, because deferred definitions are not part of the cached prefix.
`cache_control` goes on the entry only; to learn where the breakpoint lands, including markers inside a batch action, see [Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md#cache-control-on-tool-definitions).
**Handle member tool calls.** Claude calls a member with a `tool_use` block whose `name` is the member name and whose `toolset_name` is `computer` or `browser`; `input` holds that member's parameters and no `action` field. Dispatch on the `toolset_name` and `name` pair, because a custom tool may share a member's name and the two toolsets share names such as `screenshot`. Only member results echo `toolset_name`. Several member calls in one turn form a batch action that you run in order ([computer use](agents-and-tools-tool-use-computer-use-tool.md#batch-actions), [browser use](agents-and-tools-tool-use-browser-use-tool.md#batch-actions)). New members arrive only with a new dated `type`.
**Not supported on toolset entries.** The API rejects each of these with an `invalid_request_error`:
- `strict: true` or `input_examples`.
- `defer_loading` on the entry, or enabled members whose `defer_loading` values differ (set it per member in `configs`, all to the same value).
- A code execution caller in `allowed_callers` (no [programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)).
- The legacy `fine-grained-tool-streaming-2025-05-14` beta header. When you stream, each member's `input` arrives as one complete `input_json_delta`.
- A `tool_choice` of type `tool` that names the toolset or a member (use `auto`, `any`, or `none`).
- Two entries of the same toolset, or another tool that carries that toolset's name: a tool named `computer` alongside `computer_toolset_20260801`, or a tool named `browser` alongside `browser_toolset_20260801`. The two toolsets can be declared together.
## Tool definition properties
Every tool in the `tools` array, including user-defined tools, accepts optional properties that control how the tool is loaded, who can call it, and how its inputs are validated. These properties compose: you can set `defer_loading` and `cache_control` and `strict` on the same tool.
| Property | Purpose | Available on | Detailed guide |
|-------------------------|-----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `cache_control` | Set a prompt-cache breakpoint at this tool definition | All tools (on `computer_toolset_20260801` and `browser_toolset_20260801`, set it on the toolset entry itself, not inside member `configs`) | [Prompt caching](../Guides/build-with-claude-prompt-caching.md) |
| `strict` | Guarantee schema validation on tool names and inputs | All tools except `mcp_toolset`, `computer_toolset_20260801`, and `browser_toolset_20260801` | [Strict tool use](agents-and-tools-tool-use-strict-tool-use.md) |
| `defer_loading` | Exclude the tool from the initial system prompt; load it on demand when tool search returns a `tool_reference` for it | All tools (for `mcp_toolset`, see [tool configuration](agents-and-tools-mcp-connector.md#mcp-toolset-configuration)). On the computer use and browser use toolsets, set it per member inside `configs`; see [Client toolsets](#client-toolsets). | [Tool search tool](agents-and-tools-tool-use-tool-search-tool.md) |
| `allowed_callers` | Restrict which callers can call the tool | All tools except `mcp_toolset` (on `computer_toolset_20260801` and `browser_toolset_20260801`, only `["direct"]` is accepted; see [Client toolsets](#client-toolsets)) | [Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md#the-allowed-callers-field) |
| `input_examples` | Provide example input objects to help Claude understand how to call the tool | User-defined and Anthropic-schema client tools, except `computer_toolset_20260801` and `browser_toolset_20260801`. Not available on server tools. | [Define tools](agents-and-tools-tool-use-implement-tool-use.md#providing-tool-use-examples) |
| `eager_input_streaming` | Enable fine-grained input streaming (`true`) or keep standard buffered streaming (`false`) for this tool | User-defined tools only | [Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md) |
### `allowed_callers` values
`allowed_callers` is an array that accepts any combination of:
| Value | Meaning |
|-----------------------------|-------------------------------------------------------------------------------------------------------------------|
| `"direct"` | The model can call this tool directly in a `tool_use` block. This is the default if `allowed_callers` is omitted. |
| `"code_execution_20260120"` | Code running inside a `code_execution_20260120` or later sandbox can call this tool. |
Both `"code_execution_20260120"` and `"code_execution_20260521"` are accepted in `allowed_callers` and are interchangeable: a request using either code-execution tool version satisfies tools that list either caller. Response blocks always tag the caller as `code_execution_20260120` regardless of which version the request declared.
Omitting `"direct"` from the array (for example, `"allowed_callers": ["code_execution_20260120"]`) guides Claude to call the tool only from within code execution. The response's `tool_use` block includes a `caller` field that identifies which caller called the tool. See [Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md#the-allowed-callers-field) for the full treatment, including the `caller` response shape and error behavior.
### `defer_loading` and prompt caching
Tools with `defer_loading: true` are stripped from the rendered tools section before the cache key is computed. They don't appear in the system-prompt prefix at all. When tool search discovers a deferred tool and returns a `tool_reference` for it, the tool's full definition is expanded inline at that point in the conversation body, not in the prefix.
This means `defer_loading: true` preserves your prompt cache. You can add deferred tools to a request without invalidating an existing cache entry, and the cache remains valid across the turn where the tool is discovered and the turn where it's called.
To learn how to combine `defer_loading` with `cache_control` breakpoints, see the [Tool search tool prompt caching guidance](agents-and-tools-tool-use-tool-search-tool.md#prompt-caching).
---
## Tool runner (SDK) - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-tool-runner.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Ftool-runner)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Tool runner (SDK)
Copy page
Use the SDK's tool runner to handle the agentic loop, error wrapping, and type safety automatically.
Copy page
The tool runner handles the agentic loop, error wrapping, and type safety so you don't have to. When you need human-in-the-loop approval, custom logging, or conditional execution, use the [manual loop](agents-and-tools-tool-use-handle-tool-calls.md) instead.
Instead of manually handling tool calls, tool results, and conversation management, the tool runner automatically:
- Runs tools when Claude calls them
- Handles the request/response cycle
- Manages conversation state
- Provides type safety and validation
The tool runner is in beta and available in the [Python SDK](https://github.com/anthropics/anthropic-sdk-python/blob/main/tools.md), [TypeScript SDK](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/helpers.md#tool-helpers), [C# SDK](https://github.com/anthropics/anthropic-sdk-csharp/blob/main/examples/ToolRunnerExample/Program.cs), [Go SDK](https://github.com/anthropics/anthropic-sdk-go/blob/main/tools.md), [Java SDK](https://github.com/anthropics/anthropic-sdk-java/blob/main/anthropic-java-example/src/main/java/com/anthropic/example/BetaToolRunnerRunnableToolExample.java), [PHP SDK](https://github.com/anthropics/anthropic-sdk-php/blob/main/examples/beta/beta_tool_runner.php), and [Ruby SDK](https://github.com/anthropics/anthropic-sdk-ruby/blob/main/helpers.md#3-auto-looping-tool-runner-beta).
## Basic usage
Define tools using the SDK helpers, then use the tool runner to run them.
Depending on the SDK's tool signature, a tool returns its result as a string or as content blocks (text, image, or document blocks), so a tool can return multimodal results. A returned string becomes a single text content block. To return structured data, such as a JSON object or a number, encode it as a string first.
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
Use the `@beta_tool` decorator to define tools with type hints and docstrings.
If you're using the async client, replace `@beta_tool` with `@beta_async_tool` and define the function with `async def`.
```python
import json
from anthropic import Anthropic, beta_tool
client = Anthropic()
@beta_tool
def get_weather(location: str, unit: str = "fahrenheit") -> str:
"""Get the current weather in a given location.
Args:
location: The city and state, e.g. San Francisco, CA
unit: Temperature unit, either 'celsius' or 'fahrenheit'
"""
return json.dumps({"temperature": "20°C", "condition": "Sunny"})
@beta_tool
def calculate_sum(a: int, b: int) -> str:
"""Add two numbers together.
Args:
a: First number
b: Second number
"""
return str(a + b)
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
tools=[get_weather, calculate_sum],
messages=[
{
"role": "user",
"content": "What's the weather like in Paris? Also, what's 15 + 27?",
}
],
)
for message in runner:
print(message)
```
The `@beta_tool` decorator inspects the function arguments and docstring to derive the JSON schema for you.
## Iterating over the tool runner
The tool runner is an iterable that yields messages from Claude. On each iteration, the runner checks whether Claude requested a tool use. If so, it runs the tool and sends the result back to Claude automatically, then yields the next message from Claude to continue your loop.
You can end the loop at any iteration with a `break` statement. The runner loops until Claude returns a message without a tool use, or until it reaches `max_iterations` if you set it.
If you don't need intermediate messages, you can get the final message directly:
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
Use `runner.until_done()` to get the final message.
```python
client = anthropic.Anthropic()
# ...
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
tools=[get_weather, calculate_sum],
messages=[
{
"role": "user",
"content": "What's the weather like in Paris? Also, what's 15 + 27?",
}
],
)
final_message = runner.until_done()
for block in final_message.content:
if block.type == "text":
print(block.text)
```
## Advanced usage
Within the loop, you can read each response message and modify the runner's state before the next API call. Each iteration follows this lifecycle:
1. The runner sends a request to the Messages API with its current state.
2. The runner yields the response message to your loop body.
3. Your loop body runs. You can read the message and optionally modify the runner's state.
4. When your loop body returns, the runner checks whether you modified its message history.
- **If you did not modify message history:** If the message contains tool calls, the runner appends the assistant message and the tool results, then continues. If there are no tool calls, the loop exits.
- **If you modified message history:** The runner skips its automatic append and uses your state unchanged. See [Taking over message history](#taking-over-message-history).
### Taking over message history
By default, the runner manages conversation state for you: after each tool-call turn, it appends the assistant message and any tool results to its own message history. You take over message history when you want to retry a turn (discard the response and resend), inject a follow-up message, or build the tool result yourself.
You take over by modifying the runner's messages from inside the loop body. The exact method depends on the SDK. See the per-language tabs that follow.
When you take over for an iteration, the runner does not append the assistant message or tool results from that turn. You become responsible for keeping the conversation valid: append the assistant message and a tool result yourself (if you want the turn to count), modify state conditionally so the loop can still exit when there are no tool calls, and pass `max_iterations` to bound the loop. All seven SDKs support `max_iterations`.
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
Use `generate_tool_call_response()` to inspect or compute the tool result. Calling `append_messages()` inside the loop tells the runner you're managing history yourself, so include the assistant message and tool result in what you append.
```python
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
max_iterations=10,
tools=[get_weather],
messages=[{"role": "user", "content": "What's the weather in San Francisco?"}],
)
for message in runner:
tool_response = runner.generate_tool_call_response()
if tool_response is not None:
# append_messages() flags state as modified, so the runner skips its
# automatic append for this iteration. Append the assistant message and
# tool result yourself, plus any follow-up.
runner.append_messages(
message,
tool_response,
{"role": "user", "content": "Please be concise."},
)
# When there's no tool call, leave state untouched so the loop exits.
```
To change request parameters such as `max_tokens` without taking over message history, use `set_messages_params()`. The runner still appends the assistant message and tool result automatically.
```python
for message in runner:
runner.set_messages_params(lambda params: {**params, "max_tokens": 2048})
```
### Automatic context management
For long-running agentic tasks, the TypeScript and Ruby tool runners support automatic [compaction](../Guides/build-with-claude-context-editing.md#client-side-compaction-sdk), which generates summaries when token usage exceeds a threshold so the conversation can continue beyond context window limits. Both SDKs have deprecated this client-side option in favor of [server-side compaction](../Guides/build-with-claude-compaction-threshold.md), which works with every SDK's tool runner through the `context_management` request parameter. The Python SDK (v1.0 and later) and the Go, Java, C#, and PHP tool runners don't include client-side compaction. The tool runner has a `compact_before_next_turn()` helper for on-demand compaction. See [Compact in a loop](../Guides/build-with-claude-compaction-on-demand.md#compact-in-a-loop). Use it or a `context_management` compaction edit on a runner, not both.
### Debugging tool execution
When a tool throws an exception, the tool runner catches it and returns the error to Claude as a tool result with `is_error: true`. The tool result carries the exception's message (in Python, its type and message), not the full stack trace.
What the SDK logs is language-specific. The Python SDK logs the full exception, including its stack trace, through the standard `logging` module whenever a tool raises an unhandled exception. The Python, TypeScript, and Java SDKs read the `ANTHROPIC_LOG` environment variable to turn on the SDK's logging, which includes request and response detail:
```python
# Log at info level
export ANTHROPIC_LOG=info
# Log at debug level for more verbose output
export ANTHROPIC_LOG=debug
```
The Go, Ruby, C#, and PHP SDKs don't read `ANTHROPIC_LOG`. Outside Python, no SDK logs a failed tool: to see why a tool failed, catch and log the exception inside the tool function before returning or rethrowing it.
### Intercepting tool errors
By default, tool errors are passed back to Claude, which can then respond appropriately. However, you might want to detect errors and handle them differently, for example, to stop execution early or implement custom error handling.
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
# ...
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
tools=[my_tool],
messages=[{"role": "user", "content": "Run my_tool with the query 'hello'."}],
)
for message in runner:
tool_response = runner.generate_tool_call_response()
if tool_response is not None:
# tool_response is a dict: {"role": "user", "content": [...]}
# Check if any tool result has an error
for block in tool_response["content"]:
if block.get("is_error"):
# Option 1: Raise an exception to stop the loop
raise RuntimeError(f"Tool failed: {json.dumps(block['content'])}")
# Option 2: Log and continue (let Claude handle it)
# logger.error(f"Tool error: {json.dumps(block['content'])}")
# Process the message normally
print(message.content)
```
Call `runner.generate_tool_call_response()` in the loop to get the tool results and check them for errors before the runner sends them to Claude.
### Modifying tool results
You can modify tool results before they're sent back to Claude. This is useful for adding metadata such as `cache_control` to enable [prompt caching](../Guides/build-with-claude-prompt-caching.md) on tool results, or for transforming the tool output.
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
# ...
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
tools=[search_documents],
messages=[
{
"role": "user",
"content": "Search for information about the climate of San Francisco",
}
],
)
for message in runner:
tool_response = runner.generate_tool_call_response()
if tool_response is not None:
# tool_response is a dict: {"role": "user", "content": [...]}
# Modify the tool result to add cache control
for block in tool_response["content"]:
if block["type"] == "tool_result":
# Add cache_control to cache this tool result
block["cache_control"] = {"type": "ephemeral"}
# Append the modified response (this prevents auto-append of the original)
runner.append_messages(message, tool_response)
print(message.content)
```
Call `runner.generate_tool_call_response()` to get the tool result, modify it, and pass it to `runner.append_messages()` so the runner does not append the original.
Adding `cache_control` to tool results is particularly useful when tools return large amounts of data (such as document search results) that you want to cache for subsequent API calls. See [Prompt caching](../Guides/build-with-claude-prompt-caching.md) for more details on caching strategies.
## Streaming
Enable streaming to process each turn's response incrementally. Each iteration yields a stream object that you can iterate for events.
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
Set `stream=True` and use `get_final_message()` to get the accumulated message.
```python
client = anthropic.Anthropic()
# ...
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
tools=[calculate_sum],
messages=[{"role": "user", "content": "What is 15 + 27?"}],
stream=True,
)
# When streaming, the runner returns BetaMessageStream
for message_stream in runner:
for event in message_stream:
print("event:", event)
print("message:", message_stream.get_final_message())
print(runner.until_done())
```
## Next steps
[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)
Enforce JSON Schema compliance on Claude's tool inputs with grammar-constrained sampling.
[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)
Parse `tool_use` blocks, format `tool_result` responses, and handle errors with `is_error`.
[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)
Enable, format, and disable parallel tool calls, with message-history guidance and troubleshooting.
[Define tools](agents-and-tools-tool-use-implement-tool-use.md)
Specify tool schemas, write effective descriptions, and control when Claude calls your tools.
---
## Tool search tool - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-tool-search-tool.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Ftool-search-tool)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Tool search tool
Copy page
Scale to hundreds or thousands of tools by letting Claude search your tool catalog and load only the tools it needs.
Copy page
The tool search tool lets Claude work with hundreds or thousands of tools by discovering and loading them on demand. Instead of loading all tool definitions into the context window up front, Claude searches your tool catalog (including tool names, descriptions, argument names, and argument descriptions) and loads only the tools it needs.
Loading every tool definition up front causes two problems as a tool library grows:
- **Context bloat:** A typical multiserver setup (GitHub, Slack, Sentry, Grafana, and Splunk) can consume ~55k tokens in definitions before Claude does any work. Tool search typically reduces this by over 85 percent, loading only the 3–5 tools Claude needs for a given request.
- **Tool selection accuracy:** Claude's ability to pick the right tool degrades once you exceed 30–50 available tools. Because tool search loads only a focused set of relevant tools on demand, selection accuracy stays high even across thousands of tools.
For the models that support tool search, see [Model compatibility](#model-compatibility).
For background on the scaling challenges that tool search solves, see [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use). Tool search's on-demand loading is also an instance of the broader just-in-time retrieval principle described in [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).
Tool search runs as a server-side tool, but you can also implement your own client-side tool search. See [Custom tool search implementation](#custom-tool-search-implementation) for details.
Share feedback on this feature through the [feedback form](https://forms.gle/MhcGFFwLxuwnWTkYA).
To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
On Amazon Bedrock, server-side tool search is available only through the [InvokeModel API](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-runtime_example_bedrock-runtime_InvokeModel_AnthropicClaude_section.html), not the Converse API.
On [Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md), server-side tool search works identically to the Claude API. Claude Platform on AWS uses the Anthropic Messages API directly, so there is no InvokeModel or Converse distinction.
## Model compatibility
Both tool search variants are available on the following models:
[TABLE]
Claude Opus 4.1 and earlier models don't support the tool search tool.
## How tool search works
There are two tool search variants:
- **Regex** (`tool_search_tool_regex_20251119`): Claude constructs regex patterns to search for tools.
- **BM25** (`tool_search_tool_bm25_20251119`): Claude uses natural language queries to search for tools.
When you enable the tool search tool:
1. You include a tool search tool (for example, `tool_search_tool_regex_20251119` or `tool_search_tool_bm25_20251119`) in your `tools` list.
2. You provide every tool definition in the `tools` array and set `defer_loading: true` on the tools that shouldn't load up front. At least one tool, normally the tool search tool itself, must stay non-deferred.
3. Initially, Claude's context contains only the tool search tool and any non-deferred tools.
4. When Claude needs additional tools, it searches using a tool search tool.
5. The API runs the search and returns the matching tools as `tool_reference` blocks (up to 5 by default; Claude can set a `limit` in its search input).
6. The API automatically expands these references into full tool definitions.
7. Claude selects from the discovered tools and calls them.
## Quick start
The following example includes the tool search tool and two deferred tools:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=2048,
messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
tools=[
{"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
{
"name": "get_weather",
"description": "Get the weather at a specific location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
},
"required": ["location"],
},
"defer_loading": True,
},
{
"name": "search_files",
"description": "Search through files in the workspace",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string"},
"file_types": {"type": "array", "items": {"type": "string"}},
},
"required": ["query"],
},
"defer_loading": True,
},
],
)
print(response)
```
Claude searches the catalog, discovers `get_weather`, and calls it. The response ends with `stop_reason: "tool_use"`. Execute the discovered tool and return a `tool_result` as in [Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md). [Response format](#response-format) shows the blocks you get back and what to send next.
## Tool definition
The tool search tool has two variants:
JSON
```python
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
}
```
JSON
```python
{
"type": "tool_search_tool_bm25_20251119",
"name": "tool_search_tool_bm25"
}
```
**Regex variant query format: Python regex, not natural language**
With `tool_search_tool_regex_20251119`, Claude writes Python `re.search()` patterns, not natural language queries. Matching is case-insensitive. Common patterns include the following:
- `"weather"`: matches tool names and descriptions containing "weather"
- `"get_.*_data"`: matches tools such as `get_user_data` and `get_weather_data`
- `"database.*query|query.*database"`: matches either word order
Maximum pattern length: 200 characters
**BM25 variant query format: natural language**
With `tool_search_tool_bm25_20251119`, Claude searches with natural language queries. Maximum query length: 500 characters.
### Deferred tool loading
Mark tools for on-demand loading by adding `defer_loading: true`:
JSON
```python
{
"name": "get_weather",
"description": "Get current weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": { "type": "string" },
"unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
},
"required": ["location"]
},
"defer_loading": true
}
```
`defer_loading` controls what enters the context window, not what you send in the request:
- You still send every tool's full definition in the `tools` array on every request, including the deferred ones. The API needs them server-side to run the search and expand `tool_reference` blocks.
- Tools without `defer_loading` load into context immediately.
- Tools with `defer_loading: true` load only when Claude discovers them through search.
- Never set `defer_loading: true` on the tool search tool itself.
- Keep your 3–5 most frequently used tools non-deferred so Claude can call them without searching first.
The computer use and browser use toolsets (`computer_toolset_20260801` and `browser_toolset_20260801`) take `defer_loading` per member tool inside the entry's `configs` object, not on the entry itself; a request that sets it at the entry level is rejected. Because a toolset defers and expands as a unit, `defer_loading` must resolve to the same value on every enabled member, and when Claude discovers the toolset through search, every enabled member loads at once. See [Client toolsets](agents-and-tools-tool-use-tool-reference.md#client-toolsets) for the `configs` format.
Both tool search variants (`regex` and `bm25`) search tool names, descriptions, argument names, and argument descriptions.
Internally, the API excludes deferred tools from the system-prompt prefix. When Claude discovers a deferred tool through tool search, the API appends a `tool_reference` block inline in the conversation, then expands it into the full tool definition before passing it to Claude. The prefix is untouched, so prompt caching is preserved. The grammar for [strict mode](agents-and-tools-tool-use-strict-tool-use.md) (the rules that constrain tool-call output to match your schemas) builds from the full toolset, so `defer_loading` and strict mode compose without grammar recompilation.
## Response format
When Claude uses the tool search tool, the response includes the following block types:
JSON
```python
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll search for tools to help with the weather information."
},
{
"type": "server_tool_use",
"id": "srvtoolu_01ABC123",
"name": "tool_search_tool_regex",
"input": {
"pattern": "weather",
"limit": 10
}
},
{
"type": "tool_search_tool_result",
"tool_use_id": "srvtoolu_01ABC123",
"content": {
"type": "tool_search_tool_search_result",
"tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }]
}
},
{
"type": "text",
"text": "I found a weather tool. Let me get the weather for San Francisco."
},
{
"type": "tool_use",
"id": "toolu_01XYZ789",
"name": "get_weather",
"input": { "location": "San Francisco", "unit": "fahrenheit" }
}
],
"stop_reason": "tool_use"
}
```
### Understanding the response
- **`server_tool_use`:** Claude's call to the tool search tool. The search runs on Anthropic's servers. Never return a `tool_result` for its `srvtoolu_...` ID. The `input` holds the search (`pattern` for the regex variant, `query` for BM25) and may include an optional `limit`, an integer from 1 to 10,000 that caps how many matching tools the search returns (default: 5).
- **`tool_search_tool_result`:** the search results, in a nested `tool_search_tool_search_result` object. Keep it in the message history as is.
- **`tool_references`:** an array of `tool_reference` objects pointing to discovered tools. The API expands these for Claude. You never expand them yourself.
- **`tool_use`:** Claude's call to a discovered tool. Execute it and return a `tool_result` exactly as in standard tool use.
The API automatically expands `tool_reference` blocks into full tool definitions before showing them to Claude. You don't need to handle this expansion yourself, as long as you provide all matching tool definitions in the `tools` parameter.
### Continuing the conversation
On the next request, pass the assistant's content back unchanged, including the `server_tool_use` and `tool_search_tool_result` blocks. Add your `tool_result` for the discovered tool in a user message, and send the same `tools` array: the search tool plus every deferred definition. Don't return a `tool_result` for the `srvtoolu_...` ID: the API rejects the request. The API expands `tool_reference` blocks throughout the conversation history, so Claude can reuse discovered tools in later turns without re-searching. A search that matches nothing returns a `tool_search_tool_search_result` with an empty `tool_references` array, not an error.
## MCP integration
If your tools come from MCP servers through the [MCP connector](agents-and-tools-mcp-connector.md), you don't set `defer_loading` on individual tool definitions. Instead, set it once on the `mcp_toolset` entry's `default_config` for the whole server, or per tool in its `configs`. See [MCP toolset configuration](agents-and-tools-mcp-connector.md#mcp-toolset-configuration).
## Custom tool search implementation
You can implement your own tool search logic (for example, using embeddings or semantic search) by returning `tool_reference` blocks from a custom tool. When Claude calls your custom search tool, return a standard `tool_result` with `tool_reference` blocks in the content array:
JSON
```python
{
"type": "tool_result",
"tool_use_id": "toolu_your_tool_id",
"content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}
```
Every tool referenced must have a corresponding tool definition in the top-level `tools` parameter, normally with `defer_loading: true`. This lets you use search methods the built-in variants don't provide, such as embedding-based retrieval, and the API expands the returned `tool_reference` blocks the same way.
The `tool_search_tool_result` format shown in the [Response format](#response-format) section is the server-side format used internally by Anthropic's built-in tool search. For custom client-side implementations, always use the standard `tool_result` format with `tool_reference` content blocks as shown in the preceding example.
For a complete example using embeddings, see the [tool search with embeddings](https://platform.claude.com/cookbook/tool-use-tool-search-with-embeddings) recipe.
## Error handling
[Tool use examples](agents-and-tools-tool-use-implement-tool-use.md#providing-tool-use-examples) work with tool search: when Claude discovers a deferred tool, the API expands its `input_examples` along with its definition.
### HTTP errors (400 status)
These errors prevent the API from processing the request:
**All tools deferred:**
```python
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "At least one tool must have defer_loading=false. All tools cannot be deferred."
}
}
```
**Missing tool definition:**
```python
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Tool reference 'unknown_tool' not found in available tools"
}
}
```
### Tool result errors (200 status)
When a tool search operation fails during execution, the API returns a 200 response with the error in the body:
JSON
```python
{
"type": "tool_search_tool_result",
"tool_use_id": "srvtoolu_01ABC123",
"content": {
"type": "tool_search_tool_result_error",
"error_code": "invalid_tool_input",
"error_message": "Invalid regular expression pattern: missing ) at position 1"
}
}
```
The `error_code` field has four possible values:
- `invalid_tool_input`: the search input was invalid, for example a malformed regex pattern or a pattern over the 200-character limit
- `unavailable`: the search couldn't run, for example because it timed out or the service was unavailable
- `too_many_requests`: rate limit exceeded for tool search operations
- `execution_time_exceeded`: the search exceeded its execution time limit
### Common mistakes
### 400 error: all tools are deferred
**Cause:** You set `defer_loading: true` on every tool, including the tool search tool.
**Fix:** Remove `defer_loading` from the tool search tool:
```python
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
}
```
### 400 error: missing tool definition
**Cause:** A `tool_reference` points to a tool not in your `tools` array.
**Fix:** Ensure every tool that could be discovered has a complete definition:
```python
{
"name": "my_tool",
"description": "Full description here",
"input_schema": {
"type": "object"
},
"defer_loading": true
}
```
### Claude doesn't find expected tools
**Cause:** The regex pattern doesn't match the tool's name, description, argument names, or argument descriptions.
**Debugging steps:**
1. Check tool name, description, argument names, and argument descriptions. Claude searches all of these fields.
2. Test your pattern: `import re; re.search(r"your_pattern", "tool_name", re.IGNORECASE)`.
3. Matching is case-insensitive, so casing differences aren't the problem.
4. Claude uses broad patterns such as `".*weather.*"`, not exact matches.
**Tip:** Add common keywords to tool descriptions to improve discoverability.
## Prompt caching
To learn how `defer_loading` preserves prompt caching, see [Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md).
A tool with `defer_loading: true` can't also carry `cache_control`: the API returns a 400. Put the cache breakpoint on a non-deferred tool.
## Streaming
With streaming enabled, you'll receive tool search events as part of the stream:
```python
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "tool_search_tool_regex"}}
// Search pattern streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"pattern\":\"weather\"}"}}
// Pause while search executes
// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "tool_search_tool_search_result", "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}]}}}
// Claude continues with discovered tools
```
## Batch requests
You can include the tool search tool in the [Messages Batches API](../Guides/build-with-claude-batch-processing.md).
## Limits and best practices
### Limits
- **Maximum deferred tools:** 10,000 tools with `defer_loading: true` per request
- **Search results:** each search returns up to 5 matching tools by default; Claude can set `limit` in its search input to any integer from 1 to 10,000
- **Pattern and query length:** maximum 200 characters for regex patterns and 500 characters for BM25 queries
- **Model support:** see [Model compatibility](#model-compatibility)
### When to use tool search
Use tool search when any of the following apply:
- You have 10 or more tools available.
- Your tool definitions consume more than 10k tokens.
- Tool selection accuracy drops as your toolset grows.
- You aggregate multiple MCP servers (200+ tools).
- Your tool library grows over time.
Standard tool calling, without tool search, is a better fit when you have fewer than 10 tools, every tool is used in every request, or your tool definitions are small (less than 100 tokens total).
### Optimization tips
- Keep your 3–5 most frequently used tools non-deferred.
- Write clear, descriptive tool names and descriptions.
- Use consistent namespacing in tool names: prefix by service or resource (for example, `github_`, `slack_`) so one search matches the whole group.
- Use keywords in descriptions that match how users describe tasks.
- Add a system prompt section describing available tool categories: "You can search for tools to interact with Slack, GitHub, and Jira."
- Monitor which tools Claude discovers to refine your descriptions.
## Usage
Tool search isn't metered as a separate server tool. The response's `usage.server_tool_use` object has no tool search field, and the tool definitions that search loads into context count as input tokens like any other tool definition.
## Next steps
[Memory tool](agents-and-tools-tool-use-memory-tool.md)
Let Claude store and retrieve information across conversations by implementing the memory tool's file operations in your application.
[Tool reference](agents-and-tools-tool-use-tool-reference.md)
Directory of Anthropic-provided tools and reference for optional tool definition properties.
[MCP connector](agents-and-tools-mcp-connector.md)
Configure MCP toolsets with deferred loading.
[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)
Cache tool definitions across turns and understand what invalidates your cache.
[Define tools](agents-and-tools-tool-use-implement-tool-use.md)
Specify tool schemas, write effective descriptions, and control when Claude calls your tools.
---
## Tool use with prompt caching - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-tool-use-with-prompt-caching.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Ftool-use-with-prompt-caching)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tool infrastructure
# Tool use with prompt caching
Copy page
Cache tool definitions across turns and understand what invalidates your cache.
Copy page
This page covers prompt caching for tool definitions: where to place `cache_control` breakpoints, how `defer_loading` preserves your cache, and what invalidates it. For general prompt caching, see [Prompt caching](../Guides/build-with-claude-prompt-caching.md).
## cache_control on tool definitions
Place `cache_control: {"type": "ephemeral"}` on the last tool in your `tools` array. This caches the entire tool-definitions prefix, from the first tool through the marked breakpoint:
```python
{
"tools": [
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": { "type": "string" }
},
"required": ["location"]
}
},
{
"name": "get_time",
"description": "Get the current time in a given time zone",
"input_schema": {
"type": "object",
"properties": {
"timezone": { "type": "string" }
},
"required": ["timezone"]
},
"cache_control": { "type": "ephemeral" }
}
]
}
```
For `mcp_toolset`, the `cache_control` breakpoint lands on the last tool in the set. You don't control tool order within an MCP toolset, so place the breakpoint on the `mcp_toolset` entry itself and the API applies it to the final expanded tool.
The [computer use](agents-and-tools-tool-use-computer-use-tool.md) and [browser use](agents-and-tools-tool-use-browser-use-tool.md) toolset entries follow the same rule: place `cache_control` on the toolset entry itself, and the breakpoint lands after the toolset's definition. It isn't accepted inside a member's `configs` entry, because the toolset's members load as one definition. Within a [batch action](agents-and-tools-tool-use-computer-use-tool.md#batch-actions), a `cache_control` marker on any of the turn's member `tool_use` or `tool_result` blocks is accepted and takes effect at the end of that batch, so several markers in one batch act as a single breakpoint. Each marker still counts toward the request's limit of [four breakpoints](../Guides/build-with-claude-prompt-caching.md#when-to-use-multiple-breakpoints), so use one per turn.
## defer_loading and cache preservation
Deferred tools are not included in the system-prompt prefix. When the model discovers a deferred tool through [tool search](agents-and-tools-tool-use-tool-search-tool.md), the definition is appended inline as a `tool_reference` block in the conversation history. The prefix is untouched, so prompt caching is preserved.
This means adding tools dynamically through tool search does not break your cache. You can start a conversation with a small set of always-loaded tools (cached), let the model discover additional tools as needed, and keep the same cache hit across every turn.
`defer_loading` also acts independently of grammar construction for [strict mode](agents-and-tools-tool-use-strict-tool-use.md). The grammar builds from the full toolset regardless of which tools are deferred, so prompt caching and grammar caching are both preserved when tools load dynamically.
## What invalidates your cache
The cache follows a prefix hierarchy (`tools` → `system` → `messages`), so a change at one level invalidates that level and everything after it:
| Change | Invalidates |
|--------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Modifying tool definitions | Entire cache (tools, system, messages) |
| Toggling web search or citations | System and messages caches |
| Changing `tool_choice` | Messages cache |
| Changing `disable_parallel_tool_use` | Messages cache |
| Toggling images present/absent | Messages cache |
| Changing thinking parameters | Messages cache always; tool and system caches too on models that render the thinking configuration ahead of them ([details](../Guides/build-with-claude-thinking.md#thinking-and-prompt-caching)) |
| Changing `output_config.effort` | Same as thinking parameters; setting the model's default explicitly is equivalent to omitting it |
If you need to vary `tool_choice` mid-conversation, consider placing cache breakpoints before the variation point.
## Server tool results are cached automatically
When your request has prompt caching enabled and Claude uses a [server tool](agents-and-tools-tool-use-server-tools.md) such as web search, web fetch, or code execution, the API automatically places a cache breakpoint on the server tool result before running the next iteration of the agentic loop. This lets later iterations within the same request read the growing prefix from cache instead of reprocessing it.
This automatic breakpoint always uses the default 5-minute TTL, independent of any TTL you set on your own `cache_control` markers. In the response `usage`, these writes appear under `cache_creation.ephemeral_5m_input_tokens`, so you may see 5-minute cache writes even when every `cache_control` you set uses a 1-hour TTL.
This behavior only applies when your request already has at least one `cache_control` marker. Requests without prompt caching do not receive the automatic breakpoint.
## Per-tool interaction table
| Tool | Caching considerations |
|--------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Web search](agents-and-tools-tool-use-web-search-tool.md) | Enabling or disabling invalidates the system and messages caches |
| [Web fetch](agents-and-tools-tool-use-web-fetch-tool.md) | Enabling or disabling invalidates the system and messages caches |
| [Code execution](agents-and-tools-tool-use-code-execution-tool.md) | Container state is independent of prompt cache |
| [Tool search](agents-and-tools-tool-use-tool-search-tool.md) | Discovered tools load as `tool_reference` blocks, preserving prefix cache |
| [Computer use](agents-and-tools-tool-use-computer-use-tool.md) | Screenshot presence affects messages cache; `cache_control` goes on the toolset entry (see [cache_control on tool definitions](#cache-control-on-tool-definitions)) |
| [Browser use](agents-and-tools-tool-use-browser-use-tool.md) | Screenshot presence affects messages cache; `cache_control` goes on the toolset entry (see [cache_control on tool definitions](#cache-control-on-tool-definitions)) |
| [Text editor](agents-and-tools-tool-use-text-editor-tool.md) | Standard client tool, no special caching interaction |
| [Bash](agents-and-tools-tool-use-bash-tool.md) | Standard client tool, no special caching interaction |
| [Memory](agents-and-tools-tool-use-memory-tool.md) | Standard client tool, no special caching interaction |
## Next steps
[Prompt caching](../Guides/build-with-claude-prompt-caching.md)
Learn the full prompt caching model, including TTLs and pricing.
[Tool search](agents-and-tools-tool-use-tool-search-tool.md)
Load tools on demand without breaking your cache.
[Tool reference](agents-and-tools-tool-use-tool-reference.md)
Browse all available tools and their parameters.
---
## Troubleshooting tool use - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/troubleshooting-tool-use
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-troubleshooting-tool-use.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Ftroubleshooting-tool-use)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Troubleshooting tool use
Copy page
Fix the most common tool-use errors with symptom-to-fix diagnostic tables.
Copy page
Symptom-to-fix tables for the most common tool-use errors. Each fix cross-references the page that owns the feature.
## Claude calls the wrong tool
| Symptom | Likely cause | Fix |
|--------------------------------------------|----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Claude calls tool A when you wanted tool B | Description ambiguity | Sharpen descriptions. Differentiate tools by WHEN to use them, not only WHAT they do. See [Define tools](agents-and-tools-tool-use-implement-tool-use.md). |
| Claude never calls your tool | Tool name collision or overly-generic schema | Check for duplicate names across your tool list. Add `input_examples` to make the intended use concrete. |
| Claude calls with wrong parameter types | Model guessing at ambiguous schema | Add `strict: true` (if your schema is in the supported subset) or add `input_examples`. |
## Claude invents tool parameters
| Symptom | Likely cause | Fix |
|---------------------------------------------|-------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| Parameter that doesn't exist in your schema | Model over-generation without strict mode | Add `strict: true` if your schema is in the [supported subset](agents-and-tools-tool-use-strict-tool-use.md). |
| Parameter values outside your enum | Missing strict mode or too-large enum | Shrink the enum or add `input_examples` showing valid choices. |
## Parallel tool calls don't work
| Symptom | Likely cause | Fix |
|---------------------------------------------------------------|----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| Claude calls tools sequentially when parallel would be better | Message history formatting | Send multiple `tool_result` blocks in ONE user message, not one per turn. See [Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md). |
| `disable_parallel_tool_use` seems ignored | Set too late in the conversation | Must be set on the request that returns `tool_use`. Setting it on a later request has no effect on earlier tool calls. |
## Cache keeps invalidating
| Symptom | Likely cause | Fix |
|---------------------------------------------|-----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Every request is a cache miss | `tool_choice`, the thinking configuration, or `output_config.effort` varying between requests | Keep `tool_choice` stable or place the `cache_control` breakpoint before the variation point; hold the thinking configuration and effort level constant for the life of a cached conversation. See [Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md) and [Thinking and prompt caching](../Guides/build-with-claude-thinking.md#thinking-and-prompt-caching). |
| Adding a tool mid-conversation breaks cache | Tool prepended to the tools array | Use `defer_loading: true` with tool search to append the tool inline instead of modifying the array head. |
## Errors at request time
| Error | Cause | Fix |
|------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `tool_use ids were found without tool_result blocks immediately after` | Missing `tool_result` for some `tool_use` ids, or `tool_result` is not the first content block in the user message | Return one `tool_result` for every `tool_use` block in the assistant response. Put `tool_result` blocks before any text. See [Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md) and [Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md). |
| `was found without a corresponding _tool_result block` | The previous assistant turn has a `server_tool_use` block with no result block (most often, Claude called it alongside a client tool), and either your next user message ended that turn (for example, with text after the `tool_result` blocks) or the resume request no longer defines that server tool (the message then ends with `but no tool was provided`) | Send a user message containing only the `tool_result` blocks for the client `tool_use` ids and keep the same `tools` array. See [Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md#tool-use). |
| `Unsupported regex feature in pattern field: ...` | A `pattern` in a strict tool's `input_schema` uses a regex feature that strict mode can't compile, such as a backreference, a lookaround, a word boundary, or a large `{n,m}` range | Simplify the pattern. Anchored patterns with basic quantifiers, character classes, and groups are supported; see [JSON Schema limitations](../Guides/build-with-claude-structured-outputs.md#json-schema-limitations). |
| `All tools have defer_loading: true` | No tools visible to the model | At least one tool must be immediately loaded. The tool search tool itself must never have `defer_loading: true`. |
## Error: thinking blocks cannot be modified
If a request fails with a 400 `invalid_request_error` whose message contains `` `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified `` when continuing a conversation after a tool call, your application is altering the assistant's thinking blocks before sending them back. Send the entire assistant message back unchanged, then append your `tool_result`.
See [Thinking blocks cannot be modified](../Endpoints/errors.md#thinking-blocks-cannot-be-modified) for the full error and fix steps.
## Claude flags tool results as prompt injection
| Symptom | Likely cause | Fix |
|----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Claude refuses to act on a tool result, or asks the user to confirm instructions that came from it | Your own instructions are being delivered inside the `tool_result` content | Claude is trained to treat instructions inside tool results as potentially untrusted third-party content. Move your instructions out of the tool result: send them in a `user` turn after the `tool_result` block, or, on supported models, in a [mid-conversation system message](../Guides/build-with-claude-mid-conversation-system-messages.md). Keep the tool result to just the data. See [Mitigate jailbreaks and prompt injections](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-mitigate-jailbreaks.md#indirect-prompt-injection). |
## JSON escaping differences between model versions
| Symptom | Cause | Fix |
|----------------------------------------------------------|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| String comparison on tool inputs fails with newer models | Unicode and forward-slash escaping differs between model versions | Parse with `json.loads()` or `JSON.parse()`. Never do raw string matching on serialized input. |
## Next steps
[Define tools](agents-and-tools-tool-use-implement-tool-use.md)
Write schemas and descriptions that steer Claude toward the right tool.
[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)
Execute tools and return results in the required message format.
[Tool reference](agents-and-tools-tool-use-tool-reference.md)
Full directory of Anthropic-provided tools and their version strings.
---
## Web fetch tool - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-web-fetch-tool.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fweb-fetch-tool)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Web fetch tool
Copy page
Fetch and read content from specific URLs to augment Claude's context with live web content.
Copy page
To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
The web fetch tool allows Claude to retrieve full content from specified web pages and PDF documents.
The latest web fetch tool version (`web_fetch_20260318`) supports **dynamic filtering**: Claude can write and execute code to filter fetched content before it reaches the context window, keeping only relevant information and discarding the rest. This reduces token consumption while maintaining response quality. Dynamic filtering is available with Claude 4.6 and later models and [Claude Mythos Preview](../../22-Safety-Policy/glasswing.md). `web_fetch_20260318` also adds [response inclusion](#response-inclusion) control for agentic workflows. The previous versions (`web_fetch_20260309` for dynamic filtering and [cache bypass](#cache-bypass), `web_fetch_20260209` for dynamic filtering only, `web_fetch_20250910` for basic fetch) remain available.
Web fetch (with and without dynamic filtering) is available on the Claude API, [Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md), and [Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md). On Microsoft Foundry, deployments [hosted on Azure](../Guides/build-with-claude-claude-in-microsoft-foundry.md#additional-features-not-supported-when-hosted-on-azure) support only the basic web fetch tool (`web_fetch_20250910`, without dynamic filtering). Deployments hosted on Anthropic support all versions. Web fetch is not currently available on Amazon Bedrock or Google Cloud.
For [Claude Mythos Preview](../../22-Safety-Policy/glasswing.md), web fetch is available on the Claude API and Microsoft Foundry. It is not currently available for Mythos Preview on Amazon Bedrock or Google Cloud.
Use the [feedback form](https://forms.gle/NhWcgmkcvPCMmPE86) to provide feedback on the quality of the model responses, the API itself, or the quality of the documentation.
For Zero Data Retention eligibility and the `allowed_callers` workaround, see [Server tools](agents-and-tools-tool-use-server-tools.md#zdr-and-allowed-callers).
Enabling the web fetch tool in environments where Claude processes untrusted input alongside sensitive data poses data exfiltration risks. Only use this tool in trusted environments or when handling non-sensitive data.
To minimize exfiltration risks, Claude cannot fetch URLs that appear only in its own output. Claude can only fetch URLs that have previously appeared in the conversation: URLs in user messages, URLs in client-side tool results, and URLs from previous web search or web fetch results (see [URL validation](#url-validation)). Claude also cannot fetch a URL that appears to contain a credential, such as an API key or a password, unless that credential appears in the system prompt or in the text of a user message.
However, there is still residual risk that you should carefully consider when using this tool.
If data exfiltration is a concern, consider:
- Disabling the web fetch tool entirely
- Using the `max_uses` parameter to limit the number of requests
- Using the `allowed_domains` parameter to restrict to known safe domains
- Using the `url_sources` parameter to stop client-side tool results from counting as a source (see [URL sources](#url-sources))
For model support, see the [Tool reference](agents-and-tools-tool-use-tool-reference.md).
## How web fetch works
Web fetch is a [server tool](agents-and-tools-tool-use-server-tools.md): the API fetches the content during the request and inserts the results into the conversation. You don't run anything or return a `tool_result`. The exception is when Claude calls web fetch and one of your client tools in the same group of parallel tool calls: the API returns the response with `stop_reason: "tool_use"` before that fetch has run, then runs the fetch when you send back the client `tool_result` blocks. See [Mixing server tools and client tools in one turn](agents-and-tools-tool-use-server-tools.md#mixing-server-tools-and-client-tools-in-one-turn).
When you add the web fetch tool to your API request:
1. Claude determines when to fetch content based on the prompt and available URLs.
2. The API retrieves the full text content from the specified URL.
3. For PDFs, the API returns the content as base64-encoded data and processes it like a directly attached PDF document.
4. Claude analyzes the fetched content and provides a response with optional citations.
The web fetch tool currently does not support websites dynamically rendered with JavaScript. For pages that need a real browser (JavaScript rendering, clicking, or filling forms), consider the [browser use tool](agents-and-tools-tool-use-browser-use-tool.md), a client tool where your application drives the browser and returns page text or screenshots to Claude as tool results.
### When Claude fetches
Claude fetches when the request points at a specific page or document:
- A URL is provided in the conversation (or a previous tool result)
- The user names a specific resource (a particular article, README, pricing page, or documentation section) without a URL, and the [web search tool](agents-and-tools-tool-use-web-search-tool.md) is also enabled so Claude can locate it first (see [Combined search and fetch](#combined-search-and-fetch))
Claude does **not** fetch for general-knowledge or open-ended questions that don't reference a specific page. "Summarize this article: ``" triggers a fetch. "What are best practices for REST API design?" is answered directly.
### Dynamic filtering
Fetching full web pages and PDFs can quickly consume tokens, especially when only specific information is needed from large documents. With `web_fetch_20260209` or later, Claude can write and execute code to filter the fetched content before loading it into context.
This dynamic filtering is particularly useful for:
- Extracting specific sections from long documents
- Processing structured data from web pages
- Filtering relevant information from PDFs
- Reducing token costs when working with large documents
Dynamic filtering runs on the [code execution tool](agents-and-tools-tool-use-code-execution-tool.md), which the API enables automatically for the request. You don't need to add the code execution tool to the `tools` array.
To enable dynamic filtering, use `web_fetch_20260209` or any later version. The following examples use `web_fetch_20260318`:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Fetch the content at https://example.com/research-paper and extract the key findings.",
}
],
tools=[{"type": "web_fetch_20260318", "name": "web_fetch"}],
)
print(response)
```
## How to use web fetch
Provide the web fetch tool in your API request:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Please analyze the content at https://example.com/article",
}
],
tools=[{"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5}],
)
print(response)
```
## Tool definition
The web fetch tool supports the following parameters:
JSON
```python
{
"type": "web_fetch_20250910",
"name": "web_fetch",
// Optional: Limit the number of fetches per request
"max_uses": 10,
// Optional: Only fetch from these domains
"allowed_domains": ["example.com", "docs.example.com"],
// Optional: Never fetch from these domains (cannot be combined with allowed_domains)
"blocked_domains": ["private.example.com"],
// Optional: Don't fetch URLs that appear only in client-side tool results
"url_sources": {
"client_tool_results": { "type": "none" }
},
// Optional: Enable citations for fetched content
"citations": {
"enabled": true
},
// Optional: Maximum content length in tokens
"max_content_tokens": 100000
}
```
Later tool versions add two more optional parameters: `use_cache` requires `web_fetch_20260309` or later (see [Cache bypass](#cache-bypass)), and `response_inclusion` requires `web_fetch_20260318` or later (see [Response inclusion](#response-inclusion)).
### Max uses
The `max_uses` parameter limits the number of web fetches performed. Failed fetches count against the limit. If Claude attempts more fetches than allowed, the `web_fetch_tool_result` is an error with the `max_uses_exceeded` error code. There is currently no default limit.
### Domain filtering
For domain filtering with `allowed_domains` and `blocked_domains`, see [Server tools](agents-and-tools-tool-use-server-tools.md#domain-filtering).
On [Claude Managed Agents](../Other/managed-agents-overview.md), set these fields on the `web_fetch` entry of the agent toolset, where each listed domain must be a plain hostname with no path; see [Restrict web search and web fetch domains](../Other/managed-agents-tools-web-restrictions.md).
### Content limits
The `max_content_tokens` parameter limits the amount of content included in the context. If the fetched content exceeds this limit, the tool truncates it. This helps control token usage when fetching large documents. The limit applies to text content, not to binary content such as PDFs.
The `max_content_tokens` parameter limit is approximate. The actual number of input tokens used can vary by a small amount.
On Claude Managed Agents, the `web_fetch` entry of the agent toolset also accepts `max_content_tokens`; see the [web tool settings](../Other/managed-agents-tools-web-restrictions.md#settings).
### Cache bypass
Requires `web_fetch_20260309` or later (including `web_fetch_20260318`).
The `use_cache` parameter controls whether cached content may be returned. Set `"use_cache": false` to bypass the cache and fetch fresh content. The default is `true`. Only disable caching when the user explicitly requests fresh content or when fetching rapidly changing sources, because bypassing the cache increases latency.
```python
{
"tools": [
{
"type": "web_fetch_20260309",
"name": "web_fetch",
"use_cache": false
}
]
}
```
### Response inclusion
Requires `web_fetch_20260318` or later.
The `response_inclusion` parameter controls how fetch result blocks appear in the API response when the result was consumed by a completed [code execution](agents-and-tools-tool-use-code-execution-tool.md) call in the same turn. Set `"response_inclusion": "excluded"` to drop those nested `server_tool_use` and result block pairs entirely from the response, reducing output token costs for agentic workflows that don't need to echo raw page content back to the client. The default is `"full"`. Results from direct calls, or from code execution calls that paused before completing, are always returned in full so they can be sent back on the next turn.
```python
{
"tools": [
{
"type": "web_fetch_20260318",
"name": "web_fetch",
"response_inclusion": "excluded"
}
]
}
```
### Citations
Unlike web search where citations are always enabled, citations are optional for web fetch and disabled by default. Set `"citations": {"enabled": true}` to enable Claude to cite specific passages from fetched documents.
When displaying API outputs directly to end users, include citations to the original source. If you are making modifications to API outputs, including by reprocessing or combining them with your own material before displaying them to end users, display citations as appropriate based on consultation with your legal team.
## Response
Here's an example response structure:
Output
```python
{
"role": "assistant",
"content": [
// 1. Claude's decision to fetch
{
"type": "text",
"text": "I'll fetch the content from the article to analyze it."
},
// 2. The fetch request
{
"type": "server_tool_use",
"id": "srvtoolu_01234567890abcdef",
"name": "web_fetch",
"input": {
"url": "https://example.com/article"
}
},
// 3. Fetch results
{
"type": "web_fetch_tool_result",
"tool_use_id": "srvtoolu_01234567890abcdef",
"content": {
"type": "web_fetch_result",
"url": "https://example.com/article",
"content": {
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "Full text content of the article..."
},
"title": "Article Title",
"citations": { "enabled": true }
},
"retrieved_at": "2025-08-25T10:30:00Z"
}
},
// 4. Claude's analysis with citations (if enabled)
{
"text": "Based on the article, ",
"type": "text"
},
{
"text": "the main argument presented is that artificial intelligence will transform healthcare",
"type": "text",
"citations": [
{
"type": "char_location",
"document_index": 0,
"document_title": "Article Title",
"start_char_index": 1234,
"end_char_index": 1456,
"cited_text": "Artificial intelligence is poised to revolutionize healthcare delivery..."
}
]
}
],
"id": "msg_a930390d3a",
"usage": {
"input_tokens": 25039,
"output_tokens": 931,
"server_tool_use": {
"web_fetch_requests": 1
}
},
"stop_reason": "end_turn"
}
```
### Fetch results
Fetch results include:
- `url`: The URL that was fetched
- `content`: A document block containing the fetched content
- `retrieved_at`: Timestamp when the content was retrieved
The web fetch tool caches results to improve performance and reduce redundant requests. The content returned may not always reflect the latest version available at the URL. The cache behavior is managed automatically and may change over time to optimize for different content types and usage patterns. To fetch fresh content, set `"use_cache": false` (see [Cache bypass](#cache-bypass)).
For PDF documents, content is returned as base64-encoded data:
Output
```python
{
"type": "web_fetch_tool_result",
"tool_use_id": "srvtoolu_02",
"content": {
"type": "web_fetch_result",
"url": "https://example.com/paper.pdf",
"content": {
"type": "document",
"source": {
"type": "base64",
"media_type": "application/pdf",
"data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmo..."
},
"citations": { "enabled": true }
},
"retrieved_at": "2025-08-25T10:30:02Z"
}
}
```
### Errors
When the web fetch tool encounters an error, the Claude API returns a 200 (success) response with the error represented in the response body. Claude sees the error result and continues the turn. For example:
Output
```python
{
"type": "web_fetch_tool_result",
"tool_use_id": "srvtoolu_a93jad",
"content": {
"type": "web_fetch_tool_result_error",
"error_code": "url_not_accessible"
}
}
```
These are the possible error codes:
- `invalid_tool_input`: Invalid tool input, such as a malformed URL or a non-HTTP(S) scheme
- `url_too_long`: URL exceeds maximum length (250 characters)
- `url_not_allowed`: URL blocked by domain filtering rules (including your organization's settings) or by Anthropic-side restrictions, such as private addresses, `robots.txt`, and URLs that appear to contain a credential you did not provide
- `url_not_in_prior_context`: URL did not appear earlier in the conversation, or appeared only in sources that `url_sources` excludes (see [URL validation](#url-validation))
- `url_not_accessible`: Failed to fetch content (HTTP error)
- `too_many_requests`: Rate limit exceeded
- `unsupported_content_type`: Content type not supported (only text, HTML, and PDF)
- `max_uses_exceeded`: Maximum web fetch tool uses exceeded
- `unavailable`: An internal error occurred
## URL validation
For security reasons, the web fetch tool can only fetch URLs that have previously appeared in the conversation context. This includes:
- URLs in user messages
- URLs in client-side tool results
- URLs from previous web search or web fetch results
The tool cannot fetch URLs that appear only in Claude's own output or only in the system prompt. To make a URL from the system prompt fetchable, also include it in a user message. Results of other server-side tools, such as [code execution](agents-and-tools-tool-use-code-execution-tool.md), the [MCP connector](agents-and-tools-mcp-connector.md), or [tool search](agents-and-tools-tool-use-tool-search-tool.md), are not an allowed source either. By default, client-side tool results are an allowed source even when they echo text that Claude produced (for example, a command that prints its input, or an error message that quotes it).
The tool also refuses a URL that appears to contain a credential, such as an API key or a password, unless that credential appears in the system prompt or in the text of a user message. A credential that appears only in a tool result does not count. The result is a `url_not_allowed` error. To fetch such a URL, include it in a user message.
### URL sources
Works with `web_fetch_20250910`, `web_fetch_20260209`, `web_fetch_20260309`, and `web_fetch_20260318`.
The optional `url_sources` parameter lets you turn off any of the three allowed sources, or limit tool results to certain tools. It has one key per source, and each key defaults to `{"type": "all"}`:
- `user_input`: URLs in user messages. Its `type` is `"all"` or `"none"`.
- `client_tool_results`: URLs in client-side tool results. Its `type` is `"all"`, `"none"`, or an `"only"` or `"except"` filter that names tools, as in the following example.
- `server_tool_results`: URLs from previous web search or web fetch results. It takes the same values, and its filters name `web_search` or `web_fetch`.
For example, a tool that runs code Claude wrote returns whatever that code prints, including any URL Claude put in it. To stop that tool's results from counting as a source, name it in an `"except"` filter:
```python
{
"tools": [
{
"type": "web_fetch_20260318",
"name": "web_fetch",
"url_sources": {
"client_tool_results": {
"type": "except",
"tools": [{ "type": "tool_reference", "name": "run_code" }]
}
}
},
{
"name": "run_code",
"description": "Run Python code and return its output",
"input_schema": {
"type": "object",
"properties": { "code": { "type": "string" } },
"required": ["code"]
}
}
]
}
```
A filter lists tools as `tool_reference` objects. Each name must match a tool in the request's `tools` array: a client tool for `client_tool_results`, or a server tool for `server_tool_results`. Otherwise, the request fails with an error. Under `"except"`, a tool you add to `tools` later counts as a source. Under `"only"`, it doesn't.
Client-side tools other than `run_code` can also return text Claude wrote, for example in an error message that quotes it. To exclude all client-side tool results, set `client_tool_results` to `{"type": "none"}`.
If a URL appeared only in sources that `url_sources` excludes, fetching it returns the `url_not_in_prior_context` error.
## Combined search and fetch
When both the web search and web fetch tools are enabled, and the user names a specific page or document without providing a URL (for example, "read the README from the anthropics/anthropic-sdk-python repository"), Claude uses web search to locate it, then fetches the result. The following example asks for a search and an analysis in one request:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Find recent articles about quantum computing and analyze the most relevant one in detail",
}
],
tools=[
{"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
{
"type": "web_fetch_20250910",
"name": "web_fetch",
"max_uses": 5,
"citations": {"enabled": True},
},
],
)
print(response)
```
In this workflow, Claude:
1. Uses web search to find relevant articles.
2. Selects the most promising results.
3. Uses web fetch to retrieve full content.
4. Provides detailed analysis with citations.
## Prompt caching
To cache tool definitions across turns, see [Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md).
## Streaming
With streaming enabled, fetch events are part of the stream with a pause during content retrieval:
Output
```python
event: message_start
data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}
event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}
// Claude's decision to fetch
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_fetch"}}
// Fetch URL streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}
// Pause while fetch executes
// Fetch results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "web_fetch_result", "url": "https://example.com/article", "content": {"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "Article content..."}}}}}
// Claude's response continues...
```
## Batch requests
You can include the web fetch tool in the [Messages Batches API](../Guides/build-with-claude-batch-processing.md). Web fetch tool calls through the Messages Batches API are priced the same as those in regular Messages API requests.
## Usage and pricing
Web fetch usage has **no additional charges** beyond standard token costs:
```python
{
"usage": {
"input_tokens": 25039,
"output_tokens": 931,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"server_tool_use": {
"web_fetch_requests": 1
}
}
}
```
The web fetch tool is available on the Claude API at **no additional cost**. You only pay standard token costs for the fetched content that becomes part of your conversation context.
To protect against inadvertently fetching large content that would consume excessive tokens, use the `max_content_tokens` parameter to set appropriate limits based on your use case and budget considerations.
Example token usage for typical content:
- Average web page (10 kB): ~2,500 tokens
- Large documentation page (100 kB): ~25,000 tokens
- Research paper PDF (500 kB): ~125,000 tokens
## Next steps
[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)
Run Python and bash code in a sandboxed container to analyze data, generate files, and iterate on solutions.
[Server tools](agents-and-tools-tool-use-server-tools.md)
Work with Anthropic-executed tools: server_tool_use blocks, pause_turn continuation, and domain filtering.
[Tool reference](agents-and-tools-tool-use-tool-reference.md)
Directory of Anthropic-provided tools and reference for optional tool definition properties.
---
## Web search tool - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool
Path: 04-API-Reference/Agents-Tools/agents-and-tools-tool-use-web-search-tool.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [SDKs, CLI, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Ftool-use%2Fweb-search-tool)
SearchCtrlK
First steps
[Intro to Claude](../../01-Getting-Started/intro.md)[Get your API key](../Other/get-api-key.md)[Quickstart](../../01-Getting-Started/get-started.md)[Authentication](../Other/manage-claude-authentication.md)
Building with Claude
[Features overview](../Guides/build-with-claude-overview.md)[Using the Messages API](../Guides/build-with-claude-working-with-messages.md)[Stop reasons and fallback](../Guides/build-with-claude-handling-stop-reasons.md)[Refusals and fallback](../Guides/build-with-claude-refusals-and-fallback.md)[Fallback credit](../Guides/build-with-claude-fallback-credit.md)
Model capabilities
[Effort](../Guides/build-with-claude-effort.md)[Task budgets (beta)](../Guides/build-with-claude-task-budgets.md)[Fast mode](../Guides/build-with-claude-fast-mode.md)[Structured outputs](../Guides/build-with-claude-structured-outputs.md)[Citations](../Guides/build-with-claude-citations.md)[Streaming Messages](../Guides/build-with-claude-streaming.md)[Batch processing](../Guides/build-with-claude-batch-processing.md)[Search results](../Guides/build-with-claude-search-results.md)[Streaming refusals](../Test-Evaluate/test-and-evaluate-strengthen-guardrails-handle-streaming-refusals.md)[Multilingual support](../Guides/build-with-claude-multilingual-support.md)[Embeddings](../Guides/build-with-claude-embeddings.md)
[Thinking](../Guides/build-with-claude-thinking.md)
Tools
[Overview](agents-and-tools-tool-use-overview.md)[How tool use works](agents-and-tools-tool-use-how-tool-use-works.md)[Tutorial: Build a tool-using agent](agents-and-tools-tool-use-build-a-tool-using-agent.md)[Define tools](agents-and-tools-tool-use-implement-tool-use.md)[Handle tool calls](agents-and-tools-tool-use-handle-tool-calls.md)[Parallel tool use](agents-and-tools-tool-use-parallel-tool-use.md)[Tool Runner (SDK)](agents-and-tools-tool-use-tool-runner.md)[Strict tool use](agents-and-tools-tool-use-strict-tool-use.md)[Server tools](agents-and-tools-tool-use-server-tools.md)[Web search tool](agents-and-tools-tool-use-web-search-tool.md)[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)[Code execution tool](agents-and-tools-tool-use-code-execution-tool.md)[Advisor tool](agents-and-tools-tool-use-advisor-tool.md)[Tool search tool](agents-and-tools-tool-use-tool-search-tool.md)[Memory tool](agents-and-tools-tool-use-memory-tool.md)[Bash tool](agents-and-tools-tool-use-bash-tool.md)[Text editor tool](agents-and-tools-tool-use-text-editor-tool.md)[Browser and computer use (SDK)](agents-and-tools-tool-use-browser-use-sdk.md)[Computer use tool](agents-and-tools-tool-use-computer-use-tool.md)[Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)[Troubleshooting](agents-and-tools-tool-use-troubleshooting-tool-use.md)
Tool infrastructure
[Tool reference](agents-and-tools-tool-use-tool-reference.md)[Manage tool context](agents-and-tools-tool-use-manage-tool-context.md)[Tool combinations](agents-and-tools-tool-use-tool-combinations.md)[Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md)[Programmatic tool calling](agents-and-tools-tool-use-programmatic-tool-calling.md)[Fine-grained tool streaming](agents-and-tools-tool-use-fine-grained-tool-streaming.md)
Context management
[Context windows](../Guides/build-with-claude-context-windows.md)[Context editing](../Guides/build-with-claude-context-editing.md)[Prompt caching](../Guides/build-with-claude-prompt-caching.md)[Mid-conversation system messages and tool changes](../Guides/build-with-claude-mid-conversation-system-messages.md)[Build an orchestration mode](../Guides/build-with-claude-mid-conversation-effort-example.md)[Cache diagnostics](../Guides/build-with-claude-cache-diagnostics.md)[Token counting](../Guides/build-with-claude-token-counting.md)
[Compaction](../Guides/build-with-claude-compaction.md)
Working with files
[Files API](../Guides/build-with-claude-files.md)[PDF support](../Guides/build-with-claude-pdf-support.md)
[Images and vision](../Guides/build-with-claude-vision.md)
Skills
[Overview](agents-and-tools-agent-skills-overview.md)[Quickstart](agents-and-tools-agent-skills-quickstart.md)[Best practices](agents-and-tools-agent-skills-best-practices.md)[Skills for enterprise](agents-and-tools-agent-skills-enterprise.md)[Skills in the API](../Guides/build-with-claude-skills-guide.md)
MCP
[Remote MCP servers](agents-and-tools-remote-mcp-servers.md)[MCP connector](agents-and-tools-mcp-connector.md)
[MCP tunnels](agents-and-tools-mcp-tunnels-overview.md)
Claude on cloud platforms
[Amazon Bedrock (Opus 4.7 and later)](../Guides/build-with-claude-claude-in-amazon-bedrock.md)[Amazon Bedrock (Opus 4.6 and earlier)](../Guides/build-with-claude-claude-on-amazon-bedrock-legacy.md)[Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md)[Google Cloud](../Guides/build-with-claude-claude-on-vertex-ai.md)[Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md)
[Console](../Other/playground.md)
[Messages](../../01-Getting-Started/intro.md)Tools
# Web search tool
Copy page
Give Claude access to current web content with cited sources, optional dynamic filtering, and domain controls.
Copy page
To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](../Other/manage-claude-api-and-data-retention.md).
The web search tool gives Claude direct access to real-time web content, allowing it to answer questions with up-to-date information beyond its knowledge cutoff. The response includes citations for sources drawn from search results.
With `web_search_20260209` and later versions, Claude can write and run code that filters the search results before they reach the context window (**dynamic filtering**), keeping only relevant information. Dynamic filtering is available with Claude 4.6 and later models and [Claude Mythos Preview](../../22-Safety-Policy/glasswing.md).
Three versions of the web search tool are available:
- `web_search_20250305`: basic web search
- `web_search_20260209`: adds [dynamic filtering](#dynamic-filtering)
- `web_search_20260318`: adds [response inclusion](#response-inclusion) control for agentic workflows
The examples on this page use `web_search_20250305` for basic search and `web_search_20260318` for dynamic filtering.
For [Claude Mythos Preview](../../22-Safety-Policy/glasswing.md), web search is supported on the Claude API, Google Cloud, and Microsoft Foundry. Web search is not available for Mythos Preview on Amazon Bedrock or [Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md).
For web search's Zero Data Retention eligibility and the related `allowed_callers` configuration, see [Server tools](agents-and-tools-tool-use-server-tools.md#zdr-and-allowed-callers).
For model support, see the [Tool reference](agents-and-tools-tool-use-tool-reference.md).
To check whether a model accepts web search before you send a request, read its `capabilities.server_tools.web_search.supported` value from the Models API. [Using the Models API](../../20-Models/about-claude-models-overview.md#using-the-models-api) describes the field.
## How web search works
When you add the web search tool to your API request:
1. Claude determines when to search based on the prompt.
2. The API runs the searches and provides Claude with the results. This process can repeat multiple times throughout a single request.
3. At the end of its turn, Claude provides a final response with cited sources.
### When Claude searches
Claude searches when the request depends on information that is current, changing, or outside its training data:
- Recent events, news, or announcements
- Current prices, rates, scores, or statistics
- Information about specific organizations, people, or products that might have changed
- Explicit requests to search or look something up
Claude answers directly without searching when the request draws on stable knowledge:
- Established facts, math, science fundamentals, or coding concepts
- Creative writing or brainstorming
- Analysis of content already provided in the conversation
- Conversational turns and greetings
Triggering is steerable through your system prompt: you can encourage Claude to search more readily or to prefer answering directly. For a hard constraint, use `max_uses` to cap the number of searches for each request.
### Dynamic filtering
With basic web search, every search result is loaded into Claude's context window, and much of that content can be irrelevant to the request. With `web_search_20260209` or later, Claude instead writes and runs code that filters the results first, so only relevant content reaches the context window. This reduces token use on search-heavy requests.
Dynamic filtering runs web search from inside [code execution](agents-and-tools-tool-use-code-execution-tool.md): on `web_search_20260209` and later, the tool's `allowed_callers` field defaults to `["code_execution_20260120"]`, and when dynamic filtering runs, the API provisions the code execution it needs for the request automatically. You don't need to add the code execution tool to `tools` yourself. There are no additional charges for code execution calls made this way beyond the standard token costs.
To call web search directly, without dynamic filtering, set `allowed_callers: ["direct"]`. Models that don't support programmatic tool calling require this setting. Without it, the API returns a 400 error that tells you to set it.
The web search tool (with and without dynamic filtering) is available on the Claude API, [Claude Platform on AWS](../Guides/build-with-claude-claude-platform-on-aws.md), and [Microsoft Foundry](../Guides/build-with-claude-claude-in-microsoft-foundry.md). On Microsoft Foundry, deployments [hosted on Azure](../Guides/build-with-claude-claude-in-microsoft-foundry.md#additional-features-not-supported-when-hosted-on-azure) support only the basic web search tool (`web_search_20250305`, without dynamic filtering). Deployments hosted on Anthropic support all versions. On Google Cloud, only the basic web search tool (without dynamic filtering) is available. Web search is not available on Amazon Bedrock.
The following examples use `web_search_20260318`:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.",
}
],
tools=[{"type": "web_search_20260318", "name": "web_search"}],
)
print(response)
```
## How to use web search
Web search is enabled for your organization unless an administrator has disabled it in the [Claude Console](../Other/playground.md), where they can also restrict which domains it searches. If it's disabled, a request that includes the tool fails with a 400 `invalid_request_error` that says web search is not enabled, rather than an [error code](#errors) inside a search result.
These organization-level settings in the Claude Console apply to Messages API requests only. [Claude Managed Agents](../Other/managed-agents-overview.md) sessions use the per-tool `allowed_domains` and `blocked_domains` lists on the agent toolset instead; see [Restrict web search and web fetch domains](../Other/managed-agents-tools-web-restrictions.md). For a session in a cloud environment with `limited` networking, the environment's `allowed_hosts` also applies to `web_search` and `web_fetch`; see [Networking](../Other/managed-agents-environments.md#networking). The per-tool lists restrict these tools further, within the hosts that `allowed_hosts` allows.
Provide the web search tool in your API request:
cURL
CLI
Python
TypeScript
C#
Go
Java
PHP
Ruby
Python
```python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "What's the weather in NYC?"}],
tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)
```
## Tool definition
The web search tool supports the following parameters:
JSON
```python
{
"type": "web_search_20250305",
"name": "web_search",
// Optional: Limit the number of searches per request
"max_uses": 5,
// Optional: Only include results from these domains.
// Use allowed_domains or blocked_domains, not both.
"allowed_domains": ["example.com", "trusteddomain.org"],
// Optional: Never include results from these domains
"blocked_domains": ["untrustedsource.com"],
// Optional: Localize search results
"user_location": {
"type": "approximate",
"city": "San Francisco",
"region": "California",
"country": "US",
"timezone": "America/Los_Angeles"
}
}
```
All web search tool versions accept `allowed_callers`, which controls whether Claude calls web search directly or from code execution through [dynamic filtering](#dynamic-filtering). On `web_search_20260209` and later it defaults to `["code_execution_20260120"]` instead of `["direct"]`. See [Server tools](agents-and-tools-tool-use-server-tools.md#zdr-and-allowed-callers) for how to configure it. `web_search_20260318` and later also accept [`response_inclusion`](#response-inclusion).
### Max uses
The `max_uses` parameter limits the number of searches performed. If Claude attempts more searches than allowed, the `web_search_tool_result` is an error with the `max_uses_exceeded` error code.
Simple factual queries typically use 1–3 searches; comparative or multientity research can use 10 or more. For guidance on choosing a value, see [Server tools](agents-and-tools-tool-use-server-tools.md).
### Domain filtering
Provide `allowed_domains` or `blocked_domains`, not both. If a request includes both, the API returns a 400 error. Entries are bare domains with an optional path, for example `example.com` or `example.com/blog`, without a scheme.
For the full domain filtering rules, see [Domain filtering](agents-and-tools-tool-use-server-tools.md#domain-filtering) in the Server tools guide.
On [Claude Managed Agents](../Other/managed-agents-overview.md), set these fields on the `web_search` entry of the agent toolset; see [Restrict web search and web fetch domains](../Other/managed-agents-tools-web-restrictions.md).
### Localization
The `user_location` parameter allows you to localize search results based on a user's location. Provide at least one of `city`, `region`, `country`, or `timezone`.
- `type`: The type of location (must be `approximate`)
- `city`: The city name
- `region`: The region or state
- `country`: The two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. The API rejects unsupported country codes with a 400 error.
- `timezone`: The [IANA timezone ID](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
On Claude Managed Agents, the `web_search` entry of the agent toolset accepts a `user_location` object with the same fields. The API rejects an unsupported `country` code with a 400 error when you create or update the agent, or when you create or update a session that supplies the setting. See the [web tool settings](../Other/managed-agents-tools-web-restrictions.md#settings).
### Response inclusion
Requires `web_search_20260318` or later.
The `response_inclusion` parameter controls how search result blocks appear in the API response when the result was consumed by a completed [code execution](agents-and-tools-tool-use-code-execution-tool.md) call in the same turn. Set `"response_inclusion": "excluded"` to drop those nested `server_tool_use` and result block pairs entirely from the response, reducing output token costs for agentic workflows that don't need to echo raw search content back to the client. The default is `"full"`. Results from direct calls, or from code execution calls that paused before completing, are always returned in full so they can be sent back on the next turn.
JSON
```python
{
"tools": [
{
"type": "web_search_20260318",
"name": "web_search",
"response_inclusion": "excluded"
}
]
}
```
## Response
Here's an example response structure:
Output
```python
{
"role": "assistant",
"content": [
// 1. Claude's decision to search
{
"type": "text",
"text": "I'll search for when Claude Shannon was born."
},
// 2. The search query used
{
"type": "server_tool_use",
"id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
"name": "web_search",
"input": {
"query": "claude shannon birth date"
}
},
// 3. Search results
{
"type": "web_search_tool_result",
"tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
"content": [
{
"type": "web_search_result",
"url": "https://en.wikipedia.org/wiki/Claude_Shannon",
"title": "Claude Shannon - Wikipedia",
"encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
"page_age": "April 30, 2025"
}
]
},
{
"text": "Based on the search results, ",
"type": "text"
},
// 4. Claude's response with citations
{
"text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan",
"type": "text",
"citations": [
{
"type": "web_search_result_location",
"url": "https://en.wikipedia.org/wiki/Claude_Shannon",
"title": "Claude Shannon - Wikipedia",
"encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..",
"cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..."
}
]
}
],
"id": "msg_a930390d3a",
"usage": {
"input_tokens": 6039,
"output_tokens": 931,
"server_tool_use": {
"web_search_requests": 1
}
},
"stop_reason": "end_turn"
}
```
This example shows a direct search. When a search runs through [dynamic filtering](#dynamic-filtering), the response also contains the [code execution tool's](agents-and-tools-tool-use-code-execution-tool.md) result blocks, and each nested `server_tool_use` and `web_search_tool_result` pair carries a `caller` field identifying the code execution call that made it.
### Search results
Search results include:
- `url`: The URL of the source page
- `title`: The title of the source page
- `page_age`: When the site was last updated
- `encrypted_content`: Encrypted content that you must pass back in multi-turn conversations
To continue a conversation that contains search results, send the assistant's content blocks back exactly as you received them, including each result's `encrypted_content`. The API decrypts that content on later turns to restore the search results in Claude's context. If `encrypted_content` is missing or modified, the request fails with a 400 validation error.
### Citations
Citations are always enabled for web search, and each `web_search_result_location` includes:
- `url`: The URL of the cited source
- `title`: The title of the cited source
- `encrypted_index`: A reference that must be passed back for multi-turn conversations
- `cited_text`: Up to 150 characters of the cited content
The web search citation fields `cited_text`, `title`, and `url` do not count toward input or output token usage.
When displaying API outputs directly to end users, citations must be included to the original source. If you are making modifications to API outputs, including by reprocessing or combining them with your own material before displaying them to end users, display citations as appropriate based on consultation with your legal team.
### Errors
When the web search tool encounters an error (such as hitting rate limits), the Claude API still returns a 200 (success) response. The error is represented within the response body using the following structure:
Output
```python
{
"type": "web_search_tool_result",
"tool_use_id": "srvtoolu_a93jad",
"content": {
"type": "web_search_tool_result_error",
"error_code": "max_uses_exceeded"
}
}
```
On an error, `content` is a single error object rather than a list of result blocks. A search that succeeds but matches no results returns an empty `content` list, not an error.
These are the possible error codes:
- `too_many_requests`: Rate limit exceeded
- `invalid_tool_input`: Invalid search query parameter
- `max_uses_exceeded`: Maximum web search tool uses exceeded
- `query_too_long`: Query exceeds maximum length
- `request_too_large`: The search request is too large, typically because of a long domain filter list
- `unavailable`: An internal error occurred
### `pause_turn` stop reason
The API can pause a long-running search turn and return `stop_reason: "pause_turn"`. To continue, send the paused assistant message back unchanged in a new request.
If Claude calls web search and one of your client tools in the same group of parallel tool calls, the API returns `stop_reason: "tool_use"` instead and does not run the search yet. To continue, return the client tool results, and the API runs the search in the next request. See [Mixing server tools and client tools in one turn](agents-and-tools-tool-use-server-tools.md#mixing-server-tools-and-client-tools-in-one-turn).
For the server-side loop and `pause_turn` handling, see [The server-side loop and pause_turn](agents-and-tools-tool-use-server-tools.md#the-server-side-loop-and-pause-turn) in the Server tools guide.
## Prompt caching
To cache tool definitions across turns, see [Tool use with prompt caching](agents-and-tools-tool-use-tool-use-with-prompt-caching.md).
## Streaming
With streaming enabled, you'll receive search events as part of the stream. There will be a pause while the search runs:
Output
```python
event: message_start
data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}
event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}
// Claude's decision to search
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}
// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}
// Pause while search executes
// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}}
// Claude's response with citations (omitted in this example)
```
## Batch requests
You can include the web search tool in the [Messages Batches API](../Guides/build-with-claude-batch-processing.md). Web search tool calls through the Messages Batches API are priced the same as those in regular Messages API requests.
To protect shared capacity, the Batches API throttles web search requests per organization, so large batches with many searches might take longer to complete. You can see your organization's web search rate limit on the [Rate limits](../Other/playground.md) page in the Claude Console. To request a higher limit, contact sales from that page.
## Usage and pricing
Web search usage is charged in addition to token usage:
```python
{
"usage": {
"input_tokens": 105,
"output_tokens": 6039,
"cache_read_input_tokens": 7123,
"cache_creation_input_tokens": 7345,
"server_tool_use": {
"web_search_requests": 1
}
}
}
```
Web search is available on the Claude API for **\$10 per 1,000 searches**, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.
Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.
## Next steps
[Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)
Fetch and read content from specific URLs to augment Claude's context with live web content.
[Server tools](agents-and-tools-tool-use-server-tools.md)
Work with Anthropic-executed tools: server_tool_use blocks, pause_turn continuation, and domain filtering.
[Tool reference](agents-and-tools-tool-use-tool-reference.md)
Directory of Anthropic-provided tools and reference for optional tool definition properties.
---
## Not Found - Claude Platform Docs
Source: https://platform.claude.com/docs/en/agents-and-tools/web-fetch-tool
Path: 04-API-Reference/Agents-Tools/agents-and-tools-web-fetch-tool.md
- [Managed Agents](../Other/managed-agents-overview.md)
- [Admin](../Other/manage-claude-admin-api.md)
- Resources
- [Best practices](../About/about-claude-use-case-guides-overview.md)
- [Models & pricing](../../20-Models/about-claude-models-overview.md)
- [CLI, SDKs, and libraries](../Other/cli-sdks-libraries-overview.md)
- [Claude API skill](agents-and-tools-agent-skills-claude-api-skill.md)
- [Release notes](../../20-Models/release-notes-overview.md)
[API reference](../Endpoints/overview.md)
[Console](../Other/playground.md)[Log in](https://platform.claude.com/login?returnTo=%2Fdocs%2Fen%2Fagents-and-tools%2Fweb-fetch-tool)
# Page not found
The requested page could not be found. These pages are close:
- [Web fetch tool](agents-and-tools-tool-use-web-fetch-tool.md)Fetch and read content from specific URLs to augment Claude's context with live web content.
- [Browser use tool](agents-and-tools-tool-use-browser-use-tool.md)Let Claude navigate, read, and interact with webpages in your own browser environment with the browser use tool.
- [Web search tool](agents-and-tools-tool-use-web-search-tool.md)Give Claude access to current web content with cited sources, optional dynamic filtering, and domain controls.