Conectando o Claude Agent SDK a Servidores MCP
O Model Context Protocol (MCP) é uma maneira padrão para um agente chamar ferramentas que residem fora do SDK em si, em um processo local ou em um servidor remoto.
Busque em todas as páginas da documentação
O Model Context Protocol (MCP) é uma maneira padrão para um agente chamar ferramentas que residem fora do SDK em si, em um processo local ou em um servidor remoto.
O Claude Agent SDK possui suporte de primeira classe para clientes MCP: você registra um servidor, stdio para um processo local ou HTTP para um remoto, e suas ferramentas se tornam chamáveis pelo loop de uso de ferramentas da mesma forma que as ferramentas embutidas.
Ferramentas embutidas cobrem edição de arquivos, bash e web; MCP é como você estende o loop para qualquer outra coisa, um banco de dados, uma API interna, um sistema de tickets, um produto SaaS de terceiros.
Um servidor MCP stdio roda como um subprocesso na mesma máquina do seu agente e se comunica via entrada/saída padrão.
Um servidor MCP HTTP roda remotamente e se comunica via HTTP, útil quando a ferramenta reside em infraestrutura que você não controla diretamente ou deseja compartilhar entre múltiplos agentes.
Esta página cobre o registro de ambos os tipos de servidor e como suas ferramentas interagem com o resto do loop após a conexão.
Cartão de receita de referência rápida - pronto para copiar e colar.
from claude_agent_sdk import query, AgentOptions, McpServerConfig
options = AgentOptions(
allowed_tools=["file_edit"],
mcp_servers=[
McpServerConfig(
name="internal-search",
transport="stdio",
command=["python", "-m", "internal_search_mcp"],
),
McpServerConfig(
name="ticketing",
transport="http",
url="https://mcp.internal.example.com/ticketing",
),
],
)
async for message in query(
prompt="Encontre incidentes passados relacionados e abra um ticket resumindo este bug.",
options=options,
):
print(message)Quando usar isso:
import asyncio
from claude_agent_sdk import query, AgentOptions, McpServerConfig
async def triage_incident(incident_description: str) -> None:
options = AgentOptions(
allowed_tools=["file_edit"],
mcp_servers=[
McpServerConfig(
name="logs",
transport="stdio",
command=["node", "logs-mcp-server.js"],
# servidores stdio não herdam acesso especial à rede por padrão;
# eles apenas fazem o que o processo local foi construído para fazer.
),
McpServerConfig(
name="pagerduty",
transport="http",
url="https://mcp.example.com/pagerduty",
headers={"Authorization": "Bearer ${PAGERDUTY_MCP_TOKEN}"},
),
],
# Ferramentas MCP são escopadas através de allowed_tools como qualquer outra coisa;
# nomeá-las explicitamente aqui impede que este agente chame todas
# as ferramentas que qualquer servidor possa expor.
allowed_mcp_tools=["logs.search", "pagerduty.create_incident"],
)
prompt = (
f"Um incidente foi relatado: {incident_description}. Procure nos logs recentes "
"por erros relacionados, então crie um incidente no PagerDuty resumindo o que "
"você encontrou, apenas se encontrar uma correspondência genuína."
)
async for message in query(prompt=prompt, options=options):
if message.get("type") == "text":
print(message["text"], end="", flush=True)
elif message.get("type") == "tool_call":
print(f"\n[chamada de ferramenta: {message['tool_name']}]")
asyncio.run(triage_incident("API de Checkout retornando 500s intermitentemente desde 14:02 UTC"))O que isso demonstra:
allowed_mcp_tools) em vez de expor todas as ferramentas que um servidor por acaso oferece.mcp_servers informa ao SDK como alcançá-lo (um comando de subprocesso para stdio, uma URL e cabeçalhos para HTTP) e para buscar suas definições de ferramenta na inicialização.allowed_tools/allowed_mcp_tools controlam quais das ferramentas expostas pelo servidor o loop pode realmente chamar, o mesmo modelo de escopo em camadas usado para ferramentas embutidas.| Transporte | Roda Onde | Bom Para | Consideração |
|---|---|---|---|
| stdio | Subprocesso local, mesma máquina do agente | Acesso a arquivos locais, ferramentas de desenvolvimento local, sem necessidade de salto de rede | Ciclo de vida do processo atrelado à execução do agente |
| HTTP | Servidor remoto | Infraestrutura compartilhada, sistemas já expostos como um serviço | Precisa de sua própria autenticação, a confiabilidade da rede se torna um fator |
# servidores stdio devem ser iniciados com um comando explícito e mínimo -
# evite depender da resolução de PATH ambiente que pode diferir entre
# sua máquina de desenvolvimento e um ambiente de implantação.
McpServerConfig(
name="internal-search",
transport="stdio",
command=["python3", "/opt/mcp-servers/internal_search/main.py"],
)| Parâmetro | Tipo | Descrição |
|---|---|---|
name | str | Identificador usado para referenciar as ferramentas deste servidor |
transport | str | "stdio" ou "http" |
command | list[str] | Comando do subprocesso, apenas stdio |
url | str | Endpoint do servidor, apenas HTTP |
headers | dict | Autenticação ou outros cabeçalhos enviados com requisições HTTP |
allowed_mcp_tools | list[str] | Lista de permissão granular de ferramentas específicas entre servidores registrados |
allowed_mcp_tools para nomear exatamente quais ferramentas este agente pode chamar.headers ou command de um servidor. Comprometer um token de API diretamente em AgentOptions corre o risco de vazá-lo através de logs ou controle de versão. Correção: leia segredos de variáveis de ambiente no momento da chamada, não strings literais no código.query() separadas. O ciclo de vida do processo de um servidor stdio geralmente está atrelado à execução que o iniciou. Correção: não confie no estado do servidor stdio persistindo entre execuções não relacionadas; use um servidor HTTP se precisar de um processo compartilhado de longa duração.| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Apenas ferramentas embutidas | A tarefa se encaixa inteiramente nas capacidades de arquivo/bash/web | A tarefa precisa de um sistema externo específico que o MCP possa alcançar |
| Ferramenta personalizada diretamente integrada ao seu aplicativo | Você precisa de uma integração muito específica e rigidamente acoplada e não a reutilizará em outro lugar | Você deseja que a mesma ferramenta seja reutilizável em múltiplos agentes ou projetos |
| Um subagente que por si só usa ferramentas MCP | O trabalho baseado em MCP é uma subtarefa autocontida que vale a pena isolar | A chamada MCP é uma etapa pequena e única em um fluxo maior |
Sim, as ferramentas MCP são escopadas através do mesmo mecanismo de lista de permissão (geralmente através de uma lista dedicada allowed_mcp_tools), então você controla exatamente quais ferramentas registradas o loop pode chamar.
Sim, mcp_servers aceita uma lista e pode misturar servidores stdio e HTTP juntos em uma única configuração de agente.
Na inicialização, o SDK busca as definições de ferramentas de cada servidor registrado (nomes, descrições, esquemas de argumentos) e as adiciona ao conjunto de ferramentas disponíveis do loop, da mesma forma que as definições de ferramentas embutidas são apresentadas.
As chamadas para as ferramentas desse servidor falham, e essa falha retorna ao loop como uma observação sobre a qual o modelo precisa raciocinar, assim como qualquer outra chamada de ferramenta falha.
Apenas se um já existente adequado não existir para o sistema que você precisa; MCP é um protocolo, então servidores construídos por terceiros ou sua própria equipe funcionam desde que falem MCP.
Sim, mcp_servers e allowed_mcp_tools são definidos por AgentOptions, então as próprias opções de um subagente podem registrar um conjunto diferente (ou mais restrito) do que as de seu pai.
O SDK passa quaisquer cabeçalhos que você configurar; o esquema de autenticação real (token de portador, chave de API, etc.) é definido pelo servidor e fornecido através de headers no seu registro.
Se uma ferramenta MCP realizar uma ação destrutiva ou irreversível, sim; a configuração de checkpoint (checkpoint_tools) se aplica a ferramentas MCP da mesma forma que se aplica a ferramentas embutidas.
Pode, em princípio, já que ferramentas MCP são apenas ferramentas nomeadas com esquemas. Seja deliberado sobre o escopo se você registrar um servidor cujas ferramentas possam entrar em conflito ou se sobrepor em propósito com uma ferramenta embutida.
Versões da Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o Claude Agent SDK (último lançamento, Python e TypeScript). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026