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.
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.
Resumo
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.
Receita
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:
- Uma tarefa precisa chamar um sistema que não é coberto pelas ferramentas de edição de arquivo, bash ou web.
- Você já possui (ou pode configurar) um servidor MCP para esse sistema.
- Você deseja reutilizar a mesma ferramenta em múltiplos agentes ou projetos diferentes sem reescrever o código de integração a cada vez.
- Você precisa de uma ferramenta remota (HTTP) em vez de uma local (stdio) com base em onde a capacidade realmente reside.
Exemplo de Trabalho
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:
- Registro de um servidor local (stdio) para busca de logs e um servidor remoto (HTTP) para paginação, correspondendo a onde cada capacidade realmente reside.
- Passagem de um cabeçalho de autenticação no registro do servidor HTTP, pois um servidor MCP remoto normalmente precisa de sua própria autenticação independente da chave de API do próprio SDK.
- Restrição de quais ferramentas MCP específicas são chamáveis (
allowed_mcp_tools) em vez de expor todas as ferramentas que um servidor por acaso oferece. - Um prompt que condiciona explicitamente a ação destrutiva (abrir um incidente) a uma descoberta real, reduzindo a chance de uma paginação de falso positivo.
Mergulho Profundo
Como Funciona
- Registrar um servidor MCP com
mcp_serversinforma 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. - Uma vez buscadas, as ferramentas do servidor são adicionadas ao conjunto de ferramentas disponíveis do loop ao lado das ferramentas embutidas; da perspectiva do modelo durante a etapa de decisão, uma ferramenta MCP e uma ferramenta embutida se parecem, um nome, uma descrição e um esquema de argumentos.
- Um servidor stdio se comunica através dos fluxos de entrada/saída padrão do subprocesso; o SDK gerencia o início, a comunicação e, eventualmente, o término desse subprocesso durante a execução.
- Um servidor HTTP se comunica através de requisições HTTP comuns; ele pode ser compartilhado entre múltiplas execuções de agente concorrentes e reside independentemente do ciclo de vida do processo de qualquer agente individual.
- O escopo da ferramenta ainda se aplica:
allowed_tools/allowed_mcp_toolscontrolam quais das ferramentas expostas pelo servidor o loop pode realmente chamar, o mesmo modelo de escopo em camadas usado para ferramentas embutidas.
stdio vs. HTTP em Resumo
| 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 |
Notas de Python
# 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âmetros e Valores de Retorno
| 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 |
Armadilhas
- Registrar um servidor e expor todas as ferramentas que ele oferece. Um servidor construído para uso interno pode expor mais ferramentas do que um agente específico realmente precisa. Correção: use
allowed_mcp_toolspara nomear exatamente quais ferramentas este agente pode chamar. - Codificar segredos em
headersoucommandde um servidor. Comprometer um token de API diretamente emAgentOptionscorre 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. - Assumir que o subprocesso de um servidor stdio sobrevive entre chamadas
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. - Não lidar com um servidor MCP HTTP inacessível. Se o servidor remoto estiver inativo, as chamadas para ele falharão, e o loop precisará ser capaz de raciocinar sobre essa falha. Correção: teste o comportamento de falha deliberadamente e considere se o prompt deve levar em conta uma ferramenta indisponível.
- Confiar cegamente nas descrições de ferramentas de um servidor MCP. Uma descrição de ferramenta enganosa ou maliciosa pode levar o modelo a chamadas não intencionais. Correção: registre apenas servidores MCP nos quais você confia e revise suas descrições de ferramentas da mesma forma que revisaria o escopo de uma ferramenta embutida.
- Confundir qual transporte uma determinada integração precisa. Escolher HTTP para algo que é realmente uma ferramenta de desenvolvimento local (ou vice-versa) adiciona complexidade desnecessária. Correção: combine o transporte com onde a capacidade genuinamente reside.
Alternativas
| 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 |
FAQs
Qual é a diferença prática entre servidores MCP stdio e HTTP?
- stdio roda como um subprocesso local, comunicando-se via entrada/saída padrão.
- HTTP roda remotamente, comunicando-se via requisições HTTP comuns.
- Escolha com base em onde a capacidade realmente reside, não na disponibilidade de um transporte em detrimento do outro.
As ferramentas MCP contam contra allowed_tools da mesma forma que as ferramentas embutidas?
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.
Posso registrar mais de um servidor MCP na mesma execução?
Sim, mcp_servers aceita uma lista e pode misturar servidores stdio e HTTP juntos em uma única configuração de agente.
Como o modelo sabe que uma ferramenta MCP existe?
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.
O que acontece se um servidor MCP estiver inacessível?
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.
Preciso escrever meu próprio servidor MCP para usar isso?
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.
Subagentes podem usar servidores MCP diferentes de seus pais?
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.
A autenticação é tratada pelo SDK para servidores HTTP?
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.
Devo fazer checkpoint das chamadas de ferramentas MCP também?
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.
Um servidor MCP pode expor ferramentas que se sobrepõem 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.
Relacionados
- O Modelo Mental do Claude Agent SDK - como as ferramentas MCP se encaixam no loop
- Habilitando Ferramentas de Edição de Arquivo, Bash e Web no Agent SDK - escopo de ferramentas embutidas, o mesmo modelo aplicado a MCP
- Referência de Opções de Configuração do Claude Agent SDK - formatos de opção relacionados a MCP
- Adicionando Checkpoints Human-in-the-Loop a um Fluxo de Trabalho do Agent SDK - fazendo checkpoint de chamadas MCP destrutivas
- Referência de Padrões de Implantação do Claude Agent SDK - como a forma de implantação afeta as escolhas stdio vs. HTTP
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.