Conector MCP

O recurso de conector do "Model Context Protocol", ou MCP, do Claude permite que você se conecte a servidores MCP remotos diretamente da API Messages 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 por meio da API Messages
• Configuração flexível de ferramentas: Habilite todas as ferramentas, crie uma lista de permissão de ferramentas específicas ou uma lista de bloqueio de ferramentas indesejadas
• Configuração por ferramenta: Configure ferramentas individuais com definições personalizadas
• Autenticação OAuth: Suporte a 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

Depois que um servidor MCP é 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 há no meu banco de dados Projects?" aciona a ferramenta.

Você pode orientar a prontidão com que o Claude chama ferramentas MCP por meio 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 suportadas atualmente.
• O servidor deve estar exposto publicamente via HTTP (suporta os transportes Streamable HTTP e SSE). Servidores STDIO locais não podem ser conectados diretamente.

Usando o conector MCP na API Messages

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

Com o cabeçalho beta mcp-client-2026-09-15, um MCPToolset também aceita tools, uma cópia fixada da lista de ferramentas do servidor. Consulte Fixar a lista de ferramentas de um servidor MCP.

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çã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 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: 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 as ferramentas indesejadas. Colocar ferramentas de escrita ou destrutivas em uma lista de bloqueio é recomendado ao criar assistentes somente leitura, ou quando você deseja uma etapa de confirmação humana antes de alterações 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 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: Todo 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 é registrado no backend, mas nenhum erro é retornado (servidores MCP podem ter disponibilidade dinâmica de ferramentas)

Tipos de conteúdo da resposta

Quando o Claude usa ferramentas MCP, a resposta inclui 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"
    }
  ]
}

Fixar a lista de ferramentas de um servidor MCP (beta)

Um servidor MCP pode alterar suas ferramentas a qualquer momento. O cabeçalho beta mcp-client-2026-09-15 registra a lista de ferramentas que cada servidor retorna e permite que você a fixe, para que um servidor que altere suas ferramentas não mude o que o Claude vê no meio de uma conversa. Ele inclui tudo o que mcp-client-2025-11-20 inclui, então envie-o no lugar desse cabeçalho. Ele está disponível na Claude API.

Quando a API solicita a um servidor MCP suas ferramentas enquanto produz uma resposta, a resposta começa com um bloco mcp_tool_listing para esse servidor, um bloco para cada servidor consultado:

{
  "type": "mcp_tool_listing",
  "mcp_server_name": "example-mcp",
  "tools": [
    {
      "name": "echo",
      "description": "Returns the text it receives.",
      "input_schema": {
        "type": "object",
        "properties": { "text": { "type": "string" } },
        "required": ["text"]
      }
    }
  ]
}

Se o seu código lê content[0], ignore esses blocos. Envie a mensagem do assistente de volta sem alterações, incluindo os blocos mcp_tool_listing, e continue enviando mcp-client-2026-09-15 em toda requisição que contenha um deles. As requisições posteriores então usam a lista registrada para esse servidor em vez de consultá-lo novamente.

Para fixar uma lista você mesmo, copie o tools de um bloco para o campo tools do MCPToolset desse servidor. A API então não solicita ao servidor suas ferramentas, e as ferramentas do toolset são exatamente essas entradas, com default_config e configs aplicados:

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "tools": [
    {
      "name": "echo",
      "description": "Returns the text it receives.",
      "input_schema": {
        "type": "object",
        "properties": { "text": { "type": "string" } },
        "required": ["text"]
      }
    }
  ]
}

Cada entrada em tools contém o name da ferramenta conforme o servidor a lista (sem o nome do servidor), sua description e seu input_schema.

O exemplo a seguir envia uma requisição com um toolset não fixado, copia a lista retornada para o campo tools do toolset e envia a requisição novamente. A segunda resposta não tem bloco mcp_tool_listing, porque a API não consulta o servidor:

from anthropic.types.beta import (
    BetaMessageParam,
    BetaRequestMCPServerURLDefinitionParam,
)

client = anthropic.Anthropic()

mcp_servers: list[BetaRequestMCPServerURLDefinitionParam] = [
    {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN",
    },
]
messages: list[BetaMessageParam] = [
    {"role": "user", "content": "What tools do you have available?"},
]

# Primeira requisição: o toolset não está fixado, então a API pede ao servidor
# suas ferramentas e a resposta começa com um bloco mcp_tool_listing.
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    betas=["mcp-client-2026-09-15"],
    mcp_servers=mcp_servers,
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    messages=messages,
)

listing = next(block for block in first.content if block.type == "mcp_tool_listing")
print([tool.name for tool in listing.tools])

# Fixe a lista: copie as ferramentas do bloco para o toolset. A API usa
# exatamente essas entradas e não consulta o servidor novamente.
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    betas=["mcp-client-2026-09-15"],
    mcp_servers=mcp_servers,
    tools=[
        {
            "type": "mcp_toolset",
            "mcp_server_name": "example-mcp",
            "tools": [
                {
                    "name": tool.name,
                    "description": tool.description,
                    "input_schema": tool.input_schema,
                }
                for tool in listing.tools
            ],
        },
    ],
    messages=messages,
)

# Com um toolset fixado, a resposta não tem bloco mcp_tool_listing.
print([block.type for block in second.content])

Se você também enviar o cabeçalho beta inline-tools-2026-09-15, poderá adicionar um servidor MCP no meio de uma conversa. Consulte Adicionar um servidor MCP no meio da conversa.

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-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, 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 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, além de atualizar 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 na 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 em 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 sobre o fluxo OAuth, consulte a seção Authorization 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 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 o SDK da Anthropic e o SDK MCP:

pip install "anthropic[mcp]"

Helpers disponíveis

Importe os helpers 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 helpers 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-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-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-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.files.upload(
    file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)

Tratamento de erros

As funções de conversão falham com UnsupportedMCPValueError se um valor MCP não for suportado pela Claude API (lançado como exceção ou, em Go, retornado como erro). Isso pode acontecer com tipos de conteúdo, tipos MIME ou links de recursos não suportados (resolva os links de recursos com seu cliente MCP antes de converter).

Requisições em lote

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

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

Guia de migração

Se você está 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 listas de permissão, listas de bloqueio e configuração por ferramenta

Etapas de migração

Antes (descontinuado):

{
  "model": "claude-opus-5-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-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

Compatibility