Conector MCP

O recurso de conector do Model Context Protocol (MCP) do Claude permite que você se conecte a servidores MCP remotos diretamente 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 (allowlist) de ferramentas específicas ou uma lista de bloqueio (denylist) de 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 solicitação



Quando Claude usa ferramentas MCP

Uma vez que um servidor MCP está conectado, 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 conectado).

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 conectado é respondido diretamente; perguntar "o que há no meu banco de dados de Projetos?" aciona a ferramenta.

Você pode direcionar a prontidão com que Claude chama ferramentas MCP através do seu prompt do sistema. Consulte Quando 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 publicamente exposto através de HTTP (suporta os transportes Streamable HTTP e SSE). Servidores STDIO locais não podem ser conectados diretamente.
• O conector MCP está disponível na Claude API, na Claude Platform na AWS e no Microsoft Foundry. No Microsoft Foundry, o conector MCP requer uma implantação Hosted on Anthropic. Ele não está atualmente 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 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 a configuração padrão:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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 conjunto de ferramentas MCP

O MCPToolset fica no array tools e configura quais ferramentas do servidor MCP estão habilitadas e como elas 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 a Ferramenta de busca de ferramentas.



Mesclagem de configurações

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

1. Configurações específicas da 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 a 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 (allowlist): 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 (denylist): desabilitar ferramentas específicas

Habilite todas as ferramentas por padrão e, em seguida, desabilite explicitamente as ferramentas indesejadas. Colocar ferramentas de escrita ou destrutivas na lista de bloqueio é recomendado ao construir 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 a 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 impõe 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
• 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 da resposta

Quando 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-5",
  "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, 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 Ferramenta de busca de ferramentas para que apenas as 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 a passagem de 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 do OAuth.

6. Siga as etapas na seção "OAuth Flow Progress" do inspector e clique em "Continue" até chegar a "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.



Auxiliares 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 Claude API. Isso elimina código de conversão manual ao usar um SDK MCP para sua linguagem (por exemplo, o TypeScript MCP SDK) junto com o SDK da Anthropic.



Instalação

Instale tanto o SDK da Anthropic quanto o SDK MCP:

pip install "anthropic[mcp]"



Auxiliares disponíveis

Importe os auxiliares para sua linguagem:

from anthropic.lib.tools.mcp import (
    async_mcp_tool,
    mcp_message,
    mcp_resource_to_content,
    mcp_resource_to_file,
)

Os nomes dos auxiliares e as assinaturas exatas seguem as convenções de cada linguagem; esta tabela mostra as formas em TypeScript:



Usar ferramentas MCP

Converta ferramentas MCP para uso com o tool runner do SDK, que lida com a execução de ferramentas automaticamente:

from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

client = AsyncAnthropic()


async def main() -> None:
    # Conectar a um servidor MCP
    server_params = StdioServerParameters(command="mcp-server")
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as mcp_client:
            await mcp_client.initialize()

            # Listar as ferramentas e convertê-las para a API do Claude
            tools_result = await mcp_client.list_tools()
            runner = client.beta.messages.tool_runner(
                model="claude-opus-5",
                max_tokens=1024,
                messages=[
                    {"role": "user", "content": "What tools do you have available?"},
                ],
                tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
            )

            final_message = await runner.until_done()
            print(final_message)


asyncio.run(main())



Usar prompts MCP

Converta mensagens de prompt MCP para o formato de mensagem da Claude API:

from anthropic.lib.tools.mcp import mcp_message

prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[mcp_message(message) for message in prompt.messages],
)

print(response)



Usar recursos MCP

Converta recursos MCP em blocos de conteúdo para incluir em mensagens, ou em objetos de arquivo para upload:

from anthropic.lib.tools.mcp import (
    mcp_resource_to_content,
    mcp_resource_to_file,
)

# Como um bloco de conteúdo em uma mensagem
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                mcp_resource_to_content(resource),
                {"type": "text", "text": "Summarize this document"},
            ],
        }
    ],
)
print(response)

# Como um upload de arquivo
file_resource = await mcp_client.read_resource(
    uri="file:///path/to/data.json",
)
uploaded = await client.beta.files.upload(
    file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)



Tratamento de erros

As funções de conversão lançam UnsupportedMCPValueError se um valor MCP não for suportado pela Claude API (em Go, os auxiliares retornam um UnsupportedValueError; em Java e C#, eles lançam AnthropicInvalidDataException). Isso pode acontecer com tipos de conteúdo não suportados, tipos MIME ou links de recursos (resolva links de recursos com seu cliente MCP antes de converter).



Solicitações em lote

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



Retenção de dados

O conector MCP não é coberto por acordos de 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, consulte 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-5",
  "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-5",
  "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 descontinuada: 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 dos campos descontinuados