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.

Recursos principais

• Integração direta de 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: Ative todas as ferramentas, crie uma lista de permissão de ferramentas específicas ou crie uma lista de bloqueio de ferramentas indesejadas
• Configuração por ferramenta: Configure ferramentas individuais com configurações personalizadas
• Autenticação OAuth: Suporte para tokens Bearer OAuth para servidores autenticados
• Múltiplos servidores: Conecte-se a vários 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 ser exposto publicamente através de HTTP (suporta transportes HTTP Streamable e SSE). Servidores STDIO locais não podem ser conectados diretamente.
• O conector MCP não é atualmente 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 detalhes de conexão do servidor (URL, autenticação)
2. Conjunto de Ferramentas MCP (array tools): Configura quais ferramentas ativar e como configurá-las

Exemplo básico

Este exemplo ativa todas as ferramentas de um servidor MCP com configuração padrão:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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)

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 de campos

Configuração do conjunto de ferramentas MCP

O MCPToolset fica no array tools e configura quais ferramentas do servidor MCP estão ativadas 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 de campos

Opções de configuração de ferramentas

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

Para o diretório completo de ferramentas fornecidas pela Anthropic e propriedades opcionais como defer_loading, veja a referência de ferramentas. Para buscar em grandes conjuntos de ferramentas, veja Ferramenta de busca de ferramentas.

Mesclagem de configuração

Os valores de configuração são mesclados com esta precedência (maior para menor):

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

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

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

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

Lista de permissão - Ativar apenas ferramentas específicas

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
    }
  }
}

Lista de bloqueio - Desativar ferramentas específicas

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
    }
  }
}

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

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

Regras de validação

A API impõe estas regras de validação:

• Servidor deve existir: O mcp_server_name em um MCPToolset deve corresponder a um servidor definido no array mcp_servers
• Servidor deve ser usado: Cada servidor MCP definido em mcp_servers deve ser referenciado por exatamente um MCPToolset
• Conjunto de ferramentas único por servidor: Cada servidor MCP pode ser referenciado apenas 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 de ferramentas dinâmica)

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": "Hello"
    }
  ]
}

Múltiplos servidores MCP

Você pode se conectar 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-7",
  "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 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.

Obtendo um token de acesso para testes

O inspetor MCP pode guiá-lo através do processo de obtenção de 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 as etapas na seção "Progresso do Fluxo OAuth" do inspetor e clique em "Continuar" até atingir "Autenticação concluída".

7. Copie o valor de access_token.

8. Cole-o no campo authorization_token em sua configuração de 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 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.

Auxiliares MCP do lado do cliente (TypeScript)

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.

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 manipula a execução de ferramentas automaticamente:

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 em 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-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 arranjos 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 de ZDR em todos os recursos, veja API e retenção de dados.

Guia de migração

Se você estiver usando o cabeçalho beta descontinuado 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ão, lista de bloqueio e configuração por ferramenta

Etapas de migração

Antes (descontinuado):

{
  "model": "claude-opus-4-7",
  "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-7",
  "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 de migração comuns

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

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"]
      }
    }
  ]
}

Descrições de campos descontinuados