O recurso de conector do Protocolo de Contexto de Modelo (MCP) do Claude permite conectar-se a servidores MCP remotos diretamente da API de Mensagens sem um cliente MCP separado.

Este recurso requer o cabeçalho beta: "anthropic-beta": "mcp-client-2025-04-04"

Recursos principais

  • Integração direta da 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
  • Autenticação OAuth: Suporte para tokens Bearer OAuth para servidores autenticados
  • Múltiplos servidores: Conecte-se a múltiplos servidores MCP em uma única solicitaçã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 através de HTTP (suporta transportes HTTP Streamable 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

Para conectar-se a um servidor MCP remoto, inclua o parâmetro mcp_servers em sua solicitação da API de Mensagens:

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-04-04" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1000,
    "messages": [{"role": "user", "content": "Que ferramentas você tem disponíveis?"}],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
      }
    ]
  }'

Configuração do servidor MCP

Cada servidor MCP no array mcp_servers suporta a seguinte configuração:

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "tool_configuration": {
    "enabled": true,
    "allowed_tools": ["example_tool_1", "example_tool_2"]
  },
  "authorization_token": "YOUR_TOKEN"
}

Descrições dos campos

PropriedadeTipoObrigatórioDescrição
typestringSimAtualmente apenas “url” é suportado
urlstringSimA URL do servidor MCP. Deve começar com https://
namestringSimUm identificador único para este servidor MCP. Será usado em blocos mcp_tool_call para identificar o servidor e desambiguar ferramentas para o modelo.
tool_configurationobjectNãoConfigurar uso de ferramentas
tool_configuration.enabledbooleanNãoSe deve habilitar ferramentas deste servidor (padrão: true)
tool_configuration.allowed_toolsarrayNãoLista para restringir as ferramentas a permitir (por padrão, todas as ferramentas são permitidas)
authorization_tokenstringNãoToken de autorização OAuth se requerido pelo servidor MCP. Veja especificação MCP.

Tipos de conteúdo de resposta

Quando Claude usa ferramentas MCP, a resposta incluirá dois novos tipos de bloco 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": "Olá"
    }
  ]
}

Múltiplos servidores MCP

Você pode conectar-se a múltiplos servidores MCP incluindo múltiplos objetos no array mcp_servers:

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use ferramentas de mcp-server-1 e mcp-server-2 para completar esta tarefa"
    }
  ],
  "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"
    }
  ]
}

Autenticação

Para servidores MCP que requerem 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. Espera-se que os consumidores da API lidem com o fluxo OAuth e obtenham o token de acesso antes de fazer a chamada da API, bem como atualizem o token conforme necessário.

Obtendo um token de acesso para testes

O inspetor MCP pode guiá-lo através do processo de obter um token de acesso para fins de teste.

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

    npx @modelcontextprotocol/inspector
    
  2. Na barra lateral à esquerda, para “Tipo de transporte”, selecione “SSE” ou “Streamable HTTP”.

  3. Digite a URL do servidor MCP.

  4. Na área direita, clique no botão “Abrir Configurações de Autenticação” após “Precisa configurar autenticação?”.

  5. Clique em “Fluxo OAuth Rápido” e autorize na tela OAuth.

  6. Siga os passos na seção “Progresso do Fluxo OAuth” do inspetor e clique em “Continuar” até chegar em “Autenticação completa”.

  7. Copie o valor access_token.

  8. Cole-o no campo authorization_token em sua configuração do servidor MCP.

Usando o token de acesso

Uma vez que você tenha obtido um token de acesso usando qualquer um dos fluxos OAuth acima, você pode usá-lo em sua configuração do 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.