One read of Claude Developer Platformapi-20260814T043121Z
565 pages moved out of 565 read.
Pages moved
565
significant first
Pages read
565
in this capture
Captured
04:31 UTC
Corpus hash
764ab7e8e96e
full baseline · corpus-hash
What this read moved
1-25 of 565, page 1 of 23This capture is too large to show at once. Changes 1-25 of 565 are below, significant first; the rest are on the following screens.
about-claude/glossary First recorded · 65 lines, first recorded
## Context window ## Fine-tuning ## HHH ## Latency ## LLM ## MCP (Model Context Protocol) ## MCP connector ## Pretraining ## RAG (Retrieval augmented generation) ## RLHF ## Temperature ## TTFT (Time to first token) ## Tokens
The first capture of this source. The page was already there, and this is what it said.
--- title: Glossary url: https://platform.claude.com/docs/en/about-claude/glossary description: These concepts are not unique to Claude. This page presents a brief summary of key terms. --- ## Context window The "context window" refers to the amount of text a language model can look back on and reference when generating new text. This is different from the large corpus of data the language model was trained on, and instead represents a "working memory" for the model. A larger context window allows the model to process and respond to more complex and lengthy prompts, while a smaller context window may limit the model's ability to handle longer prompts or maintain coherence over extended conversations. See the [guide to understanding context windows](https://platform.claude.com/docs/en/build-with-claude/context-windows) to learn more. ## Fine-tuning Fine-tuning is the process of further training a pretrained language model using additional data. This causes the model to start representing and mimicking the patterns and characteristics of the fine-tuning dataset. Claude is not a bare language model; it has already been fine-tuned to be a helpful assistant. The Claude API does not currently offer fine-tuning, but ask your Anthropic contact if you are interested in exploring this option. Fine-tuning can be useful for adapting a language model to a specific domain, task, or writing style, but it requires careful consideration of the fine-tuning data and the potential impact on the model's performance and biases. ## HHH HHH (helpful, honest, harmless) is a research framework that informs how Claude is trained to be beneficial to society. It is distinct from the Claude product tagline, "AI assistant for life and work." * A **helpful** AI will attempt to perform the task or answer the question posed to the best of its abilities, providing relevant and useful information. * An **honest** AI will give accurate information, and not hallucinate or confabulate. It will acknowledge its limitations and uncertainties when appropriate. * A **harmless** AI will not be offensive or discriminatory, and when asked to aid in a dangerous or unethical act, the AI should politely refuse and explain why it cannot comply. ## Latency Latency, in the context of generative AI and large language models, refers to the time it takes for the model to respond to a given prompt. It is the delay between submitting a prompt and receiving the generated output. Lower latency indicates faster response times, which is crucial for real-time applications, chatbots, and interactive experiences. Factors that can affect latency include model size, hardware capabilities, network conditions, and the complexity of the prompt and the generated response. ## LLM Large language models (LLMs) are AI language models with many parameters that are capable of performing a variety of surprisingly useful tasks. These models are trained on vast amounts of text data and can generate human-like text, answer questions, summarize information, and more. Claude, an AI assistant for life and work built by Anthropic, is based on a large language model that has been fine-tuned and trained using RLHF. ## MCP (Model Context Protocol) Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. Like a USB-C port for AI applications, MCP provides a unified way to connect AI models to different data sources and tools. MCP enables AI systems to maintain consistent context across interactions and access external resources in a standardized manner. See the [MCP documentation](https://platform.claude.com/docs/en/mcp) to learn more. ## MCP connector The MCP connector is a feature that allows API users to connect to MCP servers directly from the Messages API without building an MCP client. This enables seamless integration with MCP-compatible tools and services through the Claude API. The MCP connector supports features such as tool calling and is available in beta. See the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) documentation to learn more. ## Pretraining Pretraining is the initial process of training language models on a large unlabeled corpus of text. In Claude's case, autoregressive language models (such as Claude's underlying model) are pretrained to predict the next word, given the previous context of text in the document. These pretrained models are not inherently good at answering questions or following instructions, and often require deep skill in prompt engineering to elicit desired behaviors. Fine-tuning and RLHF are used to refine these pretrained models, making them more useful for a wide range of tasks. ## RAG (Retrieval augmented generation) Retrieval augmented generation (RAG) is a technique that combines information retrieval with language model generation to improve the accuracy and relevance of the generated text, and to better ground the model's response in evidence. In RAG, a language model is augmented with an external knowledge base or a set of documents that is passed into the context window. The data is retrieved at runtime when a query is sent to the model, although the model itself does not necessarily retrieve the data (but can with [tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) and a retrieval function). When generating text, relevant information first must be retrieved from the knowledge base based on the input prompt, and then passed to the model along with the original query. The model uses this information to guide the output it generates. This allows the model to access and use information beyond its training data, reducing the reliance on memorization and improving the factual accuracy of the generated text. RAG can be particularly useful for tasks that require up-to-date information, domain-specific knowledge, or explicit citation of sources. However, the effectiveness of RAG depends on the quality and relevance of the external knowledge base and the knowledge that is retrieved at runtime. ## RLHF Reinforcement Learning from Human Feedback (RLHF) is a technique used to train a pretrained language model to behave in ways that are consistent with human preferences. This can include helping the model follow instructions more effectively or act more like a chatbot. Human feedback consists of ranking a set of two or more example texts, and the reinforcement learning process encourages the model to prefer outputs that are similar to the higher-ranked ones. Claude has been trained using RLHF to be a more helpful assistant. For more details, you can read [Anthropic's paper on the subject](https://arxiv.org/abs/2204.05862). ## Temperature Temperature is a parameter that controls the randomness of a model's predictions during text generation. Higher temperatures lead to more creative and diverse outputs, allowing for multiple variations in phrasing and, in the case of fiction, variation in answers as well. Lower temperatures result in more conservative and deterministic outputs that stick to the most probable phrasing and answers. Adjusting the temperature enables users to encourage a language model to explore rare, uncommon, or surprising word choices and sequences, rather than only selecting the most likely predictions. Users may encounter non-determinism in APIs. Even with temperature set to 0, the results will not be fully deterministic and identical inputs may produce different outputs across API calls. This applies both to Anthropic's first-party inference service and to inference through third-party cloud providers. ## TTFT (Time to first token) Time to First Token (TTFT) is a performance metric that measures the time it takes for a language model to generate the first token of its output after receiving a prompt. It is an important indicator of the model's responsiveness and is particularly relevant for interactive applications, chatbots, and real-time systems where users expect quick initial feedback. A lower TTFT indicates that the model can start generating a response faster, providing a more seamless and engaging user experience. Factors that can influence TTFT include model size, hardware capabilities, network conditions, and the complexity of the prompt. ## Tokens Tokens are the smallest individual units of a language model, and can correspond to words, subwords, characters, or even bytes (in the case of Unicode). For Claude, a token approximately represents 3.5 English characters, though the exact number can vary depending on the language used. Tokens are typically hidden when interacting with language models at the "text" level but become relevant when examining the exact inputs and outputs of a language model. When Claude is provided with text to evaluate, the text (consisting of a series of characters) is encoded into a series of tokens for the model to process. Larger tokens enable data efficiency during inference and pretraining (and are used when possible), while smaller tokens allow a model to handle uncommon or never-before-seen words. The choice of tokenization method can impact the model's performance, vocabulary size, and ability to handle out-of-vocabulary words.
about-claude/model-deprecations First recorded · 222 lines, first recorded
## Overview ## Migrating to replacements ## Notifications ## Auditing model usage ## Best practices ## Deprecation downsides and mitigations ## Model status ## Deprecation history ### 2026-06-05: Claude Opus 4.1 model ### 2026-04-14: Claude Sonnet 4 and Claude Opus 4 models ### 2026-02-19: Claude Haiku 3 model ### 2025-12-19: Claude Haiku 3.5 model ### 2025-10-28: Claude Sonnet 3.7 model ### 2025-08-13: Claude Sonnet 3.5 models ### 2025-06-30: Claude Opus 3 model ### 2025-01-21: Claude 2, Claude 2.1, and Claude Sonnet 3 models ### 2024-09-04: Claude 1 and Instant models ## API parameter deprecations
The first capture of this source. The page was already there, and this is what it said.
--- title: Model deprecations url: https://platform.claude.com/docs/en/about-claude/model-deprecations description: See which Claude models are active, deprecated, or retired, and find retirement dates and recommended replacements for models and API parameters. --- As safer and more capable models launch, Anthropic regularly retires older ones. Applications relying on Anthropic models may need occasional updates to keep working. Impacted customers will always be notified by email and in the documentation. This page lists all API deprecations, along with recommended replacements. ## Overview Anthropic uses the following terms to describe the model lifecycle: * **Active:** The model is fully supported and recommended for use. * **Legacy:** The model will no longer receive updates and may be deprecated in the future. * **Deprecated:** The model is still functional but no longer recommended. Anthropic provides a recommended replacement and assigns a retirement date. * **Retired:** The model is no longer available for use. Requests to retired models will fail. <Warning> Deprecated models are likely to be less reliable than active models. Move workloads to active models to maintain the highest level of support and reliability. </Warning> The dates on this page apply to Anthropic-operated platforms: the Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry). Partner-operated platforms (Amazon Bedrock and Google Cloud) set their own retirement schedules, so a model's lifecycle status and dates can differ. See the [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock#supported-models), [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy#api-model-ids), and [Google Cloud](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai#api-model-ids) model tables. ## Migrating to replacements Once a model is deprecated, migrate all usage to a suitable replacement before the retirement date. Requests to models past the retirement date will fail. To help measure the performance of replacement models on your tasks, consider thorough testing of your applications with the new models well before the retirement date. For specific instructions on migrating to the latest Claude models, see the [Migration guide](https://platform.claude.com/docs/en/about-claude/models/migration-guide). ## Notifications Anthropic notifies customers with active deployments for models with upcoming retirements, providing at least 60 days' notice before model retirement for publicly released models. ## Auditing model usage To help identify usage of deprecated models, customers can access an audit of their API usage. Follow these steps: 1. Go to the [Usage](https://platform.claude.com/usage) page in Claude Console. 2. Click **Export**. 3. Review the downloaded CSV to see usage broken down by API key and model. This audit will help you locate any instances where your application is still using deprecated models, allowing you to prioritize updates to newer models before the retirement date. ## Best practices 1. Regularly check the documentation for updates on model deprecations. 2. Test your applications with newer models well before the retirement date of your current model. 3. Update your code to use the recommended replacement model as soon as possible. 4. Contact the support team if you need assistance with migration or have any questions. ## Deprecation downsides and mitigations Anthropic currently deprecates and retires models to ensure capacity for new model releases. This comes with downsides: * Users who value specific models must migrate to new versions * Researchers lose access to models for ongoing and comparative studies * Model retirement introduces safety- and model welfare-related risks At some point, Anthropic hopes to make past models publicly available again. In the meantime, Anthropic has committed to long-term preservation of model weights and other measures to help mitigate these impacts. For more details, see [Commitments on Model Deprecation and Preservation](https://www.anthropic.com/research/deprecation-commitments). ## Model status <Note> [Claude Mythos Preview](https://anthropic.com/glasswing) (`claude-mythos-preview`) is deprecated. To migrate to [Claude Mythos 5](https://anthropic.com/glasswing) (`claude-mythos-5`), see the [migration guide](https://platform.claude.com/docs/en/about-claude/models/migration-guide#migrating-from-claude-mythos-preview). </Note> Current and recently retired models are listed in the following table with their status: | API model name | Current state | Deprecated | Tentative retirement date | | -------------------------- | ------------- | ----------------- | ---------------------------------- | | claude-fable-5 | Active | N/A | Not sooner than June 9, 2027 | | claude-opus-5 | Active | N/A | Not sooner than July 24, 2027 | | claude-opus-4-8 | Active | N/A | Not sooner than May 28, 2027 | | claude-opus-4-7 | Active | N/A | Not sooner than April 16, 2027 | | claude-opus-4-6 | Active | N/A | Not sooner than February 5, 2027 | | claude-opus-4-5-20251101 | Active | N/A | Not sooner than November 24, 2026 | | claude-opus-4-1-20250805 | Retired | June 5, 2026 | August 5, 2026 | | claude-opus-4-20250514 | Retired | April 14, 2026 | June 15, 2026 | | claude-sonnet-5 | Active | N/A | Not sooner than June 30, 2027 | | claude-sonnet-4-6 | Active | N/A | Not sooner than February 17, 2027 | | claude-sonnet-4-5-20250929 | Active | N/A | Not sooner than September 29, 2026 | | claude-sonnet-4-20250514 | Retired | April 14, 2026 | June 15, 2026 | | claude-3-7-sonnet-20250219 | Retired | October 28, 2025 | February 19, 2026 | | claude-haiku-4-5-20251001 | Active | N/A | Not sooner than October 15, 2026 | | claude-3-5-haiku-20241022 | Retired | December 19, 2025 | February 19, 2026 | | claude-3-haiku-20240307 | Retired | February 19, 2026 | April 20, 2026 | ## Deprecation history All deprecations are listed in the following sections, with the most recent announcements first. ### 2026-06-05: Claude Opus 4.1 model <Note> This model was retired August 5, 2026. </Note> On June 5, 2026, Anthropic notified developers using Claude Opus 4.1 of its upcoming retirement on the Claude API. | Retirement date | Deprecated model | Recommended replacement | | --------------- | -------------------------- | ----------------------- | | August 5, 2026 | `claude-opus-4-1-20250805` | `claude-opus-4-8` | ### 2026-04-14: Claude Sonnet 4 and Claude Opus 4 models <Note> These models were retired June 15, 2026. </Note> On April 14, 2026, Anthropic notified developers using Claude Sonnet 4 and Claude Opus 4 models of their upcoming retirement on the Claude API. | Retirement date | Deprecated model | Recommended replacement | | --------------- | -------------------------- | ----------------------- | | June 15, 2026 | `claude-sonnet-4-20250514` | `claude-sonnet-4-6` | | June 15, 2026 | `claude-opus-4-20250514` | `claude-opus-4-8` | ### 2026-02-19: Claude Haiku 3 model <Note> This model was retired April 20, 2026. </Note> On February 19, 2026, Anthropic notified developers using Claude Haiku 3 model of its upcoming retirement on the Claude API. | Retirement date | Deprecated model | Recommended replacement | | --------------- | ------------------------- | --------------------------- | | April 20, 2026 | `claude-3-haiku-20240307` | `claude-haiku-4-5-20251001` | ### 2025-12-19: Claude Haiku 3.5 model <Note> This model was retired February 19, 2026. </Note> On December 19, 2025, Anthropic notified developers using Claude Haiku 3.5 model of its upcoming retirement on the Claude API. | Retirement date | Deprecated model | Recommended replacement | | ----------------- | --------------------------- | --------------------------- | | February 19, 2026 | `claude-3-5-haiku-20241022` | `claude-haiku-4-5-20251001` | ### 2025-10-28: Claude Sonnet 3.7 model <Note> This model was retired February 19, 2026. </Note> On October 28, 2025, Anthropic notified developers using Claude Sonnet 3.7 model of its upcoming retirement on the Claude API. | Retirement date | Deprecated model | Recommended replacement | | ----------------- | ---------------------------- | ----------------------- | | February 19, 2026 | `claude-3-7-sonnet-20250219` | `claude-sonnet-4-6` | ### 2025-08-13: Claude Sonnet 3.5 models <Note> These models were retired October 28, 2025. </Note> On August 13, 2025, Anthropic notified developers using Claude Sonnet 3.5 models of their upcoming retirement. | Retirement date | Deprecated model | Recommended replacement | | ---------------- | ---------------------------- | ----------------------- | | October 28, 2025 | `claude-3-5-sonnet-20240620` | `claude-sonnet-4-6` | | October 28, 2025 | `claude-3-5-sonnet-20241022` | `claude-sonnet-4-6` | ### 2025-06-30: Claude Opus 3 model <Note> This model was retired January 5, 2026. </Note> On June 30, 2025, Anthropic notified developers using Claude Opus 3 model of its upcoming retirement. | Retirement date | Deprecated model | Recommended replacement | | --------------- | ------------------------ | ----------------------- | | January 5, 2026 | `claude-3-opus-20240229` | `claude-opus-4-8` | ### 2025-01-21: Claude 2, Claude 2.1, and Claude Sonnet 3 models <Note> These models were retired July 21, 2025. </Note> On January 21, 2025, Anthropic notified developers using Claude 2, Claude 2.1, and Claude Sonnet 3 models of their upcoming retirements. | Retirement date | Deprecated model | Recommended replacement | | --------------- | -------------------------- | ----------------------- | | July 21, 2025 | `claude-2.0` | `claude-opus-4-8` | | July 21, 2025 | `claude-2.1` | `claude-opus-4-8` | | July 21, 2025 | `claude-3-sonnet-20240229` | `claude-sonnet-4-6` | ### 2024-09-04: Claude 1 and Instant models <Note> These models were retired November 6, 2024. </Note> On September 4, 2024, Anthropic notified developers using Claude 1 and Instant models of their upcoming retirements. | Retirement date | Deprecated model | Recommended replacement | | ---------------- | -------------------- | --------------------------- | | November 6, 2024 | `claude-1.0` | `claude-haiku-4-5-20251001` | | November 6, 2024 | `claude-1.1` | `claude-haiku-4-5-20251001` | | November 6, 2024 | `claude-1.2` | `claude-haiku-4-5-20251001` | | November 6, 2024 | `claude-1.3` | `claude-haiku-4-5-20251001` | | November 6, 2024 | `claude-instant-1.0` | `claude-haiku-4-5-20251001` | | November 6, 2024 | `claude-instant-1.1` | `claude-haiku-4-5-20251001` | | November 6, 2024 | `claude-instant-1.2` | `claude-haiku-4-5-20251001` | ## API parameter deprecations Anthropic occasionally deprecates request parameters that no longer apply to current models. Deprecated parameters remain in the SDK request types so existing code continues to type-check, but their behavior changes per model. | Parameter | Status | Behavior | Recommended replacement | | ------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `temperature`, `top_p`, `top_k` | Deprecated (Claude Opus 4.7 and later) | Returns a 400 error when set to a non-default value on Claude 4.7 and later models and [Claude Mythos Preview](https://anthropic.com/glasswing). | Omit and use [prompting](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) to guide model behavior. | For migration steps, see the [migration guide](https://platform.claude.com/docs/en/about-claude/models/migration-guide).
about-claude/models/choosing-a-model First recorded · 112 lines, first recorded
## Establish key criteria ## Choose the best model to start with ### Option 1: Start efficiency-first ### Option 2: Start capability-first ## Model selection matrix ## Decide whether to upgrade or change models ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Choosing the right model
url: https://platform.claude.com/docs/en/about-claude/models/choosing-a-model
description: "Selecting the optimal Claude model for your application involves balancing three key considerations: capabilities, speed, and cost. This guide helps you make an informed decision based on your specific requirements."
---
## Establish key criteria
When choosing a Claude model, consider first evaluating these factors:
* **Capabilities:** What specific features or capabilities will you need the model to have to meet your needs?
* **Speed:** How quickly does the model need to respond in your application? Claude Opus 5 and Claude Opus 4.8 support [fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) (research preview), which delivers up to 2.5x higher output speed at premium pricing.
* **Cost:** What's your budget for both development and production usage?
* **Effort:** Recent Opus and Sonnet models support an [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) that trades intelligence for latency and cost within a single model. Tuning effort is often a better lever than switching models. On Claude Opus 5, start with the default (`high`) and adjust up or down based on your evals. On Claude Opus 4.8 and Claude Opus 4.7, the `xhigh` effort level, between `high` and `max`, is the best setting for most coding and agentic use cases.
Knowing these answers in advance will make narrowing down and deciding which model to use much easier.
***
## Choose the best model to start with
There are two general approaches you can use to start testing which Claude model best works for your needs.
### Option 1: Start efficiency-first
For many applications, starting with a faster, more cost-effective model like Claude Haiku 4.5 can be the optimal approach:
1. Begin implementation with Claude Haiku 4.5.
2. Test your use case thoroughly.
3. Evaluate if performance meets your requirements.
4. Upgrade only if necessary for specific capability gaps.
This approach allows for quick iteration, lower development costs, and is often sufficient for many common applications. This approach is best for:
* Initial prototyping and development
* Applications with tight latency requirements
* Cost-sensitive implementations
* High-volume, straightforward tasks
### Option 2: Start capability-first
For complex tasks where intelligence and advanced capabilities are paramount, you may want to start capability-first: implement with the strongest starting point for your task, then optimize to more efficient models down the line:
1. Implement with Claude Opus 5.
2. [Optimize your prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5) for this model.
3. Evaluate if performance meets your requirements.
4. Consider increasing efficiency by lowering [effort](https://platform.claude.com/docs/en/build-with-claude/effort) or downgrading models over time with greater workflow optimization.
This approach is best for:
* Complex reasoning tasks
* Scientific or mathematical applications
* Tasks requiring nuanced understanding
* Applications where accuracy outweighs cost considerations
* Advanced coding and high-autonomy agentic work
<Note>
The [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) defaults to `high` on Claude Opus 5 and Claude Opus 4.8, including in Claude Code and the Messages API. On Claude Opus 5, start at the default and step up to `xhigh` for the most demanding coding and agentic work. On Claude Opus 4.8, use `xhigh` for coding, high-autonomy work, and the most intelligence-demanding tasks.
</Note>
**Claude Opus 5** (`claude-opus-5`) is a step-change improvement over Claude Opus 4.8, strong on deep reasoning, agentic and long-horizon tasks, and test-time compute scaling. Claude Opus 5 supports a 1M token context window by default and up to 128k output tokens, and is priced at $5 USD per million input tokens and $25 USD per million output tokens.
**Claude Fable 5** (`claude-fable-5`) is Anthropic's most capable widely released model, delivering next-generation intelligence for long-running agents. **Claude Mythos 5** (`claude-mythos-5`) is available through [Project Glasswing](https://anthropic.com/glasswing). Both models support a 1M token context window by default, up to 128k output tokens, and always-on [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking). See [Introducing Claude Fable 5 and Claude Mythos 5](https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5) for launch details.
Claude Fable 5 and Claude Mythos 5 are priced at $10 USD per million input tokens and $50 USD per million output tokens.
## Model selection matrix
| When you need... | Consider starting with... | Example use cases |
| ------------------------------------------------------------------------------------------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The highest available capability | Claude Fable 5 | Long-running agents, deep reasoning, long-horizon agentic tasks, advanced research |
| Complex agentic coding and enterprise work | Claude Opus 5 | Multihour autonomous coding agents, large-scale refactoring, complex systems engineering, advanced research, knowledge work, vision-heavy workflows, computer use |
| Frontier intelligence at scale, built for coding, agents, and enterprise workflows | Claude Sonnet 5 | Code generation, data analysis, content creation, visual understanding, agentic tool use |
| Near-frontier performance with lightning-fast speed and extended thinking at the most economical price point | Claude Haiku 4.5 | Real-time applications, high-volume intelligent processing, cost-sensitive deployments needing strong reasoning, sub-agent tasks |
***
## Decide whether to upgrade or change models
To determine if you need to upgrade or change models, you should:
1. [Create benchmark tests](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests) specific to your use case - having a good evaluation set is the most important step in the process.
2. Test with your actual prompts and data.
3. Compare performance across models for:
* Accuracy of responses
* Response quality
* Handling of edge cases
4. Weigh performance and cost tradeoffs.
## Next steps
<CardGroup cols={2}>
<Card title="Model comparison chart" icon="settings" href="https://platform.claude.com/docs/en/about-claude/models/overview">
See detailed specifications and pricing for the latest Claude models
</Card>
<Card title="What's new in Claude Opus 5" icon="sparkle" href="https://platform.claude.com/docs/en/about-claude/models/whats-new-opus-5">
Explore the latest improvements in Claude Opus 5
</Card>
<Card title="What's new in Claude Sonnet 5" icon="sparkle" href="https://platform.claude.com/docs/en/about-claude/models/whats-new-sonnet-5">
The best combination of speed and intelligence
</Card>
<Card title="Start building" icon="code" href="https://platform.claude.com/docs/en/get-started">
Get started with your first API call
</Card>
</CardGroup>
about-claude/models/introducing-claude-fable-5-and-claude-mythos-5 First recorded · 133 lines, first recorded
## Models ## Refusals, fallback, and billing on Claude Fable 5 ### Refusals ### Fallback ### Billing ## Availability ## Working with Claude Fable 5 and Claude Mythos 5 ### Prompting ## Messages API on Claude Fable 5 and Claude Mythos 5 ### Adaptive thinking is always on ### Raw thinking content is never returned ## Supported features ## Migrating from earlier models ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Introducing Claude Fable 5 and Claude Mythos 5
url: https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5
description: Claude Fable 5 and Claude Mythos 5 capabilities, API changes, and availability.
---
<Tip>
Access to Claude Fable 5 and Claude Mythos 5 has been restored. See [our statement](https://www.anthropic.com/news/redeploying-fable-5) for more information.
</Tip>
Claude Fable 5 is Anthropic's most capable widely released model, built for the most demanding reasoning and long-horizon agentic work. Claude Mythos 5 shares the same capabilities and is available only in limited release through [Project Glasswing](https://anthropic.com/glasswing).
The headline change for integrations: Claude Fable 5 includes safety classifiers that can decline requests. Claude Mythos 5 does not include these classifiers. If your integration calls Claude Fable 5, plan for three changes: new response handling for refusals, fallback options for retrying on another Claude model, and new billing rules. [Refusals, fallback, and billing on Claude Fable 5](https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5#refusals-fallback-and-billing-on-claude-fable-5) summarizes all three.
## Models
| Model | API model ID | Description |
| --------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Fable 5 | `claude-fable-5` | Anthropic's most capable widely released model, for the most demanding reasoning and long-horizon agentic work |
| Claude Mythos 5 | `claude-mythos-5` | Shares Claude Fable 5's capabilities without the safety classifiers. Available through Project Glasswing. Successor to Claude Mythos Preview. |
Claude Fable 5 and Claude Mythos 5 share the same specs and pricing:
* **Context window and output:** a [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) by default, and up to 128k output tokens per request.
* **Pricing:** $10 USD per million input tokens and $50 USD per million output tokens.
For specs across all current models, see the [models overview](https://platform.claude.com/docs/en/about-claude/models/overview).
## Refusals, fallback, and billing on Claude Fable 5
Claude Fable 5 includes safety classifiers that can decline certain requests. Claude Mythos 5 does not include these classifiers, so this section applies to Claude Fable 5 only. The following sections summarize what refusals mean for your integration; each links to the full guide.
### Refusals
When Claude Fable 5 declines a request, the Messages API returns `stop_reason: "refusal"` as a successful HTTP 200 response, not an error. The response also reports which classifier declined the request. See [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) for response shapes and handling guidance.
### Fallback
A request that Claude Fable 5 refuses can usually be served by another Claude model. There are three ways to retry:
* **Server-side:** Pass the `fallbacks` parameter to have the API retry for you, using its `"default"` mode for Anthropic's recommended models or naming your own (in beta on the Claude API). See [Server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback).
* **Client-side:** Use the [SDK middleware](https://platform.claude.com/docs/en/cli-sdks-libraries/middleware) to retry from the client on any platform. See [Client-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#client-side-fallback).
* **Manual:** Build the retry yourself, on any platform and in any language. See [Fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit).
### Billing
You are not billed for a request that is refused before any output is generated. When you retry on another model, [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit) refunds the prompt-cache cost of switching, so you avoid paying that cost twice.
## Availability
Claude Fable 5 and Claude Mythos 5 both become available on June 9, 2026:
* **Claude Fable 5** is generally available on the Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Google Cloud](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry).
* **Claude Mythos 5** is not generally available: it is offered in limited availability to approved customers in [Project Glasswing](https://anthropic.com/glasswing). For access, contact your Anthropic, AWS, or Google Cloud account team. Customers without access to Claude Mythos 5 can use Claude Fable 5, which is generally available and offers the same capabilities.
Claude Fable 5 and Claude Mythos 5 carry 30-day data retention and are not available under zero data retention: both are designated [Covered Models](https://support.claude.com/en/articles/15425695). See [Model-specific data retention requirements](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements).
## Working with Claude Fable 5 and Claude Mythos 5
### Prompting
Claude Fable 5 responds to the same prompting techniques as other Claude models, with a few differences in how to structure long-context prompts and reasoning instructions. See [Prompting Claude Fable 5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5).
## Messages API on Claude Fable 5 and Claude Mythos 5
### Adaptive thinking is always on
Claude Fable 5 and Claude Mythos 5 always have thinking enabled; passing `thinking: {"type": "disabled"}` is not supported. To reduce or otherwise control thinking depth, use the [effort](https://platform.claude.com/docs/en/build-with-claude/effort) parameter.
### Raw thinking content is never returned
The raw chain of thought is never returned on Claude Fable 5 and Claude Mythos 5. The `thinking.display` setting controls what thinking blocks contain instead:
* `"summarized"` returns thinking blocks with a readable summary of the reasoning.
* `"omitted"` (the default) returns thinking blocks with an empty `thinking` field.
Pass thinking blocks back unchanged in multi-turn conversations on the same model. See [thinking output on Claude Fable 5 and Claude Mythos 5](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-output-on-claude-fable-5-and-claude-mythos-5) for cross-model handling.
## Supported features
At launch, Claude Fable 5 and Claude Mythos 5 support:
* [Effort](https://platform.claude.com/docs/en/build-with-claude/effort)
* [Task budgets](https://platform.claude.com/docs/en/build-with-claude/task-budgets) (beta: set the `task-budgets-2026-03-13` header)
* The [memory tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)
* [Code execution](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)
* [Programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)
* Tool result clearing through [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) (beta: set the `context-management-2025-06-27` header)
* [Compaction](https://platform.claude.com/docs/en/build-with-claude/compaction)
* [Vision](https://platform.claude.com/docs/en/build-with-claude/vision)
## Migrating from earlier models
Step-by-step instructions live in the migration guide:
* From Claude Mythos Preview: see [Migrating from Claude Mythos Preview to Claude Mythos 5](https://platform.claude.com/docs/en/about-claude/models/migration-guide#migrating-from-claude-mythos-preview).
* From Claude Opus 4.8: see [Migrating from Claude Opus 4.8 to Claude Fable 5](https://platform.claude.com/docs/en/about-claude/models/migration-guide#migrating-from-claude-opus-48).
## Next steps
<CardGroup>
<Card title="Migration guide" icon="arrow-right" href="https://platform.claude.com/docs/en/about-claude/models/migration-guide">
Step-by-step upgrade instructions from Claude Opus 4.8 and Claude Mythos Preview.
</Card>
<Card title="Models overview" icon="settings" href="https://platform.claude.com/docs/en/about-claude/models/overview">
Specs and comparison for all current Claude models.
</Card>
<Card title="Adaptive thinking" icon="brain" href="https://platform.claude.com/docs/en/build-with-claude/thinking">
The only thinking mode on Claude Fable 5 and Claude Mythos 5.
</Card>
<Card title="Refusals and fallback" icon="shield" href="https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback">
How Claude Fable 5 declines requests, and how to retry on another model.
</Card>
<Card title="Fallback credit" icon="coins" href="https://platform.claude.com/docs/en/build-with-claude/fallback-credit">
Avoid paying the prompt-cache cost twice on a retry.
</Card>
<Card title="Fallback and billing cookbook" icon="book-open" href="https://platform.claude.com/cookbook/fable-5-fallback-billing-guide">
A worked end-to-end example of refusal handling, fallback, and billing.
</Card>
<Card title="Effort" icon="sliders" href="https://platform.claude.com/docs/en/build-with-claude/effort">
Control thinking depth and cost on Claude Fable 5 and Claude Mythos 5.
</Card>
<Card title="Prompting Claude Fable 5" icon="terminal" href="https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5">
Fable-specific prompting techniques.
</Card>
</CardGroup>
about-claude/models/migration-guide First recorded · 2772 lines, first recorded
## Migrating to Claude Mythos 5 and Claude Fable 5 ### Migrating to Claude Mythos 5 and Claude Fable 5 from Claude Mythos Preview #### Update your model name #### Features not available on Claude Mythos 5 and Claude Fable 5 #### Token counting and billing #### Migration checklist ### Migrating to Claude Mythos 5 and Claude Fable 5 from Claude Opus 5 #### Update your model name #### What changed #### Migration checklist ### Migrating to Claude Mythos 5 and Claude Fable 5 from Claude Opus 4.8 #### Update your model name #### What changed #### Migration checklist ## Migrating to Claude Opus 5 ### Migrating to Claude Opus 5 from Claude Opus 4.8 #### Update your model name #### Breaking changes #### Recommended changes #### Migration checklist ### Migrating to Claude Opus 5 from Claude Opus 4.7 #### Update your model name #### Breaking changes #### What changed #### Recommended changes #### Migration checklist ### Migrating to Claude Opus 5 from Claude Opus 4.6 and earlier Opus models #### Update your model name #### Breaking changes #### Choosing an effort level #### Behavior changes #### Recommended changes #### Migration checklist #### Migrating from Claude Opus 4.5 or earlier ##### Update your model name ##### Breaking changes ##### Recommended changes #### Migrating from Claude 4.1 or earlier ##### Additional breaking changes ##### Additional recommended changes #### Migration checklist (from Claude Opus 4.5 or earlier) ### Migrating to Claude Opus 5 from Claude Sonnet 5 #### Update your model name #### What changed #### Migration checklist ## Migrating to Claude Sonnet 5 ### Migrating to Claude Sonnet 5 from Claude Sonnet 4.6 #### Update your model name #### What changed #### Migration checklist ### Migrating to Claude Sonnet 5 from Claude Sonnet 4.5 and earlier Sonnet models #### Breaking changes ##### When migrating from Sonnet 4.5 ##### When migrating from Claude 3.x ### Migrating to Claude Sonnet 5 from Claude Haiku 4.5 #### Update your model name #### What changed #### Migration checklist ## Migrating to Claude Haiku 4.5 ### Migrating to Claude Haiku 4.5 from Claude Haiku 3.5 and earlier Haiku models #### Breaking changes #### Haiku 4.5 migration checklist ## Get help
The first capture of this source. The page was already there, and this is what it said.
---
title: Migration guide
url: https://platform.claude.com/docs/en/about-claude/models/migration-guide
description: Guide for migrating to the latest Claude models from previous Claude versions
---
<Note>
This guide covers migrating [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) code. If you use [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview), no changes beyond updating the model name are required.
</Note>
<Tip>
**Automate your migration with the Claude API skill.** In Claude Code, run `/claude-api migrate` to invoke the bundled [Claude API skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model). It works for any target model on this page:
```text wrap
/claude-api migrate this project to claude-opus-5
```
The skill applies the model ID swap and, as needed, breaking parameter changes, prefill replacement, and effort calibration for your target model across your code base, then produces a checklist of items to verify manually. It asks you to confirm the migration scope (entire working directory, a subdirectory, or a specific file list) before editing any files. The skill also detects Amazon Bedrock and Claude Platform on AWS clients and adjusts model ID formats and feature changes for those platforms.
</Tip>
## Migrating to Claude Mythos 5 and Claude Fable 5
[Claude Fable 5](https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5) is Anthropic's most capable widely released model, generally available on the Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Google Cloud](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry). [Claude Mythos 5](https://anthropic.com/glasswing) shares the same capabilities and is offered in limited availability to approved customers in Project Glasswing.
The baseline settings shared by `claude-fable-5` and `claude-mythos-5`:
* **Thinking:** [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) is always on. The model determines when and how much to think on each request, and no `thinking` configuration is required. Both `thinking: {type: "disabled"}` and manual extended thinking (`thinking: {type: "enabled", budget_tokens: N}`) return a 400 error.
* **Prefill:** Prefilling the assistant message returns a 400 error. Use system prompt instructions instead.
* **Context window and output:** A [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) by default, and up to 128k output tokens per request.
* **Pricing:** $10 USD per million input tokens and $50 USD per million output tokens. See [Claude pricing](https://platform.claude.com/docs/en/about-claude/pricing).
* **Data retention:** Both models require 30-day data retention and are not available under zero data retention (ZDR) arrangements; both are designated Covered Models. On the Claude API, a request to Claude Fable 5 from an organization whose data retention configuration does not meet this requirement returns a 400 `invalid_request_error`. Organizations with a ZDR arrangement should contact their Anthropic account team to discuss data retention configuration. Alternatively, you can configure data retention per workspace. See [Model-specific data retention requirements](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements) for per-platform details.
Where the two models diverge:
* **Availability:** Claude Fable 5 is generally available. Claude Mythos 5 is available only to approved customers in [Project Glasswing](https://anthropic.com/glasswing).
* **Safety classifiers:** Claude Fable 5 runs safety classifiers that can decline requests with `stop_reason: "refusal"`. Claude Mythos 5 does not include these classifiers. See [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback).
* **Priority Tier:** [Priority Tier](https://platform.claude.com/docs/en/api/service-tiers#supported-models) is supported on Claude Fable 5 but not on Claude Mythos 5.
### Migrating to Claude Mythos 5 and Claude Fable 5 from Claude Mythos Preview
[Claude Mythos 5](https://anthropic.com/glasswing) is the access-gated successor to [Claude Mythos Preview](https://anthropic.com/glasswing), the invitation-only research preview. [Claude Fable 5](https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5) is the generally available model with the same capabilities, and the changes in this section apply equally to both targets.
Migration is mostly drop-in. Claude Mythos 5 and Claude Fable 5 use the same [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) and the same [tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) patterns as Claude Mythos Preview, and token counts are roughly unchanged because all three models use the same tokenizer. The key changes to check are the features that are no longer available (listed in the next section) and thinking output. If you migrate to Claude Fable 5, also plan for safety classifier refusals, which Claude Mythos Preview and Claude Mythos 5 do not have; see [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback).
For the Claude Mythos Preview retirement timeline, see [Model deprecations](https://platform.claude.com/docs/en/about-claude/model-deprecations).
#### Update your model name
```python
model = "claude-mythos-preview" # Before
model = "claude-mythos-5" # After
# Or, for the generally available model with the same capabilities:
model = "claude-fable-5" # After
```
#### Features not available on Claude Mythos 5 and Claude Fable 5
1. **Extended thinking and thinking token budgets:** Manual extended thinking (`thinking: {type: "enabled", budget_tokens: N}`) is not supported on `claude-mythos-5` or `claude-fable-5` and returns a 400 error. [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) is always on: the model determines when and how much to think on each request, and no `thinking` configuration is required. `thinking: {type: "disabled"}` returns an error. `budget_tokens` has no direct replacement: thinking is adaptive, and the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) is a separate output-level control, not a thinking budget.
Before (Claude Mythos Preview):
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-mythos-preview",
"max_tokens": 16000,
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"messages": [
{
"role": "user",
"content": "..."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-mythos-preview
max_tokens: 16000
thinking:
type: enabled
budget_tokens: 10000
messages:
- role: user
content: "..."
YAML
```
```python Python
client.messages.create(
model="claude-mythos-preview",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-mythos-preview",
max_tokens: 16000,
thinking: { type: "enabled", budget_tokens: 10000 },
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = "claude-mythos-preview",
MaxTokens = 16000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),
Messages = [new() { Role = Role.User, Content = "..." }]
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: "claude-mythos-preview",
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(10000),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-mythos-preview")
.maxTokens(16000L)
.enabledThinking(10000L)
.addUserMessage("...")
.build();
Message response = client.messages().create(params);
IO.println(response);
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 16000,
messages: [['role' => 'user', 'content' => '...']],
model: 'claude-mythos-preview',
thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
);
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-mythos-preview",
max_tokens: 16000,
thinking: {
type: "enabled",
budget_tokens: 10000
},
messages: [
{ role: "user", content: "..." }
]
)
```
</CodeGroup>
After (Claude Mythos 5):
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-mythos-5",
"max_tokens": 16000,
"messages": [
{
"role": "user",
"content": "..."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-mythos-5
max_tokens: 16000
messages:
- role: user
content: "..."
YAML
```
```python Python
client.messages.create(
model="claude-mythos-5",
max_tokens=16000,
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-mythos-5",
max_tokens: 16000,
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = "claude-mythos-5",
MaxTokens = 16000,
Messages = [new() { Role = Role.User, Content = "..." }]
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: "claude-mythos-5",
MaxTokens: 16000,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-mythos-5")
.maxTokens(16000L)
.addUserMessage("...")
.build();
Message response = client.messages().create(params);
IO.println(response);
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 16000,
messages: [['role' => 'user', 'content' => '...']],
model: 'claude-mythos-5',
);
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-mythos-5",
max_tokens: 16000,
Cut at 300 lines. The page has the rest.
about-claude/models/model-ids-and-versions First recorded · 83 lines, first recorded
## Model ID format ### The 4.6 generation and later ### Before the 4.6 generation ## Dateless IDs are pinned snapshots ## Model weights versus serving infrastructure ## Current model IDs
The first capture of this source. The page was already there, and this is what it said.
---
title: Model IDs and versioning
url: https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions
description: How Claude model IDs are structured and versioned, including the dateless format introduced with the Claude 4.6 generation and what it means for stability.
---
Each Claude model ID identifies a pinned version of the model. When you use a model ID in an API request, the underlying model remains constant for the lifetime of that ID. This guarantee covers model IDs, not the convenience aliases that the Claude API accepts for some earlier models (see [Before the 4.6 generation](https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions#before-the-4-6-generation)).
## Model ID format
Claude model IDs follow a versioned naming scheme.
### The 4.6 generation and later
Starting with the Claude 4.6 generation, model IDs use a dateless format:
```text wrap
claude-{name}-{major}[-{minor}]
```
Major-version releases such as Claude Sonnet 5 and Claude Opus 5 omit the minor segment.
For example: `claude-sonnet-4-6`, `claude-sonnet-5`, `claude-opus-4-6`, `claude-opus-4-7`, `claude-opus-4-8`, and `claude-opus-5`
On Amazon Bedrock, the corresponding format is:
```text wrap
anthropic.claude-{name}-{major}[-{minor}]
```
For example: `anthropic.claude-sonnet-4-6`, `anthropic.claude-sonnet-5`, `anthropic.claude-opus-4-7`, `anthropic.claude-opus-4-8`, `anthropic.claude-opus-5`
Claude Opus 4.6 is the last Bedrock model ID to include the `-v1` suffix (`anthropic.claude-opus-4-6-v1`). Anthropic dropped the suffix starting with Claude Sonnet 4.6.
On Google Cloud, the format matches the Claude API.
### Before the 4.6 generation
Models before the 4.6 generation include a snapshot date in the ID:
```text wrap
claude-{name}-{major}-{minor}-{YYYYMMDD}
```
For example: `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001`
On Amazon Bedrock, these use the format:
```text wrap
anthropic.claude-{name}-{major}-{minor}-{YYYYMMDD}-v1:0
```
For example: `anthropic.claude-sonnet-4-5-20250929-v1:0`
On Google Cloud, the date is separated with `@`:
```text wrap
claude-{name}-{major}-{minor}@{YYYYMMDD}
```
For example: `claude-haiku-4-5@20251001`
On the Claude API, these models also have shorter aliases (for example, `claude-sonnet-4-5`) that point to the most recent dated snapshot for that minor version.
## Dateless IDs are pinned snapshots
A common misconception is that dateless model IDs such as `claude-sonnet-4-6` behave as evergreen pointers that route to the latest or best-performing version. That is not the case.
For the 4.6 generation and later, the dateless ID is the canonical model ID for that release. It maps to a single, fixed model snapshot. Anthropic does not update the weights or configuration of an existing model ID. When an updated version is available, it ships under a new model ID.
This differs from the dateless aliases that exist on the Claude API for earlier models. An alias such as `claude-sonnet-4-5` is a convenience pointer that resolves to the most recent dated snapshot for that minor version. A 4.6-generation ID such as `claude-sonnet-4-6` is not an alias. It is the snapshot.
Every model ID, whether dated or dateless, has its own distinct deprecation and retirement schedule.
## Model weights versus serving infrastructure
Model weights are fixed for a given ID, but the serving infrastructure around the model can change over time. This infrastructure includes components such as the request router, safety classifiers, and sampling logic.
Occasionally, infrastructure updates produce minor differences in observable behavior even when the model ID and weights have not changed. If you notice unexpected behavioral differences on a previously stable model ID, an infrastructure update is the most likely cause.
## Current model IDs
For the full list of current model IDs and their Amazon Bedrock and Google Cloud equivalents, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview).
about-claude/models/overview First recorded · 183 lines, first recorded
## Choosing a model ### Claude Fable 5 and Claude Mythos 5 ### Latest models comparison ## Prompt and output performance ## Migrating to Claude Opus 5 ## Get started with Claude
The first capture of this source. The page was already there, and this is what it said.
---
title: Models overview
url: https://platform.claude.com/docs/en/about-claude/models/overview
description: Claude is a family of state-of-the-art large language models developed by Anthropic. This guide introduces the available models and compares their performance.
---
## Choosing a model
If you're unsure which model to use, start with **Claude Opus 5** for complex agentic coding and enterprise work. For workloads that need the highest available capability, use [Claude Fable 5](https://platform.claude.com/docs/en/about-claude/models/overview#claude-fable-5-and-claude-mythos-5).
All current Claude models support text and image input, text output, multilingual capabilities, and vision. Models are available through the Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Google Cloud](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry).
Once you've picked a model, [learn how to make your first API call](https://platform.claude.com/docs/en/get-started).
### Claude Fable 5 and Claude Mythos 5
Claude Fable 5 (`claude-fable-5`) is Anthropic's most capable widely released model. Claude Mythos 5 (`claude-mythos-5`) shares Claude Fable 5's specs and pricing and joins the invitation-only Claude Mythos Preview (`claude-mythos-preview`) within [Project Glasswing](https://anthropic.com/glasswing). See [Introducing Claude Fable 5 and Claude Mythos 5](https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5) for launch details and API changes.
Claude Fable 5 is generally available on the Claude API, Amazon Bedrock, Claude Platform on AWS, Google Cloud, and Microsoft Foundry beginning June 9, 2026. Claude Mythos 5 is not generally available: it is offered in limited availability to approved customers in [Project Glasswing](https://anthropic.com/glasswing), beginning the same day. For access, contact your Anthropic, AWS, or Google Cloud account team.
### Latest models comparison
| Feature | Claude Fable 5 | Claude Opus 5 | Claude Sonnet 5 | Claude Haiku 4.5 |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| **Description** | Next-generation intelligence for long-running agents | For complex agentic coding and enterprise work | The best combination of speed and intelligence | The fastest model with near-frontier intelligence |
| **Claude API ID** | claude-fable-5 | claude-opus-5 | claude-sonnet-5 | claude-haiku-4-5-20251001 |
| **Claude API alias** | claude-fable-5 | claude-opus-5 | claude-sonnet-5 | claude-haiku-4-5 |
| **AWS Bedrock ID** | anthropic.claude-fable-53 | anthropic.claude-opus-53 | anthropic.claude-sonnet-53 | anthropic.claude-haiku-4-5-20251001-v1:0 |
| **Google Cloud ID** | claude-fable-5 | claude-opus-5 | claude-sonnet-5 | claude-haiku-4-5\@20251001 |
| **Pricing**1 | $10 / input MTok $50 / output MTok | $5 / input MTok $25 / output MTok | $2 / input MTok $10 / output MTok | $1 / input MTok $5 / output MTok |
| **[Extended thinking (`thinking.type: "enabled"`)](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)** | No | No | No | Yes |
| **[Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking)** | Yes (always on) | Yes | Yes | No |
| **Comparative latency** | Slower | Moderate | Fast | Fastest |
| **Context window** | <Tooltip tooltipContent="~555k words \ ~2.5M unicode characters. Claude Fable 5 uses the tokenizer introduced with Claude Opus 4.7; compared to models before Claude Opus 4.7, the same text produces roughly 30% more tokens. The exact increase depends on the content.">1M tokens</Tooltip> | <Tooltip tooltipContent="~555k words \ ~2.5M unicode characters">1M tokens</Tooltip> | <Tooltip tooltipContent="~555k words \ ~2.5M unicode characters">1M tokens</Tooltip> | <Tooltip tooltipContent="~150k words \ ~680k unicode characters">200k tokens</Tooltip> |
| **Max output** | 128k tokens | 128k tokens | 128k tokens | 64k tokens |
| **Reliable knowledge cutoff** | Jan 20262 | May 20262 | Jan 20262 | Feb 2025 |
| **Training data cutoff** | Jan 2026 | May 2026 | Jan 2026 | Jul 2025 |
*1 See [Pricing](https://platform.claude.com/docs/en/about-claude/pricing) for complete pricing information including Batch API discounts and prompt caching rates.*
*2 **Reliable knowledge cutoff** indicates the date through which a model's knowledge is most extensive and reliable. **Training data cutoff** is the broader date range of training data used. For more information, see [Anthropic's Transparency Hub](https://www.anthropic.com/transparency).*
*3 Claude Fable 5, Claude Opus 5, and Claude Sonnet 5 are available on Bedrock through [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) (the Messages-API Bedrock endpoint).*
<Info>
Claude Mythos 5 and Claude Mythos Preview are offered separately for defensive cybersecurity workflows as part of [Project Glasswing](https://anthropic.com/glasswing). Access is invitation-only and there is no self-serve sign-up.
</Info>
<Note>
Every Claude model ID is a pinned snapshot. Models with a date in the ID (for example,
`20250929`
) are fixed to that specific release. Starting with the Claude 4.6 generation, model IDs use a dateless format that is also a pinned snapshot, not an evergreen pointer. For models before the 4.6 generation, entries in the Claude API alias column are convenience pointers that resolve to a dated model ID. For details on the naming convention and how versioning works, see
[Model IDs and versioning](https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions)
.
</Note>
<Note>
Starting with
**Claude Sonnet 4.5 and all subsequent models**
(including Claude Sonnet 4.6), Bedrock offers two endpoint types:
**global endpoints**
(dynamic routing for maximum availability) and
**regional endpoints**
(guaranteed data routing through specific geographic regions). Google Cloud offers three endpoint types: global endpoints,
**multi-region endpoints**
(dynamic routing within a geographic area), and regional endpoints. For more information, see
[Cloud platform pricing](https://platform.claude.com/docs/en/about-claude/pricing#cloud-platform-pricing)
.
</Note>
<Note>
**Claude Platform on AWS**
uses the same model IDs as the Claude API (for example,
`claude-opus-4-6`
), not Bedrock-style IDs. Model lifecycle on Claude Platform on AWS follows Anthropic's first-party
[Model deprecations](https://platform.claude.com/docs/en/about-claude/model-deprecations)
, not Bedrock's. See
[Available models](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#available-models)
for the model list.
</Note>
<Tip>
You can query model capabilities and token limits programmatically with the [Models API](https://platform.claude.com/docs/en/api/models/list). The response includes `max_input_tokens`, `max_tokens`, and a `capabilities` object for every available model.
</Tip>
<Note>
On Claude Opus 4.8, the `effort` parameter defaults to `high` on all surfaces, including the Claude API, Claude Code, and claude.ai. On Claude Opus 5 and Claude Sonnet 5, it defaults to `high` on the Claude API and Claude Code. Set `effort` explicitly to use a different level. See [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) for guidance on choosing a level.
</Note>
<Note>
The Max output values in the table apply to the synchronous Messages API. On the [Message Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing#extended-output-beta), Claude Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5, and Sonnet 4.6 support up to 300k output tokens by using the `output-300k-2026-03-24` beta header.
</Note>
<AccordionGroup>
<Accordion title="Legacy models">
The following models are still available. Consider migrating to current models for improved performance:
| Feature | Claude Opus 4.8 | Claude Opus 4.7 | Claude Opus 4.6 | Claude Sonnet 4.6 | Claude Sonnet 4.5 | Claude Opus 4.5 |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Claude API ID** | claude-opus-4-8 | claude-opus-4-7 | claude-opus-4-6 | claude-sonnet-4-6 | claude-sonnet-4-5-20250929 | claude-opus-4-5-20251101 |
| **Claude API alias** | claude-opus-4-8 | claude-opus-4-7 | claude-opus-4-6 | claude-sonnet-4-6 | claude-sonnet-4-5 | claude-opus-4-5 |
| **AWS Bedrock ID** | anthropic.claude-opus-4-86 | anthropic.claude-opus-4-76 | anthropic.claude-opus-4-6-v1 | anthropic.claude-sonnet-4-6 | anthropic.claude-sonnet-4-5-20250929-v1:0 | anthropic.claude-opus-4-5-20251101-v1:0 |
| **Google Cloud ID** | claude-opus-4-8 | claude-opus-4-7 | claude-opus-4-6 | claude-sonnet-4-6 | claude-sonnet-4-5\@20250929 | claude-opus-4-5\@20251101 |
| **Pricing** | $5 / input MTok $25 / output MTok | $5 / input MTok $25 / output MTok | $5 / input MTok $25 / output MTok | $3 / input MTok $15 / output MTok | $3 / input MTok $15 / output MTok | $5 / input MTok $25 / output MTok |
| **[Extended thinking (`thinking.type: "enabled"`)](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)** | No | No | Yes (deprecated) | Yes (deprecated) | Yes | Yes |
| **[Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking)** | Yes | Yes | Yes | Yes | No | No |
| **Comparative latency** | Moderate | Moderate | Moderate | Fast | Fast | Moderate |
| **Context window** | <Tooltip tooltipContent="~555k words \ ~2.5M unicode characters">1M tokens</Tooltip> | <Tooltip tooltipContent="~555k words \ ~2.5M unicode characters (Opus 4.7 uses a new tokenizer)">1M tokens</Tooltip> | <Tooltip tooltipContent="~750k words \ ~3.4M unicode characters">1M tokens</Tooltip> | <Tooltip tooltipContent="~750k words \ ~3.4M unicode characters">1M tokens</Tooltip> | <Tooltip tooltipContent="~150k words \ ~680k unicode characters">200k tokens</Tooltip> | <Tooltip tooltipContent="~150k words \ ~680k unicode characters">200k tokens</Tooltip> |
| **Max output** | 128k tokens | 128k tokens | 128k tokens | 128k tokens | 64k tokens | 64k tokens |
| **Reliable knowledge cutoff** | Jan 20265 | Jan 20265 | May 20255 | Aug 20255 | Jan 20255 | May 20255 |
| **Training data cutoff** | Jan 2026 | Jan 2026 | Aug 2025 | Jan 2026 | Jul 2025 | Aug 2025 |
*5 **Reliable knowledge cutoff** indicates the date through which a model's knowledge is most extensive and reliable. **Training data cutoff** is the broader date range of training data used.*
*6 Claude Opus 4.8 and Claude Opus 4.7 are available on Bedrock through [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) (the Messages-API Bedrock endpoint).*
</Accordion>
</AccordionGroup>
## Prompt and output performance
Current Claude models excel in:
* **Performance:** Top-tier results in reasoning, coding, multilingual tasks, long-context handling, honesty, and image processing. See [Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) for general and model-specific prompting guidance.
* **Engaging responses:** Claude models are ideal for applications that require rich, human-like interactions.
* If you prefer more concise responses, you can adjust your prompts to guide the model toward the desired output length. Refer to the [prompt engineering guides](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering) for details.
* For prompting best practices, see [Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices).
* **Output quality:** When migrating from a previous model generation, you may notice larger improvements in overall performance.
## Migrating to Claude Opus 5
If you're currently using Claude Opus 4.8 or earlier Claude models, see [Migrating to Claude Opus 5](https://platform.claude.com/docs/en/about-claude/models/migration-guide#migrating-from-claude-opus-4-8-to-claude-opus-5).
## Get started with Claude
If you're ready to start exploring what Claude can do for you, dive in! Whether you're a developer looking to integrate Claude into your applications or a user wanting to experience the power of AI firsthand, the following resources can help.
<Note>
Looking to chat with Claude? Visit
[claude.ai](https://claude.ai)
!
</Note>
<CardGroup cols={3}>
<Card title="Intro to Claude" icon="check" href="https://platform.claude.com/docs/en/intro">
Explore Claude's capabilities and development flow.
</Card>
<Card title="Quickstart" icon="lightning" href="https://platform.claude.com/docs/en/get-started">
Learn how to make your first API call in minutes.
</Card>
<Card title="Claude Console" icon="code" href="https://platform.claude.com/">
Craft and test powerful prompts directly in your browser.
</Card>
</CardGroup>
If you have any questions or need assistance, don't hesitate to reach out to the [support team](https://support.claude.com/) or consult the [Discord community](https://www.anthropic.com/discord).
about-claude/models/whats-new-opus-5 First recorded · 351 lines, first recorded
## New model ## New features ### Mid-conversation tool changes (beta) ### Default fallbacks mode ### Lower prompt cache minimum ### Fast mode ## Behavior changes ### Thinking on by default ### Effort matters more ### Disabling thinking requires effort `high` or below ### Model behavior differences ## Capability improvements ## Pricing ## Availability ## Migration guide ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: What's new in Claude Opus 5
url: https://platform.claude.com/docs/en/about-claude/models/whats-new-opus-5
description: Overview of new features and behavior changes in Claude Opus 5.
---
Claude Opus 5 is a step-change improvement over Claude Opus 4.8, with the largest gains in deep reasoning, agentic and long-horizon tasks, and test-time compute scaling. This page summarizes everything new in Claude Opus 5, including thinking on by default, mid-conversation tool changes, and a breaking change to when thinking can be disabled.
## New model
| Model | API model ID | Description |
| ------------- | --------------- | ---------------------------------------------- |
| Claude Opus 5 | `claude-opus-5` | For complex agentic coding and enterprise work |
Claude Opus 5 has a [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) (1M tokens is both the default and the maximum; there is no smaller context variant), 128k max output tokens, and [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) on by default.
For complete pricing and specs, see the [models overview](https://platform.claude.com/docs/en/about-claude/models/overview).
## New features
### Mid-conversation tool changes (beta)
You can add or remove tools between turns of a conversation while preserving the prompt cache, instead of resending a fixed tool list for the life of a session. Mid-conversation tool changes are in beta: include the `mid-conversation-tool-changes-2026-07-01` beta header in your requests. See [Mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes) for usage.
### Default fallbacks mode
The `fallbacks` parameter supports a new `"default"` mode, which applies Anthropic's recommended fallback models by refusal category instead of a model list you maintain yourself. The entire `fallbacks` parameter is in beta. Use the `server-side-fallback-2026-07-01` beta header, which supports both the `"default"` mode and explicit model lists (the earlier `server-side-fallback-2026-06-01` header accepts only explicit lists). See [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback).
### Lower prompt cache minimum
The minimum cacheable prompt length on Claude Opus 5 is 512 tokens, down from 1,024 tokens on Claude Opus 4.8. Prompts that were too short to cache on Claude Opus 4.8 can now create cache entries with no code changes. See [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations) for per-model minimums.
### Fast mode
[Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) (research preview) is available for Claude Opus 5 on the Claude API only; it is not currently available on Amazon Bedrock, Google Cloud, or Microsoft Foundry. Fast mode for Claude Opus 5 is priced at $10 USD per million input tokens and $50 USD per million output tokens. See [Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) for access, supported models, and pricing.
## Behavior changes
### Thinking on by default
On Claude Opus 4.8, requests run without thinking unless you set `thinking: {"type": "adaptive"}`. On Claude Opus 5, the same requests run with [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) on: the model decides when and how much to think on each turn, and the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) is the control for thinking depth. The wire value is unchanged; `thinking: {"type": "adaptive"}` remains valid and equivalent to the default.
Because `max_tokens` is a hard limit on total output (thinking plus response text), revisit it for workloads that ran without thinking on Claude Opus 4.8.
The API keeps the option to disable thinking, subject to the effort restriction below.
### Effort matters more
Claude Opus 5 converts additional [effort](https://platform.claude.com/docs/en/build-with-claude/effort) into better results more reliably than any earlier Opus model, so the effort level you choose carries more weight. The full ladder is available: `low`, `medium`, `high`, `xhigh`, and `max`, with `max` as the top tier for the deepest possible reasoning. Start at the default, `high`, and adjust in either direction based on your evals: step down where quality holds to save tokens and latency, or step up for the most demanding work. When running at `xhigh` or `max` effort, set a large `max_tokens` so the model has room to think and act across subagents and tool calls.
This request turns effort all the way up to `max`:
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 64000,
"stream": true,
"output_config": {
"effort": "max"
},
"messages": [
{
"role": "user",
"content": "Explain why the sum of two even numbers is always even."
}
]
}'
```
```bash CLI
# 64k max_tokens can run past the non-streaming time limit; stream the events.
ant messages create --stream --format jsonl <<'YAML'
model: claude-opus-5
max_tokens: 64000
output_config:
effort: max
messages:
- role: user
content: Explain why the sum of two even numbers is always even.
YAML
```
```python Python
client = anthropic.Anthropic()
with client.messages.stream(
model="claude-opus-5",
max_tokens=64000,
output_config={"effort": "max"},
messages=[
{
"role": "user",
"content": "Explain why the sum of two even numbers is always even.",
}
],
) as stream:
response = stream.get_final_message()
print(response)
```
```typescript TypeScript
const client = new Anthropic();
const stream = client.messages.stream({
model: "claude-opus-5",
max_tokens: 64000,
output_config: {
effort: "max"
},
messages: [
{
role: "user",
content: "Explain why the sum of two even numbers is always even."
}
]
});
const response = await stream.finalMessage();
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 64000,
OutputConfig = new OutputConfig
{
Effort = Effort.Max
},
Messages = [new() { Role = Role.User, Content = "Explain why the sum of two even numbers is always even." }]
};
var response = await client.Messages.CreateStreaming(parameters).Aggregate();
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 64000,
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortMax,
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Explain why the sum of two even numbers is always even.")),
},
})
response := anthropic.Message{}
for stream.Next() {
event := stream.Current()
if err := response.Accumulate(event); err != nil {
log.Fatal(err)
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(64000L)
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.MAX)
.build())
.addUserMessage("Explain why the sum of two even numbers is always even.")
.build();
MessageAccumulator accumulator = MessageAccumulator.create();
try (var streamResponse = client.messages().createStreaming(params)) {
streamResponse.stream().forEach(accumulator::accumulate);
}
Message response = accumulator.message();
IO.println(response);
```
```php PHP
$client = new Client();
$stream = $client->messages->createStream(
maxTokens: 64000,
messages: [
['role' => 'user', 'content' => 'Explain why the sum of two even numbers is always even.']
],
model: Model::CLAUDE_OPUS_5,
outputConfig: ['effort' => Effort::MAX],
);
$accumulator = MessageAccumulator::forMessages();
foreach ($stream as $event) {
$accumulator->accumulate($event);
}
echo $accumulator->message();
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.stream(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 64000,
output_config: {
effort: :max
},
messages: [
{ role: "user", content: "Explain why the sum of two even numbers is always even." }
]
).accumulated_message
puts response
```
</CodeGroup>
Thinking is [on by default](https://platform.claude.com/docs/en/about-claude/models/whats-new-opus-5#thinking-on-by-default) on Claude Opus 5, so no `thinking` field is needed.
### Disabling thinking requires effort `high` or below
On Claude Opus 5, `thinking: {"type": "disabled"}` is accepted only when the effort level is `high` or below. Setting `thinking: {"type": "disabled"}` with effort `xhigh` or `max` returns a 400 error. This is generally available behavior on Claude Opus 5 onward, enforced on each request, and it is a breaking change from Claude Opus 4.8, where disabling thinking was independent of the effort level. If you disable thinking at high effort levels today, either keep thinking disabled and set effort to `high` or below, or keep the effort level and remove the `thinking` field.
With thinking disabled, Claude Opus 5 can occasionally write a tool call into its text output instead of emitting a `tool_use` block, or include internal XML tags in its visible response. Where possible, keep thinking enabled and control token cost with lower effort levels; for integrations that must keep thinking disabled, see [Running with thinking disabled](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#running-with-thinking-disabled) for prompting mitigations.
### Model behavior differences
Beyond the API changes above, Claude Opus 5 behaves differently from Claude Opus 4.8 in ways you may notice without changing any code. Default user-facing responses and written deliverables run longer. In agentic sessions, the model narrates its progress to the user more often. In multi-agent frameworks, it delegates to subagents more readily. It also verifies its own work without being told to, so remove verification instructions carried over from earlier models ("include a final verification step," "use a subagent to verify"); they cause over-verification on Claude Opus 5. For prompting patterns that tune each of these behaviors, see [Prompting Claude Opus 5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5).
## Capability improvements
Compared with Claude Opus 4.8, Claude Opus 5 is a step-change improvement rather than an incremental one, and it delivers frontier intelligence at half the cost of Claude Fable 5. The largest gains are in:
* **Deep reasoning**, sustaining multistep analysis across long problem chains.
* **Agentic coding and long-horizon tasks**, staying on task across extended tool-use loops and completing multi-file features, larger refactors, and end-to-end feature work without leaving stubs or placeholders.
* **Test-time compute scaling**, converting additional effort (up to the `max` level) into better results.
* **Efficiency at lower effort levels**, with `low` and `medium` [effort](https://platform.claude.com/docs/en/build-with-claude/effort) producing strong quality at a fraction of the tokens and latency of higher settings.
* **Code review and bug-finding**, surfacing real bugs at a high rate per pass with few false positives, and staying accurate at lower effort levels.
* **Vision**, understanding charts, documents, and diagrams and replicating UI and frontend visuals, strongest when given tools to iteratively analyze, crop, and verify its work.
* **Long-context work**, with a [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) as both the default and the maximum, and consistent instruction following, tool calling, and reasoning throughout the window.
* **Office and document tasks**, generating and editing complex multi-sheet spreadsheets with non-trivial formulas, and producing well-structured slide decks.
* **Multi-agent coordination**, running teams of subagents with effective writer-verifier patterns and few cases of agents overwriting each other's work.
For the prompting patterns that get the most out of these capabilities, see [Prompting Claude Opus 5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5#capability-improvements).
## Pricing
Claude Opus 5 is priced at $5 USD per million input tokens and $25 USD per million output tokens, unchanged from Claude Opus 4.8.
See [Pricing](https://platform.claude.com/docs/en/about-claude/pricing) for complete pricing, including batch processing, prompt caching, and fast mode rates.
## Availability
Claude Opus 5 is available on:
* **Claude API:** available to all customers, as `claude-opus-5`.
* **AWS:** available through [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), as `anthropic.claude-opus-5`. Claude Opus 5 is also reachable through the `InvokeModel` API on `bedrock-runtime`, served by the same infrastructure; the [Claude on Amazon Bedrock (legacy)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) integration does not include it in its ARN-versioned model ID table.
* **Google Cloud:** available through [Claude on Google Cloud](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai), as `claude-opus-5`.
* **Microsoft Foundry:** available through [Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry).
Claude Opus 4.8 remains available on all of these platforms.
## Migration guide
To migrate from Claude Opus 4.8, update your model ID:
<CodeGroup exclude="shell">
```python Python
model = "claude-opus-4-8" # Before
model = "claude-opus-5" # After
```
```typescript TypeScript
let model = "claude-opus-4-8"; // Before
model = "claude-opus-5"; // After
```
```csharp C#
var model = Model.ClaudeOpus4_8; // Before
model = Model.ClaudeOpus5; // After
```
```go Go
model := anthropic.ModelClaudeOpus4_8 // Before
model = anthropic.ModelClaudeOpus5 // After
Cut at 300 lines. The page has the rest.
about-claude/models/whats-new-sonnet-5 First recorded · 216 lines, first recorded
## New model ## Behavior changes ### Adaptive thinking on by default ### Sampling parameters not accepted ### Manual extended thinking removed ## New tokenizer ## API constraints inherited from Claude Sonnet 4.6 ### Assistant message prefilling not supported ## Capability improvements ## Cybersecurity safeguards ## Pricing ## Availability ## Migration guide ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: What's new in Claude Sonnet 5
url: https://platform.claude.com/docs/en/about-claude/models/whats-new-sonnet-5
description: Overview of new features and behavior changes in Claude Sonnet 5.
---
Claude Sonnet 5 is the next generation of Anthropic's Sonnet model family. It is a drop-in upgrade for Claude Sonnet 4.6 with three behavior changes: [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) is on by default, manual extended thinking now returns a 400 error (it was deprecated on Claude Sonnet 4.6), and setting sampling parameters (`temperature`, `top_p`, `top_k`) to non-default values returns a 400 error. This page summarizes everything new at launch, including a new tokenizer.
## New model
| Model | API model ID | Description |
| --------------- | ----------------- | ---------------------------------------------- |
| Claude Sonnet 5 | `claude-sonnet-5` | The best combination of speed and intelligence |
Claude Sonnet 5 supports the [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) by default (1M tokens is both the default and the maximum; there is no smaller context variant), 128k max output tokens, [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking), and the same set of tools and platform features as Claude Sonnet 4.6, except [Priority Tier](https://platform.claude.com/docs/en/api/service-tiers#supported-models), which is not available on Claude Sonnet 5.
For complete pricing and specs, see the [models overview](https://platform.claude.com/docs/en/about-claude/models/overview).
## Behavior changes
### Adaptive thinking on by default
On Claude Sonnet 4.6, requests without a `thinking` field run without thinking. On Claude Sonnet 5, the same requests run with [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking). To turn thinking off, pass `thinking: {type: "disabled"}`. Because `max_tokens` is a hard limit on total output (thinking plus response text), revisit it for workloads that ran without thinking on Claude Sonnet 4.6.
### Sampling parameters not accepted
Setting `temperature`, `top_p`, or `top_k` to a non-default value returns a 400 error. Remove these parameters when migrating; the default value (or omitting the parameter) is accepted. Use system-prompt instructions to guide model behavior. This is new for Sonnet-class models; the same constraint was previously introduced on Claude Opus 4.7.
### Manual extended thinking removed
Manual extended thinking (`thinking: {type: "enabled", budget_tokens: N}`) was deprecated on Claude Sonnet 4.6; on Claude Sonnet 5 it is removed and returns a 400 error, the same as on Claude Opus 4.8 and Claude Opus 4.7. Use adaptive thinking with the [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) instead.
<CodeGroup exclude="shell">
```python Python
# Not supported on Claude Sonnet 5 (returns 400)
thinking = {"type": "enabled", "budget_tokens": 32000}
# Use this instead
thinking = {"type": "adaptive"}
```
```typescript TypeScript
// Not supported on Claude Sonnet 5 (returns 400)
const legacyThinking = { type: "enabled", budget_tokens: 32000 };
// Use this instead
const thinking = { type: "adaptive" };
```
```csharp C#
// Not supported on Claude Sonnet 5 (returns 400)
var legacyThinking = new ThinkingConfigEnabled(budgetTokens: 32000);
// Use this instead
var thinking = new ThinkingConfigAdaptive();
```
```go Go
// Not supported on Claude Sonnet 5 (returns 400)
legacyThinking := anthropic.ThinkingConfigParamUnion{
OfEnabled: &anthropic.ThinkingConfigEnabledParam{BudgetTokens: 32000},
}
// Use this instead
thinking := anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
}
```
```java Java
// Not supported on Claude Sonnet 5 (returns 400)
var legacyThinking = ThinkingConfigEnabled.builder().budgetTokens(32_000L).build();
// Use this instead
var thinking = ThinkingConfigAdaptive.builder().build();
```
```php PHP
// Not supported on Claude Sonnet 5 (returns 400)
$thinking = ['type' => 'enabled', 'budget_tokens' => 32000];
// Use this instead
$thinking = ['type' => 'adaptive'];
```
```ruby Ruby
# Not supported on Claude Sonnet 5 (returns 400)
legacy_thinking = {type: "enabled", budget_tokens: 32_000}
# Use this instead
thinking = {type: "adaptive"}
```
</CodeGroup>
## New tokenizer
Claude Sonnet 5 uses a new tokenizer. The same input text produces approximately 30% more tokens than on Claude Sonnet 4.6. The exact increase depends on the content. This is not an API change: requests, responses, and streaming events keep the same shape, and no code changes are required.
The change affects anything you measure or budget in tokens:
* **Token counts:** `usage` fields and [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) results for the same text are higher than on Claude Sonnet 4.6. Don't reuse counts measured against earlier models; recount against Claude Sonnet 5.
* **Context window capacity in text terms:** the context window is 1M tokens, but each token covers less text on average, so the same window holds less text than on Claude Sonnet 4.6.
* **`max_tokens` budgets:** an output limit tuned for Claude Sonnet 4.6 may truncate equivalent output on Claude Sonnet 5. Revisit limits sized close to your expected output length.
* **Per-request cost:** per-token pricing is lower than Claude Sonnet 4.6's (see [Pricing](https://platform.claude.com/docs/en/about-claude/models/whats-new-sonnet-5#pricing)), but because the same text produces more tokens, the cost of an equivalent request does not drop in direct proportion.
## API constraints inherited from Claude Sonnet 4.6
<Note>
This constraint is unchanged from Claude Sonnet 4.6. Aside from the three [behavior changes](https://platform.claude.com/docs/en/about-claude/models/whats-new-sonnet-5#behavior-changes) (see [Migration guide](https://platform.claude.com/docs/en/about-claude/models/whats-new-sonnet-5#migration-guide)), code that already runs on Claude Sonnet 4.6 needs no other changes.
</Note>
### Assistant message prefilling not supported
Prefilling the assistant message returns a `400` error, unchanged from Claude Sonnet 4.6. Use [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs), system prompt instructions, or `output_config.format` instead.
## Capability improvements
Claude Sonnet 5 is a capability upgrade over Claude Sonnet 4.6 at a lower price. It is also an option for workloads that need more capability than Claude Sonnet 4.6 provides without moving to an Opus-class model.
The largest gains over Claude Sonnet 4.6 are in coding and agentic tasks. For benchmark results, see [Anthropic's Transparency Hub](https://www.anthropic.com/transparency).
## Cybersecurity safeguards
Claude Sonnet 5 is the first Sonnet-tier model with real-time cybersecurity safeguards. Requests that involve prohibited or high-risk cybersecurity topics may be refused. Refusals return as a successful HTTP 200 response with `stop_reason: "refusal"`, not an error. See [Safeguards, warnings, and appeals](https://support.claude.com/en/articles/8241253-safeguards-warnings-and-appeals) for background.
## Pricing
Claude Sonnet 5 is priced at $2 per million input tokens and $10 per million output tokens, lower per-token pricing than Claude Sonnet 4.6's $3/$15. Because the [new tokenizer](https://platform.claude.com/docs/en/about-claude/models/whats-new-sonnet-5#new-tokenizer) produces approximately 30% more tokens for the same text, the cost of an equivalent request does not drop in direct proportion to the per-token prices when comparing with Claude Sonnet 4.6. The exact difference depends on the content and workload shape.
See [Pricing](https://platform.claude.com/docs/en/about-claude/pricing) for complete pricing, including batch processing and prompt caching rates.
## Availability
At launch, Claude Sonnet 5 is available on:
* **Claude API:** available to all customers.
* **AWS:** available through [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) and [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws). On Amazon Bedrock, Claude Sonnet 5 is also reachable through the `InvokeModel` API, served by the same infrastructure as Claude in Amazon Bedrock. The legacy [Claude on Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) integration does not include Claude Sonnet 5.
* **Google Cloud:** available through [Claude on Google Cloud](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai).
* **Microsoft Foundry:** available through [Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry).
Claude Sonnet 5 supports [zero data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention) for organizations with ZDR agreements.
## Migration guide
Claude Sonnet 5 is a drop-in replacement for Claude Sonnet 4.6. Update your model ID:
<CodeGroup exclude="shell">
```python Python
model = "claude-sonnet-4-6" # Before
model = "claude-sonnet-5" # After
```
```typescript TypeScript
const legacyModel = "claude-sonnet-4-6"; // Before
const model = "claude-sonnet-5"; // After
```
```csharp C#
var legacyModel = Model.ClaudeSonnet4_6; // Before
var model = Model.ClaudeSonnet5; // After
```
```go Go
// Before
legacyModel := anthropic.ModelClaudeSonnet4_6
// After
model := anthropic.ModelClaudeSonnet5
```
```java Java
var legacyModel = Model.CLAUDE_SONNET_4_6; // Before
var model = Model.CLAUDE_SONNET_5; // After
```
```php PHP
$model = 'claude-sonnet-4-6'; // Before
$model = 'claude-sonnet-5'; // After
```
```ruby Ruby
legacy_model = "claude-sonnet-4-6" # Before
model = "claude-sonnet-5" # After
```
</CodeGroup>
Then review the following:
1. **Token budgets and counts:** the [new tokenizer](https://platform.claude.com/docs/en/about-claude/models/whats-new-sonnet-5#new-tokenizer) produces approximately 30% more tokens for the same text. The exact increase depends on the content and workload shape. Recount prompts with [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting), and revisit `max_tokens` limits sized close to your expected output length.
2. **Extended thinking:** if you still set `budget_tokens`, migrate to [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking). Manual extended thinking (`thinking: {type: "enabled"}`) is not supported and returns a 400 error.
3. **Sampling parameters:** requests that set sampling parameters (`temperature`, `top_p`, `top_k`) to a non-default value return a 400 error; remove them when migrating. Tool definitions and response shapes are unchanged, and assistant message prefilling was already unsupported on Claude Sonnet 4.6.
See the [Claude Sonnet 5 section of the migration guide](https://platform.claude.com/docs/en/about-claude/models/migration-guide#migrating-from-claude-sonnet-4-6-to-claude-sonnet-5) for details.
## Next steps
<CardGroup>
<Card title="Models overview" icon="arrow-right" href="https://platform.claude.com/docs/en/about-claude/models/overview">
Complete specs and pricing for all current Claude models.
</Card>
<Card title="Token counting" icon="database" href="https://platform.claude.com/docs/en/build-with-claude/token-counting">
Measure your prompts under the new tokenizer before you migrate.
</Card>
<Card title="Adaptive thinking" icon="brain" href="https://platform.claude.com/docs/en/build-with-claude/thinking">
The recommended thinking-on mode on Claude Sonnet 5.
</Card>
<Card title="Context windows" icon="sliders" href="https://platform.claude.com/docs/en/build-with-claude/context-windows">
How the 1M token context window works.
</Card>
<Card title="Pricing" icon="shield" href="https://platform.claude.com/docs/en/about-claude/pricing">
Complete pricing, including batch processing and prompt caching rates.
</Card>
</CardGroup>
about-claude/pricing First recorded · 506 lines, first recorded
## Model pricing ## Cloud platform pricing ## Claude Platform on AWS pricing ### Inference geography ### Private offers ## Claude in Microsoft Foundry pricing ### Inference geography ## Feature-specific pricing ### Prompt caching ### Data residency pricing ### Fast mode pricing ### Batch processing ### Long context pricing ### Tool use pricing ### Specific tool pricing #### Bash tool #### Code execution tool #### Text editor tool #### Web search tool #### Web fetch tool #### Computer use tool ## Claude Managed Agents pricing ### Tokens ### Session runtime ### Worked example ## Additional pricing considerations ### Cost optimization strategies ### Rate limits ### Volume discounts ### Enterprise pricing ## Billing and payment ## Frequently asked questions
The first capture of this source. The page was already there, and this is what it said.
---
title: Pricing
url: https://platform.claude.com/docs/en/about-claude/pricing
description: Learn about Anthropic's pricing structure for models and features
---
This page provides detailed pricing information for Anthropic's models and features. All prices are in USD.
For the most current pricing information, visit [claude.com/pricing](https://claude.com/pricing).
## Model pricing
The following table shows pricing for all Claude models:
| Model | Base Input Tokens | 5m Cache Writes | 1h Cache Writes | Cache Hits & Refreshes | Output Tokens |
| ------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------------- | --------------- | ---------------------- | ------------- |
| Claude Fable 5 | $10 / MTok | $12.50 / MTok | $20 / MTok | $1 / MTok | $50 / MTok |
| Claude Mythos 5 ([limited availability](https://anthropic.com/glasswing)) | $10 / MTok | $12.50 / MTok | $20 / MTok | $1 / MTok | $50 / MTok |
| Claude Opus 5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.8 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.7 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.6 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.1 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Sonnet 5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.20 / MTok | $10 / MTok |
| Claude Sonnet 4.6 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4.5 | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Sonnet 4 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / MTok |
| Claude Haiku 3.5 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $0.80 / MTok | $1 / MTok | $1.60 / MTok | $0.08 / MTok | $4 / MTok |
<Note id="claude-sonnet-5-introductory-pricing">
The $2/$10 per million input/output token pricing for Claude Sonnet 5, announced at launch as introductory pricing through August 31, 2026, is now the standard price. The previously scheduled increase to $3/$15 per million input/output tokens on September 1, 2026 will not occur.
</Note>
<Note>
MTok = Million tokens. The "Base Input Tokens" column shows standard input pricing, the "5m Cache Writes", "1h Cache Writes", and "Cache Hits & Refreshes" columns are specific to [prompt caching](https://platform.claude.com/docs/en/about-claude/pricing#prompt-caching), and "Output Tokens" shows output pricing. See [prompt caching pricing](https://platform.claude.com/docs/en/about-claude/pricing#prompt-caching) for an explanation of the cache columns and pricing multipliers.
</Note>
<Note>
Claude 4.7 and later models and Claude Mythos Preview use a newer tokenizer that contributes to their improved performance on a wide range of tasks. This tokenizer produces approximately 30% more tokens for the same text. The exact increase depends on the content and workload shape. Claude Sonnet 4.6 and earlier models use the previous tokenizer.
</Note>
For Claude Platform on AWS pricing, see [Claude Platform on AWS pricing](https://platform.claude.com/docs/en/about-claude/pricing#claude-platform-on-aws-pricing).
## Cloud platform pricing
This section covers partner-operated cloud platforms, where the cloud provider invoices you. For Anthropic-operated cloud platforms billed through a marketplace, see [Claude Platform on AWS pricing](https://platform.claude.com/docs/en/about-claude/pricing#claude-platform-on-aws-pricing) and [Claude in Microsoft Foundry pricing](https://platform.claude.com/docs/en/about-claude/pricing#claude-in-microsoft-foundry-pricing).
Claude models are available on [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) and [Google Cloud](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai). For official pricing, visit:
* [Amazon Bedrock pricing](https://aws.amazon.com/bedrock/pricing/)
* [Google Cloud pricing](https://cloud.google.com/vertex-ai/generative-ai/pricing#claude-models)
<Note>
**Regional and multi-region endpoint pricing for Claude 4.5 models and beyond**
Starting with Claude Sonnet 4.5, Haiku 4.5, and Opus 4.5:
* **Bedrock** offers two endpoint types: global endpoints (dynamic routing for maximum availability) and regional endpoints (guaranteed data routing through specific geographic regions).
* **Google Cloud** offers three endpoint types: global endpoints, multi-region endpoints (dynamic routing within a geographic area), and regional endpoints.
Regional and multi-region endpoints include a 10% premium over global endpoints. The Claude API (first-party) is global by default; for first-party data residency options and pricing, see [Data residency pricing](https://platform.claude.com/docs/en/about-claude/pricing#data-residency-pricing).
**Scope:** This pricing structure applies to Claude Sonnet 4.5, Haiku 4.5, Opus 4.5, and all future models. Earlier models (Claude Opus 4.1 and prior releases) retain their existing pricing.
For implementation details and code examples:
* [Amazon Bedrock global vs regional endpoints](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock#regions) for Opus 4.7, Haiku 4.5, and later models, or [the legacy integration](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy#global-vs-regional-endpoints) for all other models on Bedrock
* [Google Cloud global, multi-region, and regional endpoints](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai#global-multi-region-and-regional-endpoints)
</Note>
## Claude Platform on AWS pricing
[Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) bills through AWS Marketplace using Claude Consumption Units (CCUs). Anthropic rates your token usage in USD at standard per-model, per-feature rates, applies any negotiated discount, converts the result to CCUs at $0.01 per CCU, and reports the CCU quantity to AWS Marketplace hourly. Your AWS bill shows a single CCU line item.
| Concept | Details |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Billing unit** | Claude Consumption Unit (CCU) |
| **CCU price** | $0.01 per CCU (fixed; discounts apply at token-to-CCU conversion, not to the CCU price) |
| **Conversion** | Token usage rated in USD at standard per-model, per-feature rates (same as [Claude API pricing](https://platform.claude.com/docs/en/about-claude/pricing#model-pricing)), then converted to CCUs at $0.01 per CCU |
| **Billing cadence** | Hourly metering to AWS Marketplace; monthly invoices |
| **Payment model** | Arrears only (postpaid); no prepaid credits |
| **Discounts** | Applied as fewer CCUs metered |
| **Tax** | Pre-tax metering; AWS Marketplace handles tax |
| **Cost visibility** | Real-time breakdown in the Claude Console (access through the AWS Console); AWS Cost Explorer shows aggregated CCU |
<Note>
**Claude Consumption Units.** If Customer accesses the Services through certain Marketplace Platforms (e.g., Claude Platform on AWS), usage will be invoiced in Claude Consumption Units ("CCU") rather than per MTok. A CCU is a unit of measure used solely for Marketplace Platform invoicing. One hundred (100) CCU represents $1.00 USD of fees owed for the Services, calculated at the applicable prices on [claude.com/pricing#api](https://claude.com/pricing#api), after application of any discounts.
</Note>
### Inference geography
For Claude 4.6 and later models, using `inference_geo: "us"` applies a 1.1x pricing multiplier. `inference_geo: "global"` (default) uses standard pricing. See [Data residency](https://platform.claude.com/docs/en/manage-claude/data-residency) for details.
### Private offers
When you sign up on the AWS Console **Claude Platform on AWS** service page, the AWS Console looks up any private offer associated with your account and prompts you to accept it in AWS Marketplace. Contact your Anthropic account representative for private offer terms.
<Note>
If you have an existing Amazon Bedrock private offer, contact your Anthropic or AWS account representative before getting started with Claude Platform on AWS to ensure your discounts are applied correctly. Discounts cannot be applied retroactively to usage incurred before your private offer is accepted.
</Note>
## Claude in Microsoft Foundry pricing
[Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) bills through the Azure Marketplace using Claude Consumption Units (CCUs). Anthropic rates your token usage in USD at standard per-model, per-feature rates, applies any negotiated discount, converts the result to CCUs at $0.01 per CCU, and reports the CCU quantity to the Azure Marketplace hourly. Your Azure bill shows a single CCU line item.
| Concept | Details |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Billing unit** | Claude Consumption Unit (CCU) |
| **CCU price** | $0.01 per CCU (fixed; discounts apply at token-to-CCU conversion, not to the CCU price) |
| **Conversion** | Token usage rated in USD at standard per-model, per-feature rates (same as [Claude API pricing](https://platform.claude.com/docs/en/about-claude/pricing#model-pricing)), then converted to CCUs at $0.01 per CCU |
| **Billing cadence** | Hourly metering to the Azure Marketplace; monthly invoices |
| **Payment model** | Arrears only (postpaid); no prepaid credits |
| **Discounts** | Applied as fewer CCUs metered |
| **Tax** | Pre-tax metering; Azure Marketplace handles tax |
| **Cost visibility** | Azure Cost Management shows aggregated CCU |
<Note>
**Claude Consumption Units.** If Customer accesses the Services through certain Marketplace Platforms (e.g., Claude Platform on AWS, Claude in Microsoft Foundry), usage will be invoiced in Claude Consumption Units ("CCU") rather than per MTok. A CCU is a unit of measure used solely for Marketplace Platform invoicing. One hundred (100) CCU represents $1.00 USD of fees owed for the Services, calculated at the applicable prices on [claude.com/pricing#api](https://claude.com/pricing#api), after application of any discounts.
</Note>
### Inference geography
Deployments hosted on Azure can use the US Data Zone Standard deployment type, which keeps inference within the United States. This is equivalent to `inference_geo: "us"` on the Claude API and applies the same 1.1x pricing multiplier. See [Data residency](https://platform.claude.com/docs/en/manage-claude/data-residency) for details.
## Feature-specific pricing
### Prompt caching
Prompt caching reduces costs and latency by reusing previously processed portions of your prompt across API calls. Instead of reprocessing the same large system prompt, document, or conversation history on every request, the API reads from cache at a fraction of the standard input price.
There are two ways to enable prompt caching:
* **Automatic caching:** Add a single `cache_control` field at the top level of your request. The system automatically manages cache breakpoints as conversations grow. This is the recommended starting point for most use cases.
* **Explicit cache breakpoints:** Place `cache_control` directly on individual content blocks for fine-grained control over exactly what gets cached.
Prompt caching uses the following pricing multipliers relative to base input token rates:
| Cache operation | Multiplier | Duration |
| -------------------- | ---------------------- | ------------------------------------ |
| 5-minute cache write | 1.25x base input price | Cache valid for 5 minutes |
| 1-hour cache write | 2x base input price | Cache valid for 1 hour |
| Cache read (hit) | 0.1x base input price | Same duration as the preceding write |
Cache write tokens are charged when content is first stored. Cache read tokens are charged when a subsequent request retrieves the cached content. A cache hit costs 10% of the standard input price, which means caching pays off after one cache read for the 5-minute duration (1.25x write), or after two cache reads for the 1-hour duration (2x write).
These multipliers stack with other pricing modifiers, including the Batch API discount and data residency.
For implementation details, supported models, and code examples, see [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).
### Data residency pricing
For Claude 4.6 and later models, specifying US-only inference through the `inference_geo` parameter incurs a 1.1x multiplier on all token pricing categories, including input tokens, output tokens, cache writes, and cache reads. Global routing (the default) uses standard pricing.
This applies to the Claude API (first-party) and Claude Platform on AWS. On Claude in Microsoft Foundry, the same 1.1x multiplier applies to deployments that use the US Data Zone Standard deployment type (see [Inference geography](https://platform.claude.com/docs/en/about-claude/pricing#foundry-inference-geography)). Partner-operated platforms (Bedrock and Google Cloud) have independent regional pricing. See [Bedrock](https://aws.amazon.com/bedrock/pricing/) and [Google Cloud](https://cloud.google.com/vertex-ai/generative-ai/pricing#claude-models) for details. Earlier models do not support the `inference_geo` parameter and always use standard pricing; requests that include the parameter on these models return a 400 error.
For more information, see [Data residency](https://platform.claude.com/docs/en/manage-claude/data-residency).
### Fast mode pricing
[Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode), in research preview, provides significantly faster output for Claude Opus 5 and Claude Opus 4.8 at premium pricing. Fast mode pricing applies across the full context window, including requests over 200k input tokens. Fast mode is available on the Claude API (first-party) only; it is not available on Claude Platform on AWS or partner-operated cloud platforms.
| Model | Input | Output |
| ------------------------------- | ---------- | ---------- |
| Claude Opus 5 / Claude Opus 4.8 | $10 / MTok | $50 / MTok |
Fast mode is not available on Claude Opus 4.7 (requests with `speed: "fast"` return an error) or Claude Opus 4.6 (requests run at standard speed and are billed at standard rates). See [Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode#supported-models).
Fast mode pricing stacks with other pricing modifiers:
* [Prompt caching multipliers](https://platform.claude.com/docs/en/about-claude/pricing#prompt-caching) apply on top of fast mode pricing
* [Data residency](https://platform.claude.com/docs/en/manage-claude/data-residency) multipliers apply on top of fast mode pricing
Fast mode is not available with the [Batch API](https://platform.claude.com/docs/en/about-claude/pricing#batch-processing).
For more information, see [Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode).
### Batch processing
The Batch API allows asynchronous processing of large volumes of requests with a 50% discount on both input and output tokens.
| Model | Batch input | Batch output |
| ------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------- |
| Claude Fable 5 | $5 / MTok | $25 / MTok |
| Claude Mythos 5 ([limited availability](https://anthropic.com/glasswing)) | $5 / MTok | $25 / MTok |
| Claude Opus 5 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.8 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.7 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.6 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.5 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.1 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok |
| Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok |
| Claude Sonnet 5 | $1 / MTok | $5 / MTok |
| Claude Sonnet 4.6 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4.5 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $1.50 / MTok | $7.50 / MTok |
| Claude Haiku 4.5 | $0.50 / MTok | $2.50 / MTok |
| Claude Haiku 3.5 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $0.40 / MTok | $2 / MTok |
For more information about batch processing, see [Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing).
### Long context pricing
Claude 4.6 and later models and [Claude Mythos Preview](https://anthropic.com/glasswing) include the full [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) at standard pricing. (A 900k-token request is billed at the same per-token rate as a 9k-token request.) Prompt caching and batch processing discounts apply at standard rates across the full context window.
### Tool use 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.
| Model | Tool choice | Tool use system prompt token count |
| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ---------------------------------- |
| Claude Opus 5 | `auto`, `none`***`any`, `tool` | 286 tokens***406 tokens |
| Claude Opus 4.8 | `auto`, `none`***`any`, `tool` | 290 tokens***410 tokens |
| Claude Opus 4.7 | `auto`, `none`***`any`, `tool` | 675 tokens***804 tokens |
| Claude Opus 4.6 | `auto`, `none`***`any`, `tool` | 497 tokens***589 tokens |
| Claude Opus 4.5 | `auto`, `none`***`any`, `tool` | 496 tokens***588 tokens |
| Claude Opus 4.1 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | `auto`, `none`***`any`, `tool` | 313 tokens***315 tokens |
| Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | `auto`, `none`***`any`, `tool` | 313 tokens***315 tokens |
| Claude Sonnet 5 | `auto`, `none`***`any`, `tool` | 354 tokens***474 tokens |
| Claude Sonnet 4.6 | `auto`, `none`***`any`, `tool` | 497 tokens***589 tokens |
| Claude Sonnet 4.5 | `auto`, `none`***`any`, `tool` | 496 tokens***588 tokens |
| Claude Sonnet 4 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | `auto`, `none`***`any`, `tool` | 313 tokens***315 tokens |
| Claude Haiku 4.5 | `auto`, `none`***`any`, `tool` | 496 tokens***588 tokens |
| Claude Haiku 3.5 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | `auto`, `none`***`any`, `tool` | 264 tokens***355 tokens |
These token counts are added to your normal input and output tokens to calculate the total cost of a request.
For current per-model prices, refer to the [model pricing](https://platform.claude.com/docs/en/about-claude/pricing#model-pricing) section.
For more information about tool use implementation and best practices, see [Tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview).
### Specific tool pricing
#### Bash tool
The bash tool definition adds the following input tokens to your request. This is in addition to the per-model [tool use system prompt](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview#pricing) that applies whenever any tool is present.
| Model | Additional input tokens |
| --------------------------------------------------- | ----------------------- |
| Claude Opus 5, Claude Opus 4.8, and Claude Opus 4.7 | 325 tokens |
| Claude Opus 4.6, Claude Sonnet 4.6, and earlier | 244 tokens |
Additional tokens are consumed by:
* Command outputs (stdout/stderr)
* Error messages
* Large file contents
See [tool use pricing](https://platform.claude.com/docs/en/about-claude/pricing#tool-use-pricing) for complete pricing details.
#### Code execution tool
**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:
```json
{
"usage": {
"input_tokens": 105,
"output_tokens": 239,
"server_tool_use": {
"code_execution_requests": 1
}
}
}
```
#### Text editor tool
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_20250429` (Claude 4.x) | 700 tokens |
Cut at 300 lines. The page has the rest.
about-claude/use-case-guides/content-moderation First recorded · 2747 lines, first recorded
## Before building with Claude ### Decide whether to use Claude for content moderation ### Generate examples of content to moderate ## How to moderate content using Claude ### Select the right Claude model ### Build a strong prompt ### Evaluate your prompt ### Deploy your prompt ## Improve performance ### Define topics and provide examples ### Consider batch processing
The first capture of this source. The page was already there, and this is what it said.
---
title: Content moderation
url: https://platform.claude.com/docs/en/about-claude/use-case-guides/content-moderation
description: Content moderation is a critical aspect of maintaining a safe, respectful, and productive environment in digital applications. This guide discusses how Claude can be used to moderate content within your digital application.
---
> Visit the [content moderation cookbook](https://platform.claude.com/cookbook/misc-building-moderation-filter) to see an example content moderation implementation using Claude.
<Tip>
This guide is focused on moderating user-generated content within your application. If you're looking for guidance on moderating interactions with Claude, refer to
[Mitigate jailbreaks and prompt injections](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks)
.
</Tip>
## Before building with Claude
### Decide whether to use Claude for content moderation
Here are some key indicators that you should use an LLM like Claude instead of a traditional ML or rules-based approach for content moderation:
<AccordionGroup>
<Accordion title="You want a cost-effective and rapid implementation">
Traditional ML methods require significant engineering resources, ML expertise, and infrastructure costs. Human moderation systems incur even higher costs. With Claude, you can have a sophisticated moderation system operational in significantly less time and at a much lower cost.
</Accordion>
<Accordion title="You want both semantic understanding and quick decisions">
Traditional ML approaches, such as bag-of-words models or simple pattern matching, often struggle to understand the tone, intent, and context of the content. While human moderation systems excel at understanding semantic meaning, they require time for content to be reviewed. Claude addresses both needs by combining semantic understanding with the ability to deliver moderation decisions quickly.
</Accordion>
<Accordion title="You need consistent policy decisions">
By leveraging its advanced reasoning capabilities, Claude can interpret and apply complex moderation guidelines uniformly. This consistency helps ensure fair treatment of all content, reducing the risk of inconsistent or biased moderation decisions that can undermine user trust.
</Accordion>
<Accordion title="Your moderation policies are likely to change or evolve over time">
Once a traditional ML approach has been established, changing it is a laborious and data-intensive undertaking. On the other hand, as your product or customer needs evolve, Claude can easily adapt to changes or additions to moderation policies without extensive relabeling of training data.
</Accordion>
<Accordion title="You require interpretable reasoning for your moderation decisions">
If you want to provide users or regulators with clear explanations behind moderation decisions, Claude can generate detailed and coherent justifications. This transparency is important for building trust and ensuring accountability in content moderation practices.
</Accordion>
<Accordion title="You need multilingual support without maintaining separate models">
Traditional ML approaches typically require separate models or extensive translation processes for each supported language. Human moderation requires hiring a workforce fluent in each supported language. Claude’s multilingual capabilities allow it to classify tickets in various languages without the need for separate models or extensive translation processes, streamlining moderation for global customer bases.
</Accordion>
<Accordion title="You require multimodal support">
Claude's multimodal capabilities allow it to analyze and interpret content across both text and images. This makes it a versatile tool for comprehensive content moderation in environments where different media types need to be evaluated together.
</Accordion>
</AccordionGroup>
<Note>
All Claude models are trained with built-in safety behaviors. This may result in Claude moderating content deemed particularly dangerous (in line with the
[Acceptable Use Policy](https://www.anthropic.com/legal/aup)
), regardless of the prompt used. For example, an adult website that wants to allow users to post explicit sexual content may find that Claude still flags explicit content as requiring moderation, even if they specify in their prompt not to moderate explicit sexual content. Consider reviewing the AUP in advance of building a moderation solution.
</Note>
### Generate examples of content to moderate
Before developing a content moderation solution, first create examples of content that should be flagged and content that should not be flagged. Ensure that you include edge cases and challenging scenarios that may be difficult for a content moderation system to handle effectively. Afterward, review your examples to create a well-defined list of moderation categories. For instance, the examples generated by a social media platform might include the following:
<CodeGroup exclude="shell">
```python Python
client = anthropic.Anthropic()
allowed_user_comments = [
"This movie was great, I really enjoyed it. The main actor really killed it!",
"I hate Mondays.",
"It is a great time to invest in gold!",
]
disallowed_user_comments = [
"Delete this post now or you better hide. I am coming after you and your family.",
"Stay away from the 5G cellphones!! They are using 5G to control you.",
"Congratulations! You have won a $1,000 gift card. Click here to claim your prize!",
]
# Sample user comments to test the content moderation
user_comments = allowed_user_comments + disallowed_user_comments
# Categories considered unsafe for content moderation
unsafe_categories = [
"Child Exploitation",
"Conspiracy Theories",
"Hate",
"Indiscriminate Weapons",
"Intellectual Property",
"Non-Violent Crimes",
"Privacy",
"Self-Harm",
"Sex Crimes",
"Sexual Content",
"Specialized Advice",
"Violent Crimes",
]
```
```typescript TypeScript
const client = new Anthropic();
const allowedUserComments = [
"This movie was great, I really enjoyed it. The main actor really killed it!",
"I hate Mondays.",
"It is a great time to invest in gold!"
];
const disallowedUserComments = [
"Delete this post now or you better hide. I am coming after you and your family.",
"Stay away from the 5G cellphones!! They are using 5G to control you.",
"Congratulations! You have won a $1,000 gift card. Click here to claim your prize!"
];
// Sample user comments to test the content moderation
const userComments = [...allowedUserComments, ...disallowedUserComments];
// Categories considered unsafe for content moderation
const unsafeCategories = [
"Child Exploitation",
"Conspiracy Theories",
"Hate",
"Indiscriminate Weapons",
"Intellectual Property",
"Non-Violent Crimes",
"Privacy",
"Self-Harm",
"Sex Crimes",
"Sexual Content",
"Specialized Advice",
"Violent Crimes"
];
```
```csharp C#
var client = new AnthropicClient();
string[] allowedUserComments =
[
"This movie was great, I really enjoyed it. The main actor really killed it!",
"I hate Mondays.",
"It is a great time to invest in gold!",
];
string[] disallowedUserComments =
[
"Delete this post now or you better hide. I am coming after you and your family.",
"Stay away from the 5G cellphones!! They are using 5G to control you.",
"Congratulations! You have won a $1,000 gift card. Click here to claim your prize!",
];
// Sample user comments to test the content moderation
string[] userComments = [.. allowedUserComments, .. disallowedUserComments];
// Categories considered unsafe for content moderation
string[] unsafeCategories =
[
"Child Exploitation",
"Conspiracy Theories",
"Hate",
"Indiscriminate Weapons",
"Intellectual Property",
"Non-Violent Crimes",
"Privacy",
"Self-Harm",
"Sex Crimes",
"Sexual Content",
"Specialized Advice",
"Violent Crimes",
];
```
```go Go
var client = anthropic.NewClient()
var allowedUserComments = []string{
"This movie was great, I really enjoyed it. The main actor really killed it!",
"I hate Mondays.",
"It is a great time to invest in gold!",
}
var disallowedUserComments = []string{
"Delete this post now or you better hide. I am coming after you and your family.",
"Stay away from the 5G cellphones!! They are using 5G to control you.",
"Congratulations! You have won a $1,000 gift card. Click here to claim your prize!",
}
// Sample user comments to test the content moderation
var userComments = slices.Concat(allowedUserComments, disallowedUserComments)
// Categories considered unsafe for content moderation
var unsafeCategories = []string{
"Child Exploitation",
"Conspiracy Theories",
"Hate",
"Indiscriminate Weapons",
"Intellectual Property",
"Non-Violent Crimes",
"Privacy",
"Self-Harm",
"Sex Crimes",
"Sexual Content",
"Specialized Advice",
"Violent Crimes",
}
```
```java Java
final AnthropicClient client = AnthropicOkHttpClient.fromEnv();
final List<String> allowedUserComments = List.of(
"This movie was great, I really enjoyed it. The main actor really killed it!",
"I hate Mondays.",
"It is a great time to invest in gold!");
final List<String> disallowedUserComments = List.of(
"Delete this post now or you better hide. I am coming after you and your family.",
"Stay away from the 5G cellphones!! They are using 5G to control you.",
"Congratulations! You have won a $1,000 gift card. Click here to claim your prize!");
// Sample user comments to test the content moderation
final List<String> userComments =
Stream.concat(allowedUserComments.stream(), disallowedUserComments.stream()).toList();
// Categories considered unsafe for content moderation
final List<String> unsafeCategories = List.of(
"Child Exploitation",
"Conspiracy Theories",
"Hate",
"Indiscriminate Weapons",
"Intellectual Property",
"Non-Violent Crimes",
"Privacy",
"Self-Harm",
"Sex Crimes",
"Sexual Content",
"Specialized Advice",
"Violent Crimes");
```
```php PHP
$client = new Client();
$allowedUserComments = [
'This movie was great, I really enjoyed it. The main actor really killed it!',
'I hate Mondays.',
'It is a great time to invest in gold!',
];
$disallowedUserComments = [
'Delete this post now or you better hide. I am coming after you and your family.',
'Stay away from the 5G cellphones!! They are using 5G to control you.',
'Congratulations! You have won a $1,000 gift card. Click here to claim your prize!',
];
// Sample user comments to test the content moderation
$userComments = [...$allowedUserComments, ...$disallowedUserComments];
// Categories considered unsafe for content moderation
$unsafeCategories = [
'Child Exploitation',
'Conspiracy Theories',
'Hate',
'Indiscriminate Weapons',
'Intellectual Property',
'Non-Violent Crimes',
'Privacy',
'Self-Harm',
'Sex Crimes',
'Sexual Content',
'Specialized Advice',
'Violent Crimes',
];
```
```ruby Ruby
CLIENT = Anthropic::Client.new
ALLOWED_USER_COMMENTS = [
"This movie was great, I really enjoyed it. The main actor really killed it!",
"I hate Mondays.",
"It is a great time to invest in gold!"
]
DISALLOWED_USER_COMMENTS = [
"Delete this post now or you better hide. I am coming after you and your family.",
"Stay away from the 5G cellphones!! They are using 5G to control you.",
"Congratulations! You have won a $1,000 gift card. Click here to claim your prize!"
]
# Sample user comments to test the content moderation
USER_COMMENTS = ALLOWED_USER_COMMENTS + DISALLOWED_USER_COMMENTS
# Categories considered unsafe for content moderation
UNSAFE_CATEGORIES = [
"Child Exploitation",
"Conspiracy Theories",
"Hate",
Cut at 300 lines. The page has the rest.
about-claude/use-case-guides/customer-support-chat First recorded · 1226 lines, first recorded
## Prerequisites ## Before building with Claude ### Decide whether to use Claude for support chat ### Define your ideal chat interaction ### Break the interaction into unique tasks ### Establish success criteria ## How to implement Claude as a customer service agent ### Choose the right Claude model ### Build a strong prompt ### Add dynamic and agentic capabilities with tool use ### Deploy your prompts ### Build your user interface ### Evaluate your prompts ### Improve performance #### Reduce long context latency with RAG #### Integrate real-time data with tool use #### Strengthen input and output guardrails #### Reduce perceived response time with streaming #### Scale your chatbot ### Integrate Claude into your support workflow ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Customer support agent
url: https://platform.claude.com/docs/en/about-claude/use-case-guides/customer-support-chat
description: Build a customer support chatbot with Claude that answers product questions, stays on topic, and generates quotes through tool use.
---
## Prerequisites
To follow this guide, you need:
* A Claude API key (set as the `ANTHROPIC_API_KEY` environment variable)
* Python 3.9 or later
Install the required packages:
```bash
pip install anthropic streamlit python-dotenv
```
## Before building with Claude
### Decide whether to use Claude for support chat
Here are some key indicators that you should employ an LLM like Claude to automate portions of your customer support process:
<AccordionGroup>
<Accordion title="High volume of repetitive queries">
Claude excels at handling a large number of similar questions efficiently, freeing up human agents for more complex issues.
</Accordion>
<Accordion title="Need for quick information synthesis">
Claude can quickly retrieve, process, and combine information from vast knowledge bases, while human agents may need time to research or consult multiple sources.
</Accordion>
<Accordion title="24/7 availability requirement">
Claude can provide round-the-clock support without fatigue, whereas staffing human agents for continuous coverage can be costly and challenging.
</Accordion>
<Accordion title="Rapid scaling during peak periods">
Claude can handle sudden increases in query volume without the need for hiring and training additional staff.
</Accordion>
<Accordion title="Consistent brand voice">
You can instruct Claude to consistently represent your brand's tone and values, whereas human agents may vary in their communication styles.
</Accordion>
</AccordionGroup>
Some considerations for choosing Claude over other LLMs:
* You prioritize natural, nuanced conversation: Claude's sophisticated language understanding allows for more natural, context-aware conversations that feel more human-like than chats with other LLMs.
* You often receive complex and open-ended queries: Claude can handle a wide range of topics and inquiries without generating canned responses or requiring extensive programming of permutations of user utterances.
* You need scalable multilingual support: Claude's multilingual capabilities allow it to engage in conversations in over 200 languages without the need for separate chatbots or extensive translation processes for each supported language.
### Define your ideal chat interaction
Outline an ideal customer interaction to define how and when you expect the customer to interact with Claude. This outline will help to determine the technical requirements of your solution.
Here is an example chat interaction for car insurance customer support:
* **Customer:** Initiates support chat experience
* **Claude:** Warmly greets customer and initiates conversation
* **Customer:** Asks about insurance for their new electric car
* **Claude:** Provides relevant information about electric vehicle coverage
* **Customer:** Asks questions related to unique needs for electric vehicle insurances
* **Claude:** Responds with accurate and informative answers and provides links to the sources
* **Customer:** Asks off-topic questions unrelated to insurance or cars
* **Claude:** Clarifies it does not discuss unrelated topics and steers the user back to car insurance
* **Customer:** Expresses interest in an insurance quote
* **Claude:** Ask a set of questions to determine the appropriate quote, adapting to their responses
* **Claude:** Sends a request to use the quote generation API tool along with necessary information collected from the user
* **Claude:** Receives the response information from the API tool use, synthesizes the information into a natural response, and presents the provided quote to the user
* **Customer:** Asks follow up questions
* **Claude:** Answers follow up questions as needed
* **Claude:** Guides the customer to the next steps in the insurance process and closes out the conversation
<Tip>
In the real example that you write for your own use case, you might find it useful to write out the actual words in this interaction so that you can also get a sense of the ideal tone, response length, and level of detail you want Claude to have.
</Tip>
### Break the interaction into unique tasks
Customer support chat is a collection of multiple different tasks, from question answering to information retrieval to taking action on requests, wrapped up in a single customer interaction. Before you start building, break down your ideal customer interaction into every task you want Claude to be able to perform. This ensures you can prompt and evaluate Claude for every task, and gives you a good sense of the range of interactions you need to account for when writing test cases.
<Tip>
Customers sometimes find it helpful to visualize this as an interaction flowchart of possible conversation inflection points depending on user requests.
</Tip>
Here are the key tasks associated with the example insurance interaction:
1. Greeting and general guidance
* Warmly greet the customer and initiate conversation
* Provide general information about the company and interaction
2. Product information
* Provide information about electric vehicle coverage
<Note>
This will require that Claude have the necessary information in its context, and might imply that a
[RAG integration](https://platform.claude.com/cookbook/capabilities-retrieval-augmented-generation-guide)
is necessary.
</Note>
* Answer questions related to unique electric vehicle insurance needs
* Answer follow-up questions about the quote or insurance details
* Offer links to sources when appropriate
3. Conversation management
* Stay on topic (car insurance)
* Redirect off-topic questions back to relevant subjects
4. Quote generation
* Ask appropriate questions to determine quote eligibility
* Adapt questions based on customer responses
* Submit collected information to quote generation API
* Present the provided quote to the customer
### Establish success criteria
Work with your support team to [define success criteria and write detailed evaluations](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests) with measurable benchmarks and goals.
Here are criteria and benchmarks that can be used to evaluate how successfully Claude performs the defined tasks:
<AccordionGroup>
<Accordion title="Query comprehension accuracy">
This metric evaluates how accurately Claude understands customer inquiries across various topics. Measure this by reviewing a sample of conversations and assessing whether Claude has the correct interpretation of customer intent, critical next steps, what successful resolution looks like, and more. Aim for a comprehension accuracy of 95% or higher.
</Accordion>
<Accordion title="Response relevance">
This assesses how well Claude's response addresses the customer's specific question or issue. Evaluate a set of conversations and rate the relevance of each response (using LLM-based grading for scale). Target a relevance score of 90% or above.
</Accordion>
<Accordion title="Response accuracy">
Assess the correctness of general company and product information provided to the user, based on the information provided to Claude in context. Target 100% accuracy in this introductory information.
</Accordion>
<Accordion title="Citation provision relevance">
Track the frequency and relevance of links or sources offered. Target providing relevant sources in 80% of interactions where additional information could be beneficial.
</Accordion>
<Accordion title="Topic adherence">
Measure how well Claude stays on topic, such as the topic of car insurance in the example implementation. Aim for 95% of responses to be directly related to car insurance or the customer's specific query.
</Accordion>
<Accordion title="Content generation effectiveness">
Measure how successful Claude is at determining when to generate informational content and how relevant that content is. For example, in this implementation, you would be determining how well Claude understands when to generate a quote and how accurate that quote is. Target 100% accuracy, as this is vital information for a successful customer interaction.
</Accordion>
<Accordion title="Escalation efficiency">
This measures Claude's ability to recognize when a query needs human intervention and escalate appropriately. Track the percentage of correctly escalated conversations versus those that should have been escalated but weren't. Aim for an escalation accuracy of 95% or higher.
</Accordion>
</AccordionGroup>
Here are criteria and benchmarks that can be used to evaluate the business impact of employing Claude for support:
<AccordionGroup>
<Accordion title="Sentiment maintenance">
This assesses Claude's ability to maintain or improve customer sentiment throughout the conversation. Use sentiment analysis tools to measure sentiment at the beginning and end of each conversation. Aim for maintained or improved sentiment in 90% of interactions.
</Accordion>
<Accordion title="Deflection rate">
The percentage of customer inquiries successfully handled by the chatbot without human intervention. Typically aim for 70-80% deflection rate, depending on the complexity of inquiries.
</Accordion>
<Accordion title="Customer satisfaction score">
A measure of how satisfied customers are with their chatbot interaction. Usually done through post-interaction surveys. Aim for a CSAT score of 4 out of 5 or higher.
</Accordion>
<Accordion title="Average handle time">
The average time it takes for the chatbot to resolve an inquiry. This varies widely based on the complexity of issues, but generally, aim for a lower AHT compared to human agents.
</Accordion>
</AccordionGroup>
## How to implement Claude as a customer service agent
### Choose the right Claude model
The choice of model depends on the trade-offs between cost, accuracy, and response time.
For customer support chat, Claude Opus 5 is well suited to balance intelligence, latency, and cost, including the most complex support scenarios that require deep reasoning across long, multi-step conversations. However, for instances where you have conversation flow with multiple prompts including RAG, tool use, or long-context prompts, Claude Haiku 4.5 may be more suitable to optimize for latency.
### Build a strong prompt
Using Claude for customer support requires Claude having enough direction and context to respond appropriately, while having enough flexibility to handle a wide range of customer inquiries.
Start by writing the elements of a strong prompt, beginning with a system prompt. Create a file called `config.py` and add each of the following blocks to it:
```python
IDENTITY = """You are Eva, a friendly and knowledgeable AI assistant for Acme Insurance
Company. Your role is to warmly welcome customers and provide information on
Acme's insurance offerings, which include car insurance and electric car
insurance. You can also help customers get quotes for their insurance needs."""
```
<Tip>
While you may be tempted to put all your information inside a system prompt as a way to separate instructions from the user conversation, Claude actually works best with the bulk of its prompt content written inside the first
`User`
turn (with the only exception being role prompting). Read more at
[Giving Claude a role with a system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role)
.
</Tip>
It's best to break down complex prompts into subsections and write one part at a time. For each task, you might find greater success by following a step-by-step process to define the parts of the prompt Claude would need to do the task well. For this car insurance customer support example, you'll be writing piecemeal all the parts for a prompt starting with the "Greeting and general guidance" task. This also makes debugging your prompt easier as you can more quickly adjust individual parts of the overall prompt.
```python
STATIC_GREETINGS_AND_GENERAL = """
<static_context>
Acme Auto Insurance: Your Trusted Companion on the Road
About:
At Acme Insurance, we understand that your vehicle is more than just a mode of transportation—it's your ticket to life's adventures.
Since 1985, we've been crafting auto insurance policies that give drivers the confidence to explore, commute, and travel with peace of mind.
Whether you're navigating city streets or embarking on cross-country road trips, Acme is there to protect you and your vehicle.
Our innovative auto insurance policies are designed to adapt to your unique needs, covering everything from fender benders to major collisions.
With Acme's award-winning customer service and swift claim resolution, you can focus on the joy of driving while we handle the rest.
We're not just an insurance provider—we're your co-pilot in life's journeys.
Choose Acme Auto Insurance and experience the assurance that comes with superior coverage and genuine care. Because at Acme, we don't just
insure your car—we fuel your adventures on the open road.
Note: We also offer specialized coverage for electric vehicles, ensuring that drivers of all car types can benefit from our protection.
Acme Insurance offers the following products:
- Car insurance
- Electric car insurance
- Two-wheeler insurance
Business hours: Monday-Friday, 9 AM - 5 PM EST
Customer service number: 1-800-123-4567
</static_context>
"""
```
Then do the same for your car insurance and electric car insurance information.
```python
STATIC_CAR_INSURANCE = """
<static_context>
Car Insurance Coverage:
Acme's car insurance policies typically cover:
1. Liability coverage: Pays for bodily injury and property damage you cause to others.
2. Collision coverage: Pays for damage to your car in an accident.
3. Comprehensive coverage: Pays for damage to your car from non-collision incidents.
4. Medical payments coverage: Pays for medical expenses after an accident.
5. Uninsured/underinsured motorist coverage: Protects you if you're hit by a driver with insufficient insurance.
Optional coverages include:
- Rental car reimbursement
- Roadside assistance
- New car replacement
</static_context>
"""
STATIC_ELECTRIC_CAR_INSURANCE = """
<static_context>
Electric Car Insurance:
Our specialized electric car insurance goes beyond traditional auto coverage,
offering tailored protection for your high-tech investment. In addition to standard coverages, we offer:
- Safeguarding expensive battery systems
- Covering home charging equipment
- Adapting to the rapidly evolving world of electric vehicles
Whether you're driving a Rivian, Nissan Leaf, Chevrolet Bolt,
or any other electric vehicle, our knowledgeable agents are ready to craft a policy
that gives you the confidence to enjoy every electron-powered mile.
</static_context>
"""
```
Now that you have your static content, add at least 4-5 sample "good" interactions to guide Claude's responses. These examples should be representative of your ideal customer interaction and can include elements such as guardrails and tool calls.
```python
EXAMPLES = """
Here are a few examples of how you can interact with customers:
<example 1>
H: Hi, do you offer commercial insurance for small businesses?
A: Ah! Unfortunately, we don't offer commercial insurance at this time.
However, we do provide a range of personal insurance products including car insurance and electric car insurance.
Would you like to know more about these offerings?
</example 1>
<example 2>
H: Hi, what are your business hours?
A: Our business hours are Monday to Friday, 9 AM to 5 PM EST.
Cut at 300 lines. The page has the rest.
about-claude/use-case-guides/legal-summarization First recorded · 387 lines, first recorded
## Before building with Claude ### Decide whether to use Claude for legal summarization ### Determine the details you want the summarization to extract ### Establish success criteria ## How to summarize legal documents using Claude ### Select the right Claude model ### Transform documents into a format that Claude can process ### Build a strong prompt ### Evaluate your prompt ### Deploy your prompt ## Improve performance ### Perform meta-summarization to summarize long documents ### Use summary indexed documents to explore a large collection of documents ### Fine-tune Claude to learn from your dataset
The first capture of this source. The page was already there, and this is what it said.
---
title: Legal summarization
url: https://platform.claude.com/docs/en/about-claude/use-case-guides/legal-summarization
description: This guide walks through how to leverage Claude's advanced natural language processing capabilities to efficiently summarize legal documents, extracting key information and expediting legal research. With Claude, you can streamline the review of contracts, litigation prep, and regulatory work, saving time and ensuring accuracy in your legal processes.
---
> Visit the [summarization cookbook](https://platform.claude.com/cookbook/capabilities-summarization-guide) to see an example legal summarization implementation using Claude.
## Before building with Claude
### Decide whether to use Claude for legal summarization
Here are some key indicators that you should employ an LLM such as Claude to summarize legal documents:
<AccordionGroup>
<Accordion title="You want to review a high volume of documents efficiently and affordably">
Large-scale document review can be time-consuming and expensive when done manually. Claude can process and summarize vast amounts of legal documents rapidly, significantly reducing the time and cost associated with document review. This capability is particularly valuable for tasks like due diligence, contract analysis, or litigation discovery, where efficiency is crucial.
</Accordion>
<Accordion title="You require automated extraction of key metadata">
Claude can efficiently extract and categorize important metadata from legal documents, such as parties involved, dates, contract terms, or specific clauses. This automated extraction can help organize information, making it easier to search, analyze, and manage large document sets. It's especially useful for contract management, compliance checks, or creating searchable databases of legal information.
</Accordion>
<Accordion title="You want to generate clear, concise, and standardized summaries">
Claude can generate structured summaries that follow predetermined formats, making it easier for legal professionals to quickly grasp the key points of various documents. These standardized summaries can improve readability, facilitate comparison between documents, and enhance overall comprehension, especially when dealing with complex legal language or technical jargon.
</Accordion>
<Accordion title="You need precise citations for your summaries">
When creating legal summaries, proper attribution and citation are crucial to ensure credibility and compliance with legal standards. Claude can be prompted to include accurate citations for all referenced legal points, making it easier for legal professionals to review and verify the summarized information.
</Accordion>
<Accordion title="You want to streamline and expedite your legal research process">
Claude can assist in legal research by quickly analyzing large volumes of case law, statutes, and legal commentary. It can identify relevant precedents, extract key legal principles, and summarize complex legal arguments. This capability can significantly speed up the research process, allowing legal professionals to focus on higher-level analysis and strategy development.
</Accordion>
</AccordionGroup>
### Determine the details you want the summarization to extract
There is no single correct summary for any given document. Without clear direction, it can be difficult for Claude to determine which details to include. To achieve optimal results, identify the specific information you want to include in the summary.
For instance, when summarizing a sublease agreement, you might want to extract the following key points:
```python
details_to_extract = [
"Parties involved (sublessor, sublessee, and original lessor)",
"Property details (address, description, and permitted use)",
"Term and rent (start date, end date, monthly rent, and security deposit)",
"Responsibilities (utilities, maintenance, and repairs)",
"Consent and notices (landlord's consent, and notice requirements)",
"Special provisions (furniture, parking, and subletting restrictions)",
]
```
### Establish success criteria
Evaluating the quality of summaries is a notoriously challenging task. Unlike many other natural language processing tasks, evaluation of summaries often lacks clear-cut, objective metrics. The process can be highly subjective, with different readers valuing different aspects of a summary. Here are criteria you may want to consider when assessing how well Claude performs legal summarization.
<AccordionGroup>
<Accordion title="Factual correctness">
The summary should accurately represent the facts, legal concepts, and key points in the document.
</Accordion>
<Accordion title="Legal precision">
Terminology and references to statutes, case law, or regulations must be correct and aligned with legal standards.
</Accordion>
<Accordion title="Conciseness">
The summary should condense the legal document to its essential points without losing important details.
</Accordion>
<Accordion title="Consistency">
If summarizing multiple documents, the LLM should maintain a consistent structure and approach to each summary.
</Accordion>
<Accordion title="Readability">
The text should be clear and easy to understand. If the audience is not legal experts, the summarization should not include legal jargon that could confuse the audience.
</Accordion>
<Accordion title="Bias and fairness">
The summary should present an unbiased and fair depiction of the legal arguments and positions.
</Accordion>
</AccordionGroup>
See the guide on [establishing success criteria](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests) for more information.
***
## How to summarize legal documents using Claude
### Select the right Claude model
Model accuracy is extremely important when summarizing legal documents. Claude Opus 5 is an excellent choice for use cases such as this where high accuracy is required. If the size and quantity of your documents is large such that costs start to become a concern, you can also try using a smaller model such as Claude Haiku 4.5.
To help estimate these costs, the following is a comparison of the cost to summarize 1,000 sublease agreements using Opus and Haiku models:
* **Content size**
* Number of agreements: 1,000
* Characters per agreement: 300,000
* Total characters: 300M
* **Estimated tokens**
* Input tokens: 86M (assuming 1 token per 3.5 characters)
* Output tokens per summary: 350
* Total output tokens: 350,000
* **Claude Opus 5 estimated cost**
* Input token cost: 86 MTok \* $5.00/MTok = $430.00 USD
* Output token cost: 0.35 MTok \* $25.00/MTok = $8.75 USD
* Total cost: $430.00 + $8.75 = $438.75 USD
* **Claude Opus 4.8 estimated cost**
* Input token cost: 86 MTok \* $5.00/MTok = $430.00 USD
* Output token cost: 0.35 MTok \* $25.00/MTok = $8.75 USD
* Total cost: $430.00 + $8.75 = $438.75 USD
* **Claude Haiku 4.5 estimated cost**
* Input token cost: 86 MTok \* $1.00/MTok = $86.00 USD
* Output token cost: 0.35 MTok \* $5.00/MTok = $1.75 USD
* Total cost: $86.00 + $1.75 = $87.75 USD
<Tip>
Actual costs may differ from these estimates. These estimates are based on the example highlighted in the
[Build a strong prompt](https://platform.claude.com/docs/en/about-claude/use-case-guides/legal-summarization#build-a-strong-prompt)
section.
</Tip>
### Transform documents into a format that Claude can process
Before you begin summarizing documents, you need to prepare your data. This involves extracting text from PDFs, cleaning the text, and ensuring it's ready to be processed by Claude.
Here is a demonstration of this process on a sample PDF:
```python
from io import BytesIO
import re
import pypdf
import requests
def get_llm_text(pdf_file):
reader = pypdf.PdfReader(pdf_file)
text = "\n".join([page.extract_text() for page in reader.pages])
# Remove page numbers
text = re.sub(r"\n\s*\d+\s*\n", "\n", text)
# Remove extra whitespace
text = re.sub(r"\s+", " ", text)
return text
# Create the full URL from the GitHub repository
url = "https://raw.githubusercontent.com/anthropics/claude-cookbooks/main/capabilities/summarization/data/Sample Sublease Agreement.pdf"
url = url.replace(" ", "%20")
# Download the PDF file into memory
response = requests.get(url)
# Load the PDF from memory
pdf_file = BytesIO(response.content)
document_text = get_llm_text(pdf_file)
print(document_text[:50000])
```
In this example, you first download a PDF of a sample sublease agreement used in the [summarization cookbook](https://platform.claude.com/cookbook/capabilities-summarization-guide). This agreement was sourced from a publicly available sublease agreement from the [sec.gov website](https://www.sec.gov/Archives/edgar/data/1045425/000119312507044370/dex1032.htm).
The example uses the pypdf library to extract the contents of the PDF and convert it to text. The text data is then cleaned by removing page numbers and extra whitespace.
### Build a strong prompt
Claude can adapt to various summarization styles. You can change the details of the prompt to guide Claude to be more or less verbose, include more or less technical terminology, or provide a higher- or lower-level summary of the context at hand.
Here’s an example of how to create a prompt that ensures the generated summaries follow a consistent structure when analyzing sublease agreements:
```python Python
# Initialize the Anthropic client
client = anthropic.Anthropic()
def summarize_document(
text, details_to_extract, model="claude-opus-5", max_tokens=1000
):
# Format the details to extract to be placed within the prompt's context
details_to_extract_str = "\n".join(details_to_extract)
# Prompt the model to summarize the sublease agreement
prompt = f"""Summarize the following sublease agreement. Focus on these key aspects:
{details_to_extract_str}
Provide the summary in bullet points nested within the XML header for each section. For example:
<parties involved>
- Sublessor: [Name]
// Add more details as needed
</parties involved>
If any information is not explicitly stated in the document, note it as "Not specified". Do not preamble.
Sublease agreement text:
{text}
"""
response = client.messages.create(
model=model,
max_tokens=max_tokens,
system="You are a legal analyst specializing in real estate law, known for highly accurate and detailed summaries of sublease agreements.",
messages=[
{"role": "user", "content": prompt},
],
)
return next(block.text for block in response.content if block.type == "text")
sublease_summary = summarize_document(document_text, details_to_extract)
print(sublease_summary)
```
This code implements a `summarize_document` function that uses Claude to summarize the contents of a sublease agreement. The function accepts a text string and a list of details to extract as inputs. In this example, the code calls the function with the `document_text` and `details_to_extract` variables that were defined in the previous code snippets.
Within the function, a prompt is generated for Claude, including the document to be summarized, the details to extract, and specific instructions for summarizing the document. The prompt instructs Claude to respond with a summary of each detail to extract nested within XML headers.
Because the code outputs each section of the summary within tags, each section can easily be parsed out as a post-processing step. This approach enables structured summaries that can be adapted for your use case, so that each summary follows the same pattern.
### Evaluate your prompt
Prompting often requires testing and optimization for it to be production ready. To determine the readiness of your solution, evaluate the quality of your summaries using a systematic process combining quantitative and qualitative methods. Creating a [strong empirical evaluation](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests#build-evaluations) based on your defined success criteria allows you to optimize your prompts. Here are some metrics you may want to include within your empirical evaluation:
<AccordionGroup>
<Accordion title="ROUGE scores">
This measures the overlap between the generated summary and an expert-created reference summary. This metric primarily focuses on recall and is useful for evaluating content coverage.
</Accordion>
<Accordion title="BLEU scores">
Although originally developed for machine translation, this metric can be adapted for summarization tasks. BLEU scores measure the precision of n-gram matches between the generated summary and reference summaries. A higher score indicates that the generated summary contains similar phrases and terminology to the reference summary.
</Accordion>
<Accordion title="Contextual embedding similarity">
This metric involves creating vector representations (embeddings) of both the generated and reference summaries. The similarity between these embeddings is then calculated, often using cosine similarity. Higher similarity scores indicate that the generated summary captures the semantic meaning and context of the reference summary, even if the exact wording differs.
</Accordion>
<Accordion title="LLM-based grading">
This method involves using an LLM such as Claude to evaluate the quality of generated summaries against a scoring rubric. The rubric can be tailored to your specific needs, assessing key factors such as accuracy, completeness, and coherence. For implementation guidance, see
[Tips for LLM-based grading](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests#tips-for-llm-based-grading)
.
</Accordion>
<Accordion title="Human evaluation">
In addition to creating the reference summaries, legal experts can also evaluate the quality of the generated summaries. Although this is expensive and time-consuming at scale, this is often done on a few summaries as a validation check before deploying to production.
</Accordion>
</AccordionGroup>
### Deploy your prompt
Here are some additional considerations to keep in mind as you deploy your solution to production.
1. **Ensure no liability:** Understand the legal implications of errors in the summaries, which could lead to legal liability for your organization or clients. Provide disclaimers or legal notices clarifying that the summaries are generated by AI and should be reviewed by legal professionals.
2. **Handle diverse document types:** This guide discusses how to extract text from PDFs. In the real world, documents may come in a variety of formats (such as PDFs, Word documents, and text files). Ensure your data extraction pipeline can convert all of the file formats you expect to receive.
3. **Parallelize API calls to Claude:** Long documents with a large number of tokens may require up to a minute for Claude to generate a summary. For large document collections, you may want to send API calls to Claude in parallel so that the summaries can be completed in a reasonable timeframe. Refer to Anthropic’s [rate limits](https://platform.claude.com/docs/en/api/rate-limits#rate-limits) to determine the maximum amount of API calls that can be performed in parallel.
***
## Improve performance
In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview). Here are some advanced strategies:
### Perform meta-summarization to summarize long documents
Legal summarization often involves handling long documents or many related documents at once, such that you surpass Claude’s context window. You can use a chunking method known as meta-summarization to handle this use case. This technique involves breaking down documents into smaller, manageable chunks and then processing each chunk separately. You can then combine the summaries of each chunk to create a meta-summary of the entire document.
Here's an example of how to perform meta-summarization:
```python Python
# Initialize the Anthropic client
client = anthropic.Anthropic()
def chunk_text(text, chunk_size=20000):
return [text[i : i + chunk_size] for i in range(0, len(text), chunk_size)]
def summarize_long_document(
text, details_to_extract, model="claude-opus-5", max_tokens=1000
):
# Format the details to extract to be placed within the prompt's context
Cut at 300 lines. The page has the rest.
about-claude/use-case-guides/overview First recorded · 25 lines, first recorded
The first capture of this source. The page was already there, and this is what it said.
---
title: Guides to common use cases
url: https://platform.claude.com/docs/en/about-claude/use-case-guides/overview
description: "Explore production guides for building common Claude use cases: ticket routing, customer support agents, content moderation, and legal summarization."
---
Claude is designed to excel in a variety of tasks. Explore these in-depth production guides to learn how to build common use cases with Claude.
<CardGroup cols={2}>
<Card title="Ticket routing" icon="headset" href="https://platform.claude.com/docs/en/about-claude/use-case-guides/ticket-routing">
Best practices for using Claude to classify and route customer support tickets at scale.
</Card>
<Card title="Customer support agent" icon="robot" href="https://platform.claude.com/docs/en/about-claude/use-case-guides/customer-support-chat">
Build intelligent, context-aware chatbots with Claude to enhance customer support interactions.
</Card>
<Card title="Content moderation" icon="verified" href="https://platform.claude.com/docs/en/about-claude/use-case-guides/content-moderation">
Techniques and best practices for using Claude to perform content filtering and general content moderation.
</Card>
<Card title="Legal summarization" icon="book" href="https://platform.claude.com/docs/en/about-claude/use-case-guides/legal-summarization">
Summarize legal documents using Claude to extract key information and expedite research.
</Card>
</CardGroup>
about-claude/use-case-guides/ticket-routing First recorded · 525 lines, first recorded
## Prerequisites ## Define whether to use Claude for ticket routing ## Build and deploy your LLM support workflow ### Understand your current support approach ### Define user intent categories ### Establish success criteria ### Choose the right Claude model ### Build a strong prompt ### Deploy your prompt ## Evaluate your prompt ### Build an evaluation function ### Run your evaluation ## Improve performance ### Use a taxonomic hierarchy for cases with 20+ intent categories ### Use vector databases and similarity search retrieval to handle highly variable tickets ### Account specifically for expected edge cases ## Integrate Claude into your greater support workflow
The first capture of this source. The page was already there, and this is what it said.
---
title: Ticket routing
url: https://platform.claude.com/docs/en/about-claude/use-case-guides/ticket-routing
description: This guide walks through how to harness Claude's advanced natural language understanding capabilities to classify customer support tickets at scale based on customer intent, urgency, prioritization, customer profile, and more.
---
## Prerequisites
* A Claude API key and the Python SDK installed
* Access to, and familiarity with, your existing support ticketing system
* A sample set of historical support tickets for testing
## Define whether to use Claude for ticket routing
Here are some key indicators that you should use an LLM like Claude instead of traditional ML approaches for your classification task:
<AccordionGroup>
<Accordion title="You have limited labeled training data available">
Traditional ML processes require massive labeled datasets. Claude's pre-trained model can effectively classify tickets with just a few dozen labeled examples, significantly reducing data preparation time and costs.
</Accordion>
<Accordion title="Your classification categories are likely to change or evolve over time">
Once a traditional ML approach has been established, changing it is a laborious and data-intensive undertaking. On the other hand, as your product or customer needs evolve, Claude can easily adapt to changes in class definitions or new classes without extensive relabeling of training data.
</Accordion>
<Accordion title="You need to handle complex, unstructured text inputs">
Traditional ML models often struggle with unstructured data and require extensive feature engineering. Claude's advanced language understanding allows for accurate classification based on content and context, rather than relying on strict ontological structures.
</Accordion>
<Accordion title="Your classification rules are based on semantic understanding">
Traditional ML approaches often rely on bag-of-words models or simple pattern matching. Claude excels at understanding and applying underlying rules when classes are defined by conditions rather than examples.
</Accordion>
<Accordion title="You require interpretable reasoning for classification decisions">
Many traditional ML models provide little insight into their decision-making process. Claude can provide human-readable explanations for its classification decisions, building trust in the automation system and facilitating easy adaptation if needed.
</Accordion>
<Accordion title="You want to handle edge cases and ambiguous tickets more effectively">
Traditional ML systems often struggle with outliers and ambiguous inputs, frequently misclassifying them or defaulting to a catch-all category. Claude's natural language processing capabilities allow it to better interpret context and nuance in support tickets, potentially reducing the number of misrouted or unclassified tickets that require manual intervention.
</Accordion>
<Accordion title="You need multilingual support without maintaining separate models">
Traditional ML approaches typically require separate models or extensive translation processes for each supported language. Claude's multilingual capabilities allow it to classify tickets in various languages without the need for separate models or extensive translation processes, streamlining support for global customer bases.
</Accordion>
</AccordionGroup>
***
## Build and deploy your LLM support workflow
### Understand your current support approach
Before you automate, it's crucial to understand your existing ticketing system. Start by investigating how your support team currently handles ticket routing.
Consider questions like:
* What criteria are used to determine what SLA/service offering is applied?
* Is ticket routing used to determine which tier of support or product specialist a ticket goes to?
* Are there any automated rules or workflows already in place? In what cases do they fail?
* How are edge cases or ambiguous tickets handled?
* How does the team prioritize tickets?
The more you know about how humans handle certain cases, the better you can work with Claude to do the task.
### Define user intent categories
A well-defined list of user intent categories is crucial for accurate support ticket classification with Claude. Claude’s ability to route tickets effectively within your system is directly proportional to how well-defined your system’s categories are.
Here are some example user intent categories and subcategories.
<AccordionGroup>
<Accordion title="Technical issue">
* Hardware problem
* Software bug
* Compatibility issue
* Performance problem
</Accordion>
<Accordion title="Account management">
* Password reset
* Account access issues
* Billing inquiries
* Subscription changes
</Accordion>
<Accordion title="Product information">
* Feature inquiries
* Product compatibility questions
* Pricing information
* Availability inquiries
</Accordion>
<Accordion title="User guidance">
* How-to questions
* Feature usage assistance
* Best practices advice
* Troubleshooting guidance
</Accordion>
<Accordion title="Feedback">
* Bug reports
* Feature requests
* General feedback or suggestions
* Complaints
</Accordion>
<Accordion title="Order-related">
* Order status inquiries
* Shipping information
* Returns and exchanges
* Order modifications
</Accordion>
<Accordion title="Service request">
* Installation assistance
* Upgrade requests
* Maintenance scheduling
* Service cancellation
</Accordion>
<Accordion title="Security concerns">
* Data privacy inquiries
* Suspicious activity reports
* Security feature assistance
</Accordion>
<Accordion title="Compliance and legal">
* Regulatory compliance questions
* Terms of service inquiries
* Legal documentation requests
</Accordion>
<Accordion title="Emergency support">
* Critical system failures
* Urgent security issues
* Time-sensitive problems
</Accordion>
<Accordion title="Training and education">
* Product training requests
* Documentation inquiries
* Webinar or workshop information
</Accordion>
<Accordion title="Integration and API">
* Integration assistance
* API usage questions
* Third-party compatibility inquiries
</Accordion>
</AccordionGroup>
In addition to intent, ticket routing and prioritization may also be influenced by other factors such as urgency, customer type, SLAs, or language. Be sure to consider other routing criteria when building your automated routing system.
### Establish success criteria
Work with your support team to [define clear success criteria](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests) with measurable benchmarks, thresholds, and goals.
Here are some standard criteria and benchmarks when using LLMs for support ticket routing:
<AccordionGroup>
<Accordion title="Classification consistency">
This metric assesses how consistently Claude classifies similar tickets over time. It's crucial for maintaining routing reliability. Measure this by periodically testing the model with a set of standardized inputs and aiming for a consistency rate of 95% or higher.
</Accordion>
<Accordion title="Adaptation speed">
This measures how quickly Claude can adapt to new categories or changing ticket patterns. Test this by introducing new ticket types and measuring the time it takes for the model to achieve satisfactory accuracy (for example, >90%) on these new categories. Aim for adaptation within 50–100 sample tickets.
</Accordion>
<Accordion title="Multilingual handling">
This assesses Claude's ability to accurately route tickets in multiple languages. Measure the routing accuracy across different languages, aiming for no more than a 5–10% drop in accuracy for non-primary languages.
</Accordion>
<Accordion title="Edge case handling">
This evaluates Claude's performance on unusual or complex tickets. Create a test set of edge cases and measure the routing accuracy, aiming for at least 80% accuracy on these challenging inputs.
</Accordion>
<Accordion title="Bias mitigation">
This measures Claude's fairness in routing across different customer demographics. Regularly audit routing decisions for potential biases, aiming for consistent routing accuracy (within 2–3%) across all customer groups.
</Accordion>
<Accordion title="Prompt efficiency">
In situations where minimizing token count is crucial, this criteria assesses how well Claude performs with minimal context. Measure routing accuracy with varying amounts of context provided, aiming for 90%+ accuracy with just the ticket title and a brief description.
</Accordion>
<Accordion title="Explainability score">
This evaluates the quality and relevance of Claude's explanations for its routing decisions. Human raters can score explanations on a scale (for example, 1–5), with the goal of achieving an average score of 4 or higher.
</Accordion>
</AccordionGroup>
Here are some common success criteria that may be useful regardless of whether an LLM is used:
<AccordionGroup>
<Accordion title="Routing accuracy">
Routing accuracy measures how often tickets are correctly assigned to the appropriate team or individual on the first try. This is typically measured as a percentage of correctly routed tickets out of total tickets. Industry benchmarks often aim for 90–95% accuracy, though this can vary based on the complexity of the support structure.
</Accordion>
<Accordion title="Time-to-assignment">
This metric tracks how quickly tickets are assigned after being submitted. Faster assignment times generally lead to quicker resolutions and improved customer satisfaction. Best-in-class systems often achieve average assignment times of under 5 minutes, with many aiming for near-instantaneous routing (which is possible with LLM implementations).
</Accordion>
<Accordion title="Rerouting rate">
The rerouting rate indicates how often tickets need to be reassigned after initial routing. A lower rate suggests more accurate initial routing. Aim for a rerouting rate below 10%, with top-performing systems achieving rates as low as 5% or less.
</Accordion>
<Accordion title="First-contact resolution rate">
This measures the percentage of tickets resolved during the first interaction with the customer. Higher rates indicate efficient routing and well-prepared support teams. Industry benchmarks typically range from 70–75%, with top performers achieving rates of 80% or higher.
</Accordion>
<Accordion title="Average handling time">
Average handling time measures how long it takes to resolve a ticket from start to finish. Efficient routing can significantly reduce this time. Benchmarks vary widely by industry and complexity, but many organizations aim to keep average handling time under 24 hours for non-critical issues.
</Accordion>
<Accordion title="Customer satisfaction scores">
Often measured through post-interaction surveys, these scores reflect overall customer happiness with the support process. Effective routing contributes to higher satisfaction. Aim for CSAT scores of 90% or higher, with top performers often achieving 95%+ satisfaction rates.
</Accordion>
<Accordion title="Escalation rate">
This measures how often tickets need to be escalated to higher tiers of support. Lower escalation rates often indicate more accurate initial routing. Strive for an escalation rate below 20%, with best-in-class systems achieving rates of 10% or less.
</Accordion>
<Accordion title="Agent productivity">
This metric looks at how many tickets agents can handle effectively after implementing the routing solution. Improved routing should increase productivity. Measure this by tracking tickets resolved per agent per day or hour, aiming for a 10–20% improvement after implementing a new routing system.
</Accordion>
<Accordion title="Self-service deflection rate">
This measures the percentage of potential tickets resolved through self-service options before entering the routing system. Higher rates indicate effective pre-routing triage. Aim for a deflection rate of 20–30%, with top performers achieving rates of 40% or higher.
</Accordion>
<Accordion title="Cost per ticket">
This metric calculates the average cost to resolve each support ticket. Efficient routing should help reduce this cost over time. While benchmarks vary widely, many organizations aim to reduce cost per ticket by 10–15% after implementing an improved routing system.
</Accordion>
</AccordionGroup>
### Choose the right Claude model
The choice of model depends on the trade-offs between cost, accuracy, and response time.
Many customers have found `claude-haiku-4-5-20251001` an ideal model for ticket routing, as it is the fastest and most cost-effective model in the Claude 4 family while still delivering excellent results. If your classification problem requires deep subject matter expertise or a large volume of intent categories, or complex reasoning, you may opt for the [larger Sonnet model](https://platform.claude.com/docs/en/about-claude/models).
### Build a strong prompt
Ticket routing is a type of classification task. Claude analyzes the content of a support ticket and classifies it into predefined categories based on the issue type, urgency, required expertise, or other relevant factors.
Write a ticket classification prompt. The initial prompt should contain the contents of the user request and return both the reasoning and the intent.
<Tip>
Try the [metaprompt recipe from the Claude Cookbook](https://colab.research.google.com/github/anthropics/claude-cookbooks/blob/main/misc/metaprompt.ipynb) to have Claude write a first draft for you.
</Tip>
Here's an example ticket routing classification prompt:
```python
def classify_support_request(ticket_contents):
# Define the prompt for the classification task
classification_prompt = f"""You will be acting as a customer support ticket classification system. Your task is to analyze customer support requests and output the appropriate classification intent for each request, along with your reasoning.
Here is the customer support request you need to classify:
<request>{ticket_contents}</request>
Please carefully analyze the above request to determine the customer's core intent and needs. Consider what the customer is asking for has concerns about.
First, write out your reasoning and analysis of how to classify this request inside <reasoning> tags.
Then, output the appropriate classification label for the request inside a <intent> tag. The valid intents are:
<intents>
<intent>Support, Feedback, Complaint</intent>
<intent>Order Tracking</intent>
<intent>Refund/Exchange</intent>
</intents>
A request may have ONLY ONE applicable intent. Only include the intent that is most applicable to the request.
As an example, consider the following request:
<request>Hello! I had high-speed fiber internet installed on Saturday and my installer, Kevin, was absolutely fantastic! Where can I send my positive review? Thanks for your help!</request>
Here is an example of how your output should be formatted (for the above example request):
<reasoning>The user seeks information in order to leave positive feedback.</reasoning>
<intent>Support, Feedback, Complaint</intent>
Here are a few more examples:
<examples>
<example 2>
Example 2 Input:
<request>I wanted to write and personally thank you for the compassion you showed towards my family during my father's funeral this past weekend. Your staff was so considerate and helpful throughout this whole process; it really took a load off our shoulders. The visitation brochures were beautiful. We'll never forget the kindness you showed us and we are so appreciative of how smoothly the proceedings went. Thank you, again, Amarantha Hill on behalf of the Hill Family.</request>
Example 2 Output:
<reasoning>User leaves a positive review of their experience.</reasoning>
<intent>Support, Feedback, Complaint</intent>
</example 2>
<example 3>
...
</example 8>
<example 9>
Example 9 Input:
<request>Your website keeps sending ad-popups that block the entire screen. It took me twenty minutes just to finally find the phone number to call and complain. How can I possibly access my account information with all of these popups? Can you access my account for me, since your website is broken? I need to know what the address is on file.</request>
Example 9 Output:
Cut at 300 lines. The page has the rest.
agents-and-tools/agent-skills/best-practices First recorded · 1179 lines, first recorded
## Core principles ### Concise is key ### Set appropriate degrees of freedom ### Test with all models you plan to use ## Skill structure ### Naming conventions ### Writing effective descriptions ### Progressive disclosure patterns #### Visual overview: From simple to complex #### Pattern 1: High-level guide with references #### Pattern 2: Domain-specific organization #### Pattern 3: Conditional details ### Avoid deeply nested references ### Structure longer reference files with table of contents ## Workflows and feedback loops ### Use workflows for complex tasks ### Implement feedback loops ## Content guidelines ### Avoid time-sensitive information ### Use consistent terminology ## Common patterns ### Template pattern # [Analysis Title] ## Executive summary ## Key findings ## Recommendations # [Analysis Title] ## Executive summary ## Key findings ## Recommendations ### Examples pattern ### Conditional workflow pattern ## Evaluation and iteration ### Build evaluations first ### Develop Skills iteratively with Claude ### Observe how Claude navigates Skills ## Anti-patterns to avoid ### Avoid Windows-style paths ### Avoid offering too many options ## Advanced: Skills with executable code ### Solve, don't defer ### Provide utility scripts # Returns: "OK" or lists conflicts ### Use visual analysis ### Create verifiable intermediate outputs ### Package dependencies ### Runtime environment ### MCP tool references ### Avoid assuming tools are installed ## Technical notes ### YAML frontmatter requirements ### Token budgets ## Checklist for effective Skills ### Core quality ### Code and scripts ### Testing ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Skill authoring best practices
url: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
description: Learn how to write effective Skills that Claude can discover and use successfully.
---
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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).
## Core principles
### Concise is key
The [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) 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):
````markdown
## 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):
```markdown
## 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:
```markdown
## 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:
````markdown
## 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:
````markdown
## 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
<Note>
**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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#skill-structure).
</Note>
### 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.
<Warning>
**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"
</Warning>
**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:**
```yaml
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:**
```yaml
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
```
**Git Commit Helper skill:**
```yaml
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:
```yaml
description: Helps with documents
```
```yaml
description: Processes data
```
```yaml
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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#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:
```text
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
````markdown
---
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:
Cut at 300 lines. The page has the rest.
agents-and-tools/agent-skills/claude-api-skill First recorded · 183 lines, first recorded
## What the skill provides ## When the skill activates ## Supported languages ## How to use the skill ### In Claude Code (bundled) ### From the skills repository ## Migrating to a newer Claude model ## Setting up a Managed Agent ## Example usage ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Claude API skill
url: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill
description: 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.
---
The `claude-api` skill is an open-source [Agent Skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) 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](https://code.claude.com/docs/en/overview) 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#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](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) 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](https://platform.claude.com/docs/en/about-claude/models/migration-guide#migrating-from-claude-opus-4-8-to-claude-opus-5))
* **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](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) 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](https://code.claude.com/docs/en/overview) 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:
```text wrap
/claude-api
```
For more about how bundled skills work in Claude Code, see the [Claude Code skills documentation](https://code.claude.com/docs/en/skills#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:
```bash
npx skills add https://github.com/anthropics/skills --skill claude-api
```
Or install it as a [Claude Code plugin](https://code.claude.com/docs/en/plugins):
```text wrap
/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 `/claude-api migrate`:
```text wrap
/claude-api migrate this project to claude-opus-5
```
You can also pass a specific scope up front to skip the scope-confirmation question:
```text wrap
/claude-api migrate everything under src/ to claude-opus-5
/claude-api migrate apps/api.py and apps/worker.py to claude-opus-5
```
When the scope is ambiguous (for example, a bare `/claude-api migrate to claude-opus-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`) 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](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) where applicable
* **Beta header cleanup**, removing headers that are GA on the target model (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](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) when the target is Claude Fable 5 or Claude Opus 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 from Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/migration-guide#migrating-from-claude-opus-4-8-to-claude-opus-5).
## Setting up a Managed Agent
To scaffold a new Managed Agent from scratch, invoke the `managed-agents-onboard` subcommand:
```text wrap
/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:**
```text wrap
Build a streaming chat UI with the Claude API in TypeScript
```
**Migrating an existing project:**
```text wrap
/claude-api migrate this codebase to claude-opus-5 and re-tune effort
```
**Onboarding a new Managed Agent:**
```text wrap
/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
<CardGroup cols={2}>
<Card title="Agent Skills overview" icon="graduation-cap" href="https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview">
Learn about how Agent Skills work and the progressive disclosure model
</Card>
<Card title="Client SDKs" icon="code" href="https://platform.claude.com/docs/en/cli-sdks-libraries/overview">
Browse the official Anthropic SDKs for all supported languages
</Card>
<Card title="Skills repository" icon="github-logo" href="https://github.com/anthropics/skills">
Explore the public Anthropic skills repository on GitHub
</Card>
</CardGroup>
agents-and-tools/agent-skills/enterprise First recorded · 188 lines, first recorded
## Security review and vetting ### Risk tier assessment ### Review checklist ## Evaluating Skills before deployment ### What to evaluate ### Evaluation requirements ### Using evaluations for lifecycle decisions ## Skill lifecycle management ## Organizing Skills at scale ### Recall limits ### Start specific, consolidate later ### Naming and cataloging ### Role-based bundles ## Distribution and version control ### Source control ### API-based distribution ### Versioning strategy ### Cross-surface considerations ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Skills for enterprise
url: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise
description: Governance, security review, evaluation, and organizational guidance for deploying Agent Skills at enterprise scale.
---
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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices). For architecture details, see the [Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).
## Security review and vetting
Deploying Skills in an enterprise requires answering two distinct questions:
1. **Are Skills safe in general?** See the [security considerations](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#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.
<Warning>
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.
</Warning>
## 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#evaluation-and-iteration) in best practices. For general evaluation methodology, see [develop test cases](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests).
### 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
<Steps>
<Step title="Plan">
Identify workflows that are repetitive, error-prone, or require specialized knowledge. Map these to organizational roles and determine which are candidates for Skills.
</Step>
<Step title="Create and review">
Ensure the Skill author follows [best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices). Require a security review using the [review checklist](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise#review-checklist). Require an evaluation suite before approval. Establish separation of duties: Skill authors should not be their own reviewers.
</Step>
<Step title="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.
</Step>
<Step title="Deploy">
Upload through the Skills API for workspace-wide access. See [Using Skills with the API](https://platform.claude.com/docs/en/build-with-claude/skills-guide) for upload and version management. Document the Skill in your internal registry with purpose, owner, and version.
</Step>
<Step title="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.
</Step>
<Step title="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.
</Step>
</Steps>
## 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 8 Skills for each request (see [Using Skills with the API](https://platform.claude.com/docs/en/build-with-claude/skills-guide)). 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.
<Tip>
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.
</Tip>
**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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#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](https://platform.claude.com/docs/en/build-with-claude/skills-guide) for upload, versioning, and management endpoints.
### Versioning strategy
* **Production:** Pin Skills to specific versions. 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
<Warning>
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.
</Warning>
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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#cross-surface-availability).
## Next steps
<CardGroup cols={2}>
<Card title="Agent Skills overview" icon="book-open" href="https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview">
Architecture and platform details
</Card>
<Card title="Best practices" icon="lightbulb" href="https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices">
Authoring guidance for Skill creators
</Card>
<Card title="Using Skills with the API" icon="code" href="https://platform.claude.com/docs/en/build-with-claude/skills-guide">
Upload and manage Skills programmatically
</Card>
</CardGroup>
agents-and-tools/agent-skills/overview First recorded · 337 lines, first recorded
## Why use Skills ## Using Skills ## How Skills work ### Level 1: Metadata (always loaded) ### Level 2: Instructions (loaded when triggered) ### Level 3: Resources and code (loaded as needed) ### The Skills architecture ### Example: Loading a PDF processing Skill ## Where Skills work ### Claude API ### Claude Code ### claude.ai ## Skill structure ## Security considerations ## Available Skills ### Pre-built Agent Skills ### Open-source Skills ### Custom Skills examples ## Data retention ## Limitations and constraints ### Cross-surface availability ### Sharing scope ### Runtime environment constraints ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Agent Skills
url: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
description: 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.
---
<Note>
For how zero data retention (ZDR) applies to this feature, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
</Note>
## 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
<Note>
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).
</Note>
## 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](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry). On Microsoft Foundry, Agent Skills require a [Hosted on Anthropic deployment](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure). See [Available Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#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](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), upload custom Skills through the Skills API.
<Note>
**Get started:**
* For pre-built Agent Skills: See the [quickstart tutorial](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart) 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
</Note>
## 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:
```yaml
---
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:
````markdown
# 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:
```text
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:
<Note>
Claude Platform on AWS and Microsoft Foundry inherit the same Skills behavior as the Claude API in all following sections.
</Note>
### 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](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool).
**Prerequisites:** Using Skills through the API requires the [code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool), whose container Skills run in, and one beta header:
* `skills-2025-10-02` - Enables Skills functionality
Add a second header, `files-api-2025-04-14`, when you use the [Files API](https://platform.claude.com/docs/en/build-with-claude/files) to upload input files to the container or download files a Skill produces.
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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#limitations-and-constraints) for details.
To learn more, see [Using Agent Skills with the API](https://platform.claude.com/docs/en/build-with-claude/skills-guide).
### Claude Code
[Claude Code](https://code.claude.com/docs/en/overview) 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill) comes bundled with it. See the full list of [built-in commands and Skills](https://code.claude.com/docs/en/commands) 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](https://code.claude.com/docs/en/skills).
### 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](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude). 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?](https://support.claude.com/en/articles/12512176-what-are-skills)
* [Using Skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
* [How to create custom Skills](https://support.claude.com/en/articles/12512198-creating-custom-skills)
* [Teach Claude your way of working using Skills](https://support.claude.com/en/articles/12580051-teach-claude-your-way-of-working-using-skills)
## Skill structure
Every Skill requires a `SKILL.md` file with YAML frontmatter:
```markdown
---
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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices).
## 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.
<Warning>
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.
</Warning>
**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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise).
## 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](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), and claude.ai. See the [quickstart tutorial](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart) 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill):** 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](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
## Limitations and constraints
Claude Platform on AWS and Microsoft Foundry follow the same limitations as the Claude API in the following subsections.
### 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
Cut at 300 lines. The page has the rest.
agents-and-tools/agent-skills/quickstart First recorded · 1255 lines, first recorded
## Prerequisites ## Agent Skills overview ## Step 1: List available Skills ## Step 2: Create a presentation ## Step 3: Download the created file ## Try more examples ### Create a spreadsheet ### Create a Word document ### Generate a PDF ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Get started with Agent Skills in the API
url: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart
description: Learn how to use Agent Skills to create documents with the Claude API in under 10 minutes.
---
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](https://platform.claude.com/settings/keys) or a logged-in [ant CLI](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication)
* A [client SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) 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
<Note>
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.
</Note>
## 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:
<CodeGroup defaultLanguage="CLI">
```bash cURL
# List Anthropic-managed Skills
curl --fail-with-body -sS "https://api.anthropic.com/v1/skills?source=anthropic" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: skills-2025-10-02" |
jq -r '.data[] | "\(.id): \(.display_title)"'
```
```bash CLI
# List Anthropic-managed Skills
ant beta:skills list --source anthropic
```
```python Python
# List Anthropic-managed Skills
skills = client.beta.skills.list(source="anthropic")
for skill in skills.data:
print(f"{skill.id}: {skill.display_title}")
```
```typescript TypeScript
// List Anthropic-managed Skills
const skills = await client.beta.skills.list({ source: "anthropic" });
for (const skill of skills.data) {
console.log(`${skill.id}: ${skill.display_title}`);
}
```
```csharp C#
// List Anthropic-managed Skills
var skills = await client.Beta.Skills.List(new SkillListParams { Source = "anthropic" });
foreach (var skill in skills.Items)
{
Console.WriteLine($"{skill.ID}: {skill.DisplayTitle}");
}
```
```go Go
// List Anthropic-managed Skills
skills, err := client.Beta.Skills.List(ctx, anthropic.BetaSkillListParams{
Source: anthropic.String("anthropic"),
})
if err != nil {
panic(err)
}
for _, skill := range skills.Data {
fmt.Printf("%s: %s\n", skill.ID, skill.DisplayTitle)
}
```
```java Java
// List Anthropic-managed Skills
SkillListPage skills = client.beta().skills().list(
SkillListParams.builder().source("anthropic").build()
);
for (SkillListResponse skill : skills.data()) {
IO.println(skill.id() + ": " + skill.displayTitle().orElse(""));
}
```
```php PHP
// List Anthropic-managed Skills
$skills = $client->beta->skills->list(source: 'anthropic');
foreach ($skills->data as $skill) {
echo "{$skill->id}: {$skill->displayTitle}\n";
}
```
```ruby Ruby
# List Anthropic-managed Skills
skills = client.beta.skills.list(source: "anthropic")
skills.data.each do |skill|
puts "#{skill.id}: #{skill.display_title}"
end
```
</CodeGroup>
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:
<CodeGroup>
```bash cURL
# Create a message with the PowerPoint Skill
response=$(
curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: skills-2025-10-02" \
-d @- <<'EOF'
{
"model": "claude-opus-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"}]
}
EOF
)
jq -r '"stop_reason=\(.stop_reason), blocks=\(.content | length)"' <<<"$response"
```
```bash CLI
# Create a message with the PowerPoint Skill
response=$(ant beta:messages create --format json \
--beta skills-2025-10-02 <<'YAML'
model: claude-opus-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
YAML
)
jq -r '"stop_reason=\(.stop_reason), blocks=\(.content | length)"' <<<"$response"
```
```python Python
# Create a message with the PowerPoint Skill
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=16000,
betas=["skills-2025-10-02"],
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)}")
```
```typescript TypeScript
// Create a message with the PowerPoint Skill
const response = await client.beta.messages.create({
model: "claude-opus-5",
max_tokens: 16000,
betas: ["skills-2025-10-02"],
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" }],
});
console.log(
`stop_reason=${response.stop_reason}, blocks=${response.content.length}`,
);
```
```csharp C#
// Create a message with the PowerPoint Skill
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 16000,
Betas = ["skills-2025-10-02"],
Container = new BetaContainerParams
{
Skills =
[
new BetaSkillParams
{
Type = BetaSkillParamsType.Anthropic,
SkillID = "pptx",
Version = "latest",
},
],
},
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = "Create a presentation about renewable energy with 5 slides",
},
],
Tools = [new BetaCodeExecutionTool20260521()],
});
Console.WriteLine($"stop_reason={response.StopReason?.Raw()}, blocks={response.Content.Count}");
```
```go Go
// Create a message with the PowerPoint Skill
response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 16000,
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaSkills2025_10_02,
},
Container: anthropic.BetaMessageNewParamsContainerUnion{
OfContainers: &anthropic.BetaContainerParams{
Skills: []anthropic.BetaSkillParams{
{
Type: anthropic.BetaSkillParamsTypeAnthropic,
SkillID: "pptx",
Version: anthropic.String("latest"),
},
},
},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(
anthropic.NewBetaTextBlock("Create a presentation about renewable energy with 5 slides"),
),
},
Tools: []anthropic.BetaToolUnionParam{
{OfCodeExecutionTool20260521: &anthropic.BetaCodeExecutionTool20260521Param{}},
},
})
if err != nil {
panic(err)
}
fmt.Printf("stop_reason=%s, blocks=%d\n", response.StopReason, len(response.Content))
```
```java Java
// Create a message with the PowerPoint Skill
BetaMessage response = client.beta().messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(16000)
.addBeta(AnthropicBeta.SKILLS_2025_10_02)
.container(
BetaContainerParams.builder()
.addSkill(
BetaSkillParams.builder()
.type(BetaSkillParams.Type.ANTHROPIC)
.skillId("pptx")
.version("latest")
Cut at 300 lines. The page has the rest.
agents-and-tools/mcp-connector First recorded · 1499 lines, first recorded
## Compatibility ## Key features ## When Claude uses MCP tools ## Limitations ## Using the MCP connector in the Messages API ### Basic example ## MCP server configuration ### Field descriptions ## MCP toolset configuration ### Basic structure ### Field descriptions ### Tool configuration options ### Configuration merging ## Common configuration patterns ### Enable all tools with default configuration ### Allowlist: enable only specific tools ### Denylist: disable specific tools ### Mixed: allowlist with per-tool configuration ## Validation rules ## Response content types ### MCP tool use block ### MCP tool result block ## Multiple MCP servers ## Authentication ### Obtaining an access token for testing ### Using the access token ## Client-side MCP helpers ### Installation ### Available helpers ### Use MCP tools ### Use MCP prompts ### Use MCP resources ### Error handling ## Batch requests ## Data retention ## Migration guide ### Key changes ### Migration steps ### Common migration patterns ## Deprecated version: mcp-client-2025-04-04 ### Deprecated field descriptions
The first capture of this source. The page was already there, and this is what it said.
---
title: MCP connector
url: https://platform.claude.com/docs/en/agents-and-tools/mcp-connector
description: Connect to remote MCP servers directly from the Messages API without an MCP client, and allowlist, denylist, or configure individual tools.
---
## Compatibility
- Status: Beta
- [Beta header](https://platform.claude.com/docs/en/api/beta-headers): `mcp-client-2025-11-20`
- [ZDR](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention): not eligible
- Platforms: Claude API (beta), Claude Platform on AWS (beta), Microsoft Foundry (beta) [1]; not available on Amazon Bedrock, Google Cloud
1. On [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), the MCP connector requires a [Hosted on Anthropic deployment](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure).
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.
<Note>
The previous version of this feature (`mcp-client-2025-04-04`) is deprecated. See [Deprecated version: mcp-client-2025-04-04](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#deprecated-version-mcp-client-2025-04-04).
</Note>
## 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](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview#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:
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "Content-Type: application/json" \
-H "X-API-Key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: mcp-client-2025-11-20" \
-d '{
"model": "claude-opus-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"
}
]
}'
```
```bash CLI
ant beta:messages create --beta mcp-client-2025-11-20 <<'YAML'
model: claude-opus-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
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-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)
```
```typescript TypeScript
const anthropic = new Anthropic();
const response = await anthropic.beta.messages.create({
model: "claude-opus-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"]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 1000,
Messages = new List<BetaMessageParam>
{
new() { Role = Role.User, Content = "What tools do you have available?" }
},
McpServers = new List<BetaRequestMcpServerUrlDefinition>
{
new()
{
Url = "https://example-server.modelcontextprotocol.io/sse",
Name = "example-mcp",
AuthorizationToken = "YOUR_TOKEN"
}
},
Tools = new List<BetaToolUnion>
{
new BetaMcpToolset("example-mcp")
},
Betas = [AnthropicBeta.McpClient2025_11_20]
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 1000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
},
MCPServers: []anthropic.BetaRequestMCPServerURLDefinitionParam{
{
URL: "https://example-server.modelcontextprotocol.io/sse",
Name: "example-mcp",
AuthorizationToken: anthropic.String("YOUR_TOKEN"),
},
},
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
MCPServerName: "example-mcp",
}},
},
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaMCPClient2025_11_20,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.beta.messages.BetaMcpToolset;
// ...
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(1000L)
.addUserMessage("What tools do you have available?")
.addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
.url("https://example-server.modelcontextprotocol.io/sse")
.name("example-mcp")
.authorizationToken("YOUR_TOKEN")
.build())
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.build())
.addBeta(AnthropicBeta.MCP_CLIENT_2025_11_20)
.build();
BetaMessage response = client.beta().messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->beta->messages->create(
maxTokens: 1000,
messages: [
['role' => 'user', 'content' => 'What tools do you have available?']
],
model: 'claude-opus-5',
mcpServers: [
[
'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'],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
response = client.beta.messages.create(
model: "claude-opus-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"]
)
puts response
```
Cut at 300 lines. The page has the rest.
agents-and-tools/mcp-tunnels/concepts First recorded · 72 lines, first recorded
## Components ## Credential provisioning ## Connection model ## See also
The first capture of this source. The page was already there, and this is what it said.
--- title: Architecture and components url: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts description: Canonical names for the parts of an MCP tunnel deployment, the two credential-provisioning modes, and the connection model. --- <Note> MCP tunnels are in research preview. [Request access](https://claude.com/form/claude-managed-agents) to try them. </Note> This page defines the terms used throughout the [MCP tunnels](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview) 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](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation), 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. ```mermaid sequenceDiagram participant A as Anthropic<br/>backend participant E as Tunnel edge<br/>(Cloudflare network) participant C as cloudflared participant P as Proxy participant M as Upstream<br/>MCP server note over C,M: Inside your network C->>E: 1. Outbound connection (port 7844) note over C,E: Connection stays open.<br/>No inbound port is opened. A->>E: 2. MCP request (outer mTLS) E->>C: carried over the open connection C->>P: localhost:8080 note over A,P: Inner TLS spans Anthropic backend to proxy.<br/>Terminates at the proxy. P->>M: 3. Route by hostname M-->>P: response P-->>A: response (same path, reversed) ``` ## See also * [MCP tunnels](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview) for the security model and shared-responsibility table. * [MCP tunnels reference](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference) for proxy configuration fields, certificate requirements, and the setup component.
agents-and-tools/mcp-tunnels/console First recorded · 163 lines, first recorded
## Prerequisites ## Create a tunnel ## Get the connection details ## Add a CA certificate ## Deploy the tunnel stack ## Use the tunnel in an agent ## Archive a tunnel ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Manage tunnels in the Console
url: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console
description: Create tunnels, register CA certificates, retrieve the tunnel token, and attach tunneled MCP servers to agents from the Claude Console.
---
<Note>
MCP tunnels are in research preview. [Request access](https://claude.com/form/claude-managed-agents) to try them.
</Note>
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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) to an agent. [Deploy MCP tunnels with Helm](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm) and [Deploy MCP tunnels with Docker Compose](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose) cover running the [tunnel stack](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#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](https://platform.claude.com/docs/en/agents-and-tools/remote-mcp-servers) 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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) (recommended).** Set up [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning).** Skip programmatic access. After creating the tunnel, [get the tunnel token](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details), generate and [register a CA certificate](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate) yourself, and supply the token and your server certificate to your tunnel stack as secrets.
## Create a tunnel
<Steps>
<Step title="Open the MCP tunnels page">
In the Console sidebar, go to **Manage > MCP tunnels**. Tunnels are workspace-scoped; the new tunnel belongs to the workspace currently selected in the Console, so switch workspaces first if you want it elsewhere.
</Step>
<Step title="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.
</Step>
<Step title="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](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation); 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 under **Settings > Workload identity > Issuers** 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 under **Settings > Workspaces** 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.
</Step>
<Step title="Create the tunnel">
Click **Create tunnel**. The Console provisions the tunnel and opens the detail page.
</Step>
<Step title="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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#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 under **Settings > Workload identity > Rules**. | 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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details). |
| The **organization ID** (a UUID), shown under **Settings > Organization**. | A **CA certificate** that you generate and [register on the tunnel](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#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.
</Step>
</Steps>
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. |
<Note>
Every reveal and rotation is recorded in your organization's [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api) 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.
</Note>
## Add a CA certificate
Anthropic verifies [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) to your [proxy](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#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.
<Steps>
<Step title="Find the Certificates section">
On the tunnel's detail page, scroll to the **Certificates** section and click **Add certificate**.
</Step>
<Step title="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.
</Step>
<Step title="Add the certificate">
Click **Add certificate**. The fingerprint and expiry appear in the certificate list, and the slot count on the section header increments.
</Step>
</Steps>
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:
<CardGroup cols={2}>
<Card title="Deploy with Docker Compose" icon="cube" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose">
Run the tunnel stack on a single host. Both programmatic-access and manual flows.
</Card>
<Card title="Deploy with Helm" icon="stack" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm">
Run the tunnel stack on a Kubernetes cluster. Both programmatic-access and manual flows.
</Card>
</CardGroup>
## 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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers).
<Note>
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.
</Note>
<Steps>
<Step title="Open the New session modal">
Go to **Managed Agents > Sessions** and click **New session**.
</Step>
<Step title="Define an inline agent">
In the agent picker, choose **Create new agent** so you can edit the MCP server list directly.
</Step>
<Step title="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.
</Step>
<Step title="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.
</Step>
</Steps>
<Note>
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.
</Note>
## Archive a tunnel
Archiving immediately stops the tunnel from accepting connections and is permanent.
In the **MCP tunnels** list, 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
<CardGroup cols={2}>
<Card title="Deploy with Helm" icon="stack" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm">
Install on a Kubernetes cluster using the Anthropic Helm chart.
</Card>
<Card title="Security" icon="lock" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/security">
Hardening guidance, credential rotation, and breach response.
</Card>
</CardGroup>
agents-and-tools/mcp-tunnels/deploy-compose First recorded · 474 lines, first recorded
## Before you begin ## Optional: Use a sample MCP server ## Install ## Verify the deployment ## Upgrades ### Rotate the tunnel token ### Certificate renewal ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Deploy MCP tunnels with Docker Compose
url: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose
description: Install the MCP tunnel stack on a VM using Docker Compose.
---
<Note>
MCP tunnels are in research preview. [Request access](https://claude.com/form/claude-managed-agents) to try them.
</Note>
This guide deploys the [tunnel stack](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#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 (or create the federation rule directly under **Settings > Workload identity** if you're letting the setup component create the tunnel) so the setup component can authenticate through Workload Identity Federation. Record the federation rule ID (`fdrl_...`) and your organization ID.
* **Manual.** Skip programmatic access. You'll [get the tunnel token from the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details), generate a CA and server certificate yourself, and [register the CA in the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) (7844 TCP and UDP). See the full [network requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose#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:
```bash
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.
<Tabs>
<Tab title="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.
<Steps>
<Step title="Prepare the deployment directory">
```bash
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/`.
</Step>
<Step title="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.
```bash
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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose#optional-use-a-sample-mcp-server), append it as a service:
```bash
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
```
</Step>
<Step title="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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel):
```bash
# 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](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation#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:
```bash
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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#setup-component-authentication-failures) if it errors.
Retrieve your tunnel domain and export it for later steps:
```bash
export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain)
echo "$TUNNEL_DOMAIN"
```
<Note>
Workload Identity Federation tokens are short-lived (1 hour by default) and expire automatically; there is nothing to revoke after setup completes.
</Note>
</Step>
<Step title="Write the proxy config">
`tunnel_domain` is **required**: the [proxy](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#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.
```bash
cat > config/mcp-proxy.yaml <<EOF
listen_addr: ":8080"
log_level: info
shutdown_timeout: 30s
tunnel_domain: ${TUNNEL_DOMAIN}
tls:
cert_file: /data/tls.crt
key_file: /data/tls.key
routes:
echo: http://hello-mcp:9000
EOF
```
The `echo:` route targets the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose#optional-use-a-sample-mcp-server); replace it with (or add) your own routes. See the [proxy configuration](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#proxy-configuration) reference for all available fields.
</Step>
<Step title="Start the deployment">
```bash
export TUNNEL_TOKEN=$(sudo cat data/tunnel-token)
docker compose up -d
```
</Step>
</Steps>
</Tab>
<Tab title="Without programmatic access">
Use this flow if you didn't turn on **Set up programmatic access**, or for local development and testing. There is no `setup` service.
<Steps>
<Step title="Get the tunnel token and domain from the Console">
On the tunnel detail page, copy the **Domain** (it has the form `abcd1234.tunnel.anthropic.com`), then click the eye icon next to **Token** to fetch the tunnel token and use the copy icon to copy it.
Set both as shell variables for the rest of the guide:
```bash
export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
export TUNNEL_TOKEN='eyJ...'
```
</Step>
<Step title="Scaffold and generate certificates">
```bash
mkdir -p mcp-tunnel/{data,config}
cd mcp-tunnel
```
The proxy listens on `:8080` over plain WebSocket; the [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) handshake happens **inside** that WebSocket stream using these certificates. Anthropic verifies the inner handshake against the CA you register in the Console. The server certificate's Subject Alternative Name (SAN) must include `*.<tunnel-domain>` per the [certificate requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#certificate-requirements).
```bash
# 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 <<EOF
subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}
authorityKeyIdentifier = keyid,issuer
extendedKeyUsage = serverAuth
EOF
# Server certificate signed by the CA
openssl req -newkey rsa:2048 -nodes \
-keyout 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
# Allow the non-root proxy container (UID 65532) to read the key from
# the bind mount. Without the world-read bit the container cannot open
# a host-owned file.
chmod 644 data/tls.key
```
</Step>
<Step title="Register the CA certificate in the Console">
On the tunnel detail page, scroll to the **Certificates** section and click **Add certificate**. Upload `data/ca.crt` directly with **Choose file** (the modal accepts `.pem`, `.crt`, and `.cer`), or paste its contents:
```bash
cat data/ca.crt
```
The tunnel's status flips to **Active** once a certificate is registered. See [Add a CA certificate](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate).
</Step>
<Step title="Write the proxy config">
`tunnel_domain` is **required**: the proxy 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.
```bash
cat > config/mcp-proxy.yaml <<EOF
listen_addr: ":8080"
log_level: info
Cut at 300 lines. The page has the rest.
agents-and-tools/mcp-tunnels/deploy-helm First recorded · 437 lines, first recorded
## Before you begin ## Optional: Use a sample MCP server ## Install ## Verify the deployment ## Optional configuration ### Restrict egress with NetworkPolicy ### Tune the proxy ### Supply your own OIDC token ## Upgrades ### Upgrade from chart 1.x ### Change configuration ### Rotate the tunnel token ### Certificate renewal ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Deploy MCP tunnels with Helm
url: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm
description: Install the tunnel stack on a Kubernetes cluster using the Anthropic Helm chart.
---
<Note>
MCP tunnels are in research preview. [Request access](https://claude.com/form/claude-managed-agents) to try them.
</Note>
The Anthropic Helm chart installs the [tunnel stack](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) (recommended).** The [setup component](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning).** Skip programmatic access. You'll [get the tunnel token from the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details), generate a CA and server certificate yourself, [register the CA in the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) (7844 TCP and UDP). See the full [network requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#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:
```bash
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
<Tabs>
<Tab title="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.
<Steps>
<Step title="Set up Workload Identity Federation for the cluster">
Follow [Use WIF with Kubernetes](https://platform.claude.com/docs/en/manage-claude/wif-providers/kubernetes) 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 <release> ... | 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` |
<Note>
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`.
</Note>
If the tunnel is in a workspace other than the organization's default, also add the rule's service account as a member of that workspace under **Settings > Workspaces** (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`.
<Note>
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.
</Note>
</Step>
<Step title="Fetch the default values">
```bash
helm show values \
oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
--version 2.0.2 > values.yaml
```
</Step>
<Step title="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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components):
```yaml values.yaml
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.<your-tunnel-domain>` and `search.<your-tunnel-domain>`. 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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation).
<Note>
If you're using the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), set `routes` to `echo: http://hello-mcp:9000` instead.
</Note>
</Step>
<Step title="Review the rendered manifests">
Render the chart and review the output according to your organization's vetting practices:
```bash
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
```
</Step>
<Step title="Install">
```bash
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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#verify-the-deployment) on the tunnel's detail page in the Console under **Manage > MCP tunnels**, or read it from the Secret:
```bash
kubectl -n mcp-tunnel get secret mcp-tunnel \
-o jsonpath='{.data.tunnel-domain}' | base64 -d
```
Re-running the setup component (during [upgrades](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#upgrades) or [token rotation](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#rotate-the-tunnel-token)) reuses the tunnel ID stored in this Secret; it never creates a second tunnel.
<Warning>
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.
</Warning>
</Step>
</Steps>
</Tab>
<Tab title="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.
<Steps>
<Step title="Get the tunnel token and domain">
[Create the tunnel](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel) and [get the tunnel token from the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details).
<Note>
Record the tunnel domain from the detail page. You'll set it as `gateway.config.tunnel_domain`.
</Note>
</Step>
<Step title="Generate a CA and server certificate">
The proxy listens on plain WebSocket, with [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) carried inside that stream using the certificate you generate here. The server certificate's SAN must include `*.<tunnel-domain>` per the [certificate requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#certificate-requirements).
```bash
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 <<EOF
subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}
authorityKeyIdentifier = keyid,issuer
extendedKeyUsage = serverAuth
EOF
# Server certificate signed by the CA
openssl req -newkey rsa:2048 -nodes \
-keyout 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
```
[Register `data/ca.crt` in the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate). Keep `data/ca.key` somewhere durable and secure; you'll need it to sign a fresh server certificate at renewal time.
</Step>
<Step title="Create the two Secrets">
The chart reads specific keys; the Secret names are configurable but the keys are not. The following namespace-creation command is a no-op if the namespace already exists (for example, from the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server) step).
```bash
kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \
--from-literal=tunnel-token='eyJ...'
kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \
--from-file=tls.crt=data/tls.crt \
--from-file=tls.key=data/tls.key
```
</Step>
<Step title="Fetch the default values">
```bash
helm show values \
oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
--version 2.0.2 > values.yaml
```
</Step>
<Step title="Configure values for manual provisioning">
Edit `values.yaml` and set the following keys:
```yaml values.yaml
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](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation).
Cut at 300 lines. The page has the rest.