Conector MCP

O recurso de conector do "Model Context Protocol", ou MCP, do Claude permite que você se conecte a servidores MCP remotos diretamente a partir da Messages API 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 Messages API
• Configuração flexível de ferramentas: Habilite todas as ferramentas, crie uma lista de permissão com ferramentas específicas ou uma lista de bloqueio com 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



Quando o Claude usa ferramentas MCP

Uma vez que um servidor MCP está conectado, o Claude chama suas ferramentas quando a solicitação do usuário corresponde à capacidade descrita de uma ferramenta, seja explicitamente ("pesquise no Jira por bugs abertos") ou implicitamente ("o que está bloqueando o lançamento?" com um servidor Jira anexado).

O Claude não chama uma ferramenta MCP para perguntas de conhecimento geral sobre um serviço conectado. Perguntar "como funcionam os bancos de dados do Notion?" com um servidor Notion anexado é respondido diretamente; perguntar "o que está no meu banco de dados de Projetos?" aciona a ferramenta.

Você pode orientar a prontidão com que o Claude chama ferramentas MCP através do seu prompt do sistema. Consulte Quando o Claude usa ferramentas para orientações gerais e exemplos de formulações.



Limitações

• Do conjunto de recursos da especificação MCP, apenas chamadas de ferramentas são atualmente suportadas.
• O servidor deve estar exposto publicamente através de HTTP (suporta tanto transportes Streamable HTTP quanto SSE). Servidores STDIO locais não podem ser conectados diretamente.
• O conector MCP está disponível na API do Claude, na Claude Platform on AWS e no Microsoft Foundry. No Microsoft Foundry, o conector MCP requer uma implantação Hosted on Anthropic. Atualmente não está disponível no Amazon Bedrock ou no Google Cloud.



Usando o conector MCP na Messages API

O conector MCP usa dois componentes:

1. Definição de Servidor MCP (array mcp_servers): Define os detalhes de conexão do servidor (URL, autenticação)
2. MCP Toolset (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:

client = anthropic.Anthropic()

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



Configuração do MCP toolset

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:

Para o diretório completo de ferramentas fornecidas pela Anthropic e propriedades opcionais como defer_loading, consulte a Referência de ferramentas. Para pesquisar em grandes conjuntos de ferramentas, consulte Tool search tool.



Mesclagem de configuração

Os valores de configuração são mesclados com esta precedência (da mais alta para a mais baixa):

1. Configurações específicas de ferramenta 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 comuns de configuração



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ão: 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 ferramentas indesejadas. Bloquear ferramentas de escrita ou destrutivas é recomendado ao criar assistentes somente leitura, ou quando você deseja uma etapa de confirmação humana antes de mudanças de estado:

{
  "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á habilitada com defer_loading: false
• list_events está habilitada 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: Cada servidor MCP definido em mcp_servers deve ser referenciado por exatamente um MCPToolset
• Toolset ú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 o Claude usa ferramentas MCP, a resposta inclui 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-8",
  "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
      }
    }
  ]
}

Com muitas ferramentas disponíveis, o Claude seleciona com base nos nomes e descrições das ferramentas. Descrições de ferramentas claras e específicas melhoram a precisão da seleção. Para grandes conjuntos de ferramentas (dezenas de ferramentas em vários servidores), considere habilitar defer_loading com a Tool search tool para que apenas ferramentas relevantes sejam apresentadas por consulta.



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



Obtendo um token de acesso para testes

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

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

   npx @modelcontextprotocol/inspector

   

2. Na barra lateral à esquerda, em "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 as etapas na seção "OAuth Flow Progress" do inspector 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 anteriores, 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.



Helpers MCP do lado do cliente

Se você gerencia sua própria conexão de cliente MCP (por exemplo, com servidores stdio locais, prompts MCP ou recursos MCP), os SDKs fornecem funções auxiliares que convertem entre tipos MCP e tipos da API do Claude. Isso elimina código de conversão manual ao usar um SDK MCP (como o TypeScript MCP SDK) junto com o SDK da Anthropic.



Instalação

Instale tanto o SDK da Anthropic quanto o SDK MCP:

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



Helpers disponíveis

Importe os helpers 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 tool runner do SDK, que lida com 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();

// Conectar a um servidor MCP
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// Listar ferramentas e convertê-las para a API do Claude
const { tools } = await mcpClient.listTools();
const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

console.log(finalMessage);



Usar prompts MCP

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

console.log(response);



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";

// Como um bloco de conteúdo em uma mensagem
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// Como um upload de arquivo
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 do Claude. Isso pode acontecer com tipos de conteúdo não suportados, tipos MIME ou links de recursos não HTTP.



Requisições em lote

Você pode incluir mcp_servers em requisições da Message Batches API. Chamadas de ferramentas MCP através da Batches API têm o mesmo preço que aquelas em requisições regulares da Messages API.



Retenção de dados

O conector MCP não é coberto por acordos ZDR. 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ê está 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ão, lista de bloqueio e configuração por ferramenta



Etapas de migração

Antes (obsoleto):

{
  "model": "claude-opus-4-8",
  "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-8",
  "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