Conector MCP

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.

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 tanto transportes HTTP Streamable quanto 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-5",
    "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"
      }
    ]
  }'

import { Anthropic } from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

const response = await anthropic.beta.messages.create({
  model: "claude-sonnet-4-5",
  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",
    },
  ],
  betas: ["mcp-client-2025-04-04"],
});

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1000,
    messages=[{
        "role": "user",
        "content": "Que ferramentas você tem disponíveis?"
    }],
    mcp_servers=[{
        "type": "url",
        "url": "https://mcp.example.com/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
    }],
    betas=["mcp-client-2025-04-04"]
)

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

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": "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-5",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use ferramentas de ambos 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 atualizar 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 "HTTP Streamable".

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.