Conector MCP

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.

Principais recursos

• Integração direta com a API: Conecte-se a servidores MCP sem implementar um cliente MCP
• Suporte a chamadas de ferramentas: Acesse ferramentas MCP através da API de Mensagens
• Configuração flexível de ferramentas: Habilite todas as ferramentas, crie uma lista de permissões para ferramentas específicas ou uma lista de bloqueio para ferramentas indesejadas
• Configuração por ferramenta: Configure ferramentas individuais com configurações personalizadas
• Autenticação OAuth: Suporte para tokens OAuth Bearer para servidores autenticados
• Múltiplos servidores: Conecte-se a múltiplos servidores MCP em uma única requisição

Limitações

• Do conjunto de recursos da especificação MCP, apenas chamadas de ferramentas são atualmente suportadas.
• O servidor deve estar publicamente exposto via HTTP (suporta transportes Streamable HTTP e SSE). Servidores STDIO locais não podem ser conectados diretamente.
• O conector MCP atualmente não é suportado no Amazon Bedrock e Google Vertex.

Usando o conector MCP na API de Mensagens

O conector MCP usa dois componentes:

1. Definição do Servidor MCP (array mcp_servers): Define os detalhes de conexão do servidor (URL, autenticação)
2. Conjunto de Ferramentas MCP (array tools): Configura quais ferramentas habilitar e como configurá-las

Exemplo básico

Este exemplo habilita 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"
      }
    ]
  }'

Configuração do servidor 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"
}

Descrições dos campos

Configuração do conjunto de ferramentas MCP

O MCPToolset fica no array tools e configura quais ferramentas do servidor MCP estão habilitadas e como devem ser configuradas.

Estrutura básica

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "default_config": {
    "enabled": true,
    "defer_loading": false
  },
  "configs": {
    "specific_tool_name": {
      "enabled": true,
      "defer_loading": true
    }
  }
}

Descrições dos campos

Opções de configuração de ferramentas

Cada ferramenta (seja configurada em default_config ou em configs) suporta os seguintes campos:

Mesclagem de configurações

Os valores de configuração são mesclados com esta precedência (do mais alto ao mais baixo):

1. Configurações específicas de ferramentas em configs
2. default_config no nível do conjunto
3. Padrões do sistema

Exemplo:

{
  "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)
• Todas as outras ferramentas: enabled: true (padrão do sistema), defer_loading: true (de default_config)

Padrões de configuração comuns

Habilitar todas as ferramentas com configuração padrão

O padrão mais simples - habilitar todas as ferramentas de um servidor:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}

Lista de permissões - Habilitar apenas ferramentas específicas

Defina enabled: false como padrão e, em seguida, habilite 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
    }
  }
}

Lista de bloqueio - Desabilitar ferramentas específicas

Habilite todas as ferramentas por padrão e, em seguida, desabilite explicitamente as ferramentas indesejadas:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "configs": {
    "delete_all_events": {
      "enabled": false
    },
    "share_calendar_publicly": {
      "enabled": false
    }
  }
}

Misto - Lista de permissões com configuração por ferramenta

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á habilitado com defer_loading: false
• list_events está habilitado com defer_loading: true (herdado de default_config)
• Todas as outras ferramentas estão desabilitadas

Regras de validação

A API aplica estas regras de validação:

• O servidor deve existir: O mcp_server_name em um MCPToolset deve corresponder a um servidor definido no array mcp_servers
• O servidor deve ser usado: Todo servidor MCP definido em mcp_servers deve ser referenciado por exatamente um MCPToolset
• Conjunto de ferramentas único por servidor: Cada servidor MCP só pode ser referenciado por um MCPToolset
• Nomes de ferramentas desconhecidos: Se um nome de ferramenta em configs não existir no servidor MCP, um aviso de backend é registrado, mas nenhum erro é retornado (servidores MCP podem ter disponibilidade dinâmica de ferramentas)

Tipos de conteúdo de resposta

Quando Claude usa ferramentas MCP, a resposta incluirá dois novos tipos de blocos de conteúdo:

Bloco de Uso de Ferramenta MCP

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}

Bloco de Resultado de Ferramenta MCP

{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}

Múltiplos servidores MCP

Você pode se conectar a múltiplos 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
      }
    }
  ]
}

Autenticação

Para servidores MCP que requerem autenticação OAuth, você precisará obter um token de acesso. O beta do conector MCP suporta a passagem de um parâmetro authorization_token na definição do servidor MCP. Espera-se que os consumidores da API gerenciem o fluxo OAuth e obtenham o token de acesso antes de fazer a chamada à API, bem como renovem o token conforme necessário.

Obtendo um token de acesso para testes

O inspetor MCP pode guiá-lo pelo processo de obtenção de um token de acesso para fins de teste.

1. Execute o inspetor com o seguinte comando. Você precisa ter o Node.js instalado em sua máquina.

   npx @modelcontextprotocol/inspector

2. Na barra lateral à esquerda, para "Transport type", selecione "SSE" ou "Streamable HTTP".

3. Insira a URL do servidor MCP.

4. Na área à direita, clique no botão "Open Auth Settings" após "Need to configure authentication?".

5. Clique em "Quick OAuth Flow" e autorize na tela OAuth.

6. Siga os passos na seção "OAuth Flow Progress" do inspetor e clique em "Continue" até chegar em "Authentication complete".

7. Copie o valor de access_token.

8. Cole-o no campo authorization_token na configuração do seu servidor MCP.

Usando o token de acesso

Depois de obter um token de acesso usando qualquer um dos fluxos OAuth acima, você pode usá-lo na configuração do seu 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.

Auxiliares MCP do lado do cliente (TypeScript)

Se você gerencia 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 da API Claude. Isso elimina o código de conversão manual ao usar o SDK MCP junto com o SDK Anthropic.

Instalação

Instale tanto o SDK Anthropic quanto o SDK MCP:

npm install @anthropic-ai/sdk @modelcontextprotocol/sdk

Auxiliares disponíveis

Importe os auxiliares do namespace beta:

import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";

Usar ferramentas MCP

Converta ferramentas MCP para uso com o executor de ferramentas do SDK, que lida com 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-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

Usar prompts MCP

Converta mensagens de prompt MCP para o formato de mensagem da 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-6",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

Usar recursos MCP

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-6",
  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) });

Tratamento de erros

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.

Retenção de dados

O Conector MCP não é coberto por acordos ZDR. Os dados trocados com servidores MCP, incluindo definições de ferramentas e resultados de execução, são retidos de acordo com a política padrão de retenção de dados da Anthropic.

Para elegibilidade ZDR em todos os recursos, consulte API e Retenção de Dados.

Guia de migração

Se você estiver usando o cabeçalho beta obsoleto mcp-client-2025-04-04, siga este guia para migrar para a nova versão.

Principais mudanças

1. Novo cabeçalho beta: Mude de mcp-client-2025-04-04 para mcp-client-2025-11-20
2. Configuração de ferramentas movida: A configuração de ferramentas agora fica no array tools como objetos MCPToolset, não na definição do servidor MCP
3. Configuração mais flexível: O novo padrão suporta lista de permissões, lista de bloqueio e configuração por ferramenta

Etapas de migração

Antes (obsoleto):

{
  "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ões comuns de migração

Versão obsoleta: mcp-client-2025-04-04

A versão anterior do conector MCP incluía 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"]
      }
    }
  ]
}

Descrições de campos obsoletos