O recurso de conector Model Context Protocol (MCP) do Claude permite que você se conecte a servidores MCP remotos diretamente da API de Mensagens sem um cliente MCP separado.
Versão atual: Este recurso requer o cabeçalho beta: "anthropic-beta": "mcp-client-2025-11-20"
A versão anterior (mcp-client-2025-04-04) está descontinuada. Consulte a documentação da versão descontinuada abaixo.
O conector MCP usa dois componentes:
mcp_servers): Define detalhes de conexão do servidor (URL, autenticação)tools): Configura quais ferramentas ativar e como configurá-lasEste exemplo ativa todas as ferramentas de um servidor MCP com configuração padrão:
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-4-6",
"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"
}
]
}'Cada servidor MCP no array mcp_servers define os detalhes de conexão:
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}| Propriedade | Tipo | Obrigatório | Descrição |
|---|---|---|---|
type | string | Sim | Atualmente apenas "url" é suportado |
url | string | Sim | A URL do servidor MCP. Deve começar com https:// |
name | string | Sim | Um identificador único para este servidor MCP. Deve ser referenciado por exatamente um MCPToolset no array tools. |
authorization_token | string | Não | Token de autorização OAuth se exigido pelo servidor MCP. Consulte a especificação MCP. |
O MCPToolset reside no array tools e configura quais ferramentas do servidor MCP estão ativadas e como devem ser configuradas.
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"default_config": {
"enabled": true,
"defer_loading": false
},
"configs": {
"specific_tool_name": {
"enabled": true,
"defer_loading": true
}
}
}| Propriedade | Tipo | Obrigatório | Descrição |
|---|---|---|---|
type | string | Sim | Deve ser "mcp_toolset" |
mcp_server_name | string | Sim | Deve corresponder a um nome de servidor definido no array mcp_servers |
default_config | object | Não | Configuração padrão aplicada a todas as ferramentas neste conjunto. Configurações de ferramentas individuais em configs substituirão esses padrões. |
configs | object | Não | Substituições de configuração por ferramenta. As chaves são nomes de ferramentas, os valores são objetos de configuração. |
cache_control | object | Não | Configuração de ponto de interrupção de cache para este conjunto de ferramentas |
Cada ferramenta (seja configurada em default_config ou em configs) suporta os seguintes campos:
| Propriedade | Tipo | Padrão | Descrição |
|---|---|---|---|
enabled | boolean | true | Se esta ferramenta está ativada |
defer_loading | boolean | false | Se verdadeiro, a descrição da ferramenta não é enviada ao modelo inicialmente. Usado com Ferramenta de Busca de Ferramentas. |
Os valores de configuração se mesclam com esta precedência (maior para menor):
configsdefault_config no nível do conjuntoExemplo:
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": false
}
}
}Resulta em:
search_events: enabled: false (de configs), defer_loading: true (de default_config)enabled: true (padrão do sistema), defer_loading: true (de default_config)O padrão mais simples - ativar todas as ferramentas de um servidor:
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
}Defina enabled: false como padrão e, em seguida, ative explicitamente ferramentas específicas:
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false
},
"configs": {
"search_events": {
"enabled": true
},
"create_event": {
"enabled": true
}
}
}Ative todas as ferramentas por padrão e, em seguida, desative explicitamente ferramentas indesejadas:
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"configs": {
"delete_all_events": {
"enabled": false
},
"share_calendar_publicly": {
"enabled": false
}
}
}Combine lista de permissões com configuração personalizada para cada ferramenta:
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false,
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": true,
"defer_loading": false
},
"list_events": {
"enabled": true
}
}
}Neste exemplo:
search_events está ativado com defer_loading: falselist_events está ativado com defer_loading: true (herdado de default_config)A API impõe estas regras de validação:
mcp_server_name em um MCPToolset deve corresponder a um servidor definido no array mcp_serversmcp_servers deve ser referenciado por exatamente um MCPToolsetconfigs não existir no servidor MCP, um aviso de backend é registrado, mas nenhum erro é retornado (servidores MCP podem ter disponibilidade dinâmica de ferramentas)Quando Claude usa ferramentas MCP, a resposta incluirá dois novos tipos de bloco de conteúdo:
{
"type": "mcp_tool_use",
"id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"name": "echo",
"server_name": "example-mcp",
"input": { "param1": "value1", "param2": "value2" }
}{
"type": "mcp_tool_result",
"tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"is_error": false,
"content": [
{
"type": "text",
"text": "Hello"
}
]
}Você pode conectar-se a vários servidores MCP incluindo múltiplas definições de servidor em mcp_servers e um MCPToolset correspondente para cada um no array tools:
{
"model": "claude-opus-4-6",
"max_tokens": 1000,
"messages": [
{
"role": "user",
"content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
}
],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example1.com/sse",
"name": "mcp-server-1",
"authorization_token": "TOKEN1"
},
{
"type": "url",
"url": "https://mcp.example2.com/sse",
"name": "mcp-server-2",
"authorization_token": "TOKEN2"
}
],
"tools": [
{
"type": "mcp_toolset",
"mcp_server_name": "mcp-server-1"
},
{
"type": "mcp_toolset",
"mcp_server_name": "mcp-server-2",
"default_config": {
"defer_loading": true
}
}
]
}Para servidores MCP que exigem autenticação OAuth, você precisará obter um token de acesso. O beta do conector MCP suporta passar um parâmetro authorization_token na definição do servidor MCP.
Os consumidores de API devem lidar com o fluxo OAuth e obter o token de acesso antes de fazer a chamada de API, bem como atualizar o token conforme necessário.
O inspetor MCP pode guiá-lo através do processo de obtenção de um token de acesso para fins de teste.
Execute o inspetor com o seguinte comando. Você precisa ter Node.js instalado em sua máquina.
npx @modelcontextprotocol/inspectorNa barra lateral à esquerda, para "Tipo de transporte", selecione "SSE" ou "HTTP Streamable".
Digite a URL do servidor MCP.
Na área à direita, clique no botão "Abrir Configurações de Autenticação" após "Precisa configurar autenticação?".
Clique em "Fluxo OAuth Rápido" e autorize na tela OAuth.
Siga as etapas na seção "Progresso do Fluxo OAuth" do inspetor e clique em "Continuar" até atingir "Autenticação concluída".
Copie o valor de access_token.
Cole-o no campo authorization_token em sua configuração de servidor MCP.
Depois de obter um token de acesso usando qualquer um dos fluxos OAuth acima, você pode usá-lo em sua configuração de servidor MCP:
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "authenticated-server",
"authorization_token": "YOUR_ACCESS_TOKEN_HERE"
}
]
}Para explicações detalhadas do fluxo OAuth, consulte a seção de Autorização na especificação MCP.
Se você gerenciar sua própria conexão de cliente MCP (por exemplo, com servidores stdio locais, prompts MCP ou recursos MCP), o SDK TypeScript fornece funções auxiliares que convertem entre tipos MCP e tipos de API Claude. Isso elimina código de conversão manual ao usar o SDK MCP junto com o SDK Anthropic.
Esses auxiliares estão atualmente disponíveis apenas no SDK TypeScript.
Use o parâmetro de API mcp_servers quando você tiver servidores remotos acessíveis via URL e precisar apenas de suporte a ferramentas. Se você estiver usando o Agent SDK, as conexões MCP são gerenciadas automaticamente. Use os auxiliares do lado do cliente quando precisar de servidores locais, prompts, recursos ou mais controle sobre a conexão com o SDK base.
Instale o SDK Anthropic e o SDK MCP:
npm install @anthropic-ai/sdk @modelcontextprotocol/sdkImporte os auxiliares do namespace beta:
import {
mcpTools,
mcpMessages,
mcpResourceToContent,
mcpResourceToFile,
} from '@anthropic-ai/sdk/helpers/beta/mcp';| Auxiliar | Descrição |
|---|---|
mcpTools(tools, mcpClient) | Converte ferramentas MCP para ferramentas de API Claude para uso com client.beta.messages.toolRunner() |
mcpMessages(messages) | Converte mensagens de prompt MCP para formato de mensagem de API Claude |
mcpResourceToContent(resource) | Converte um recurso MCP para um bloco de conteúdo de API Claude |
mcpResourceToFile(resource) | Converte um recurso MCP para um objeto de arquivo para upload |
Converta ferramentas MCP para uso com o executador de ferramentas do SDK, que manipula a execução de ferramentas automaticamente:
import Anthropic from '@anthropic-ai/sdk';
import { mcpTools } from '@anthropic-ai/sdk/helpers/beta/mcp';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
const anthropic = new Anthropic();
// Connect to an MCP server
const transport = new StdioClientTransport({ command: 'mcp-server', args: [] });
const mcpClient = new Client({ name: 'my-client', version: '1.0.0' });
await mcpClient.connect(transport);
// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
model: 'claude-sonnet-4-5',
max_tokens: 1024,
messages: [{ role: 'user', content: 'What tools do you have available?' }],
tools: mcpTools(tools, mcpClient),
});Converta mensagens de prompt MCP para formato de mensagem de API Claude:
import { mcpMessages } from '@anthropic-ai/sdk/helpers/beta/mcp';
const { messages } = await mcpClient.getPrompt({ name: 'my-prompt' });
const response = await anthropic.beta.messages.create({
model: 'claude-sonnet-4-5',
max_tokens: 1024,
messages: mcpMessages(messages),
});Converta recursos MCP em blocos de conteúdo para incluir em mensagens ou em objetos de arquivo para upload:
import { mcpResourceToContent, mcpResourceToFile } from '@anthropic-ai/sdk/helpers/beta/mcp';
// As a content block in a message
const resource = await mcpClient.readResource({ uri: 'file:///path/to/doc.txt' });
await anthropic.beta.messages.create({
model: 'claude-sonnet-4-5',
max_tokens: 1024,
messages: [
{
role: 'user',
content: [
mcpResourceToContent(resource),
{ type: 'text', text: 'Summarize this document' },
],
},
],
});
// As a file upload
const fileResource = await mcpClient.readResource({ uri: 'file:///path/to/data.json' });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });As funções de conversão lançam UnsupportedMCPValueError se um valor MCP não for suportado pela API Claude. Isso pode acontecer com tipos de conteúdo não suportados, tipos MIME ou links de recursos não-HTTP.
Se você estiver usando o cabeçalho beta descontinuado mcp-client-2025-04-04, siga este guia para migrar para a nova versão.
mcp-client-2025-04-04 para mcp-client-2025-11-20tools como objetos MCPToolset, não na definição do servidor MCPAntes (descontinuado):
{
"model": "claude-opus-4-6",
"max_tokens": 1000,
"messages": [...],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example.com/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["tool1", "tool2"]
}
}
]
}Depois (atual):
{
"model": "claude-opus-4-6",
"max_tokens": 1000,
"messages": [...],
"mcp_servers": [
{
"type": "url",
"url": "https://mcp.example.com/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
],
"tools": [
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"default_config": {
"enabled": false
},
"configs": {
"tool1": {
"enabled": true
},
"tool2": {
"enabled": true
}
}
}
]
}| Padrão antigo | Novo padrão |
|---|---|
Sem tool_configuration (todas as ferramentas ativadas) | MCPToolset sem default_config ou configs |
tool_configuration.enabled: false | MCPToolset com default_config.enabled: false |
tool_configuration.allowed_tools: [...] | MCPToolset com default_config.enabled: false e ferramentas específicas ativadas em configs |
Esta versão está descontinuada. Por favor, migre para mcp-client-2025-11-20 usando o guia de migração acima.
A versão anterior do conector MCP incluía configuração de ferramentas diretamente na definição do servidor MCP:
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
"tool_configuration": {
"enabled": true,
"allowed_tools": ["example_tool_1", "example_tool_2"]
}
}
]
}| Propriedade | Tipo | Descrição |
|---|---|---|
tool_configuration | object | Descontinuado: Use MCPToolset no array tools em vez disso |
tool_configuration.enabled | boolean | Descontinuado: Use default_config.enabled em MCPToolset |
tool_configuration.allowed_tools | array | Descontinuado: Use padrão de lista de permissões com configs em MCPToolset |
Was this page helpful?