SpyBara
Go Premium

agent-sdk/mcp.md 2026-09-13 21:00 UTC to 2026-09-14 22:58 UTC

This page contains 1 addition and 1 deletion.

2026
Wed 9 22:58 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58

Conectar a ferramentas externas com MCP

Configure servidores MCP para estender seu agente com ferramentas externas. Abrange tipos de transporte, busca de ferramentas para grandes conjuntos de ferramentas, autenticação e tratamento de erros.

O Model Context Protocol (MCP) é um padrão aberto para conectar agentes de IA a ferramentas e fontes de dados externas. Com MCP, seu agente pode consultar bancos de dados, integrar com APIs como Slack e GitHub, e conectar a outros serviços sem escrever implementações de ferramentas personalizadas.

Os servidores MCP podem ser executados como processos locais, conectar via HTTP ou executar diretamente dentro de sua aplicação SDK.

Início rápido

Este exemplo conecta ao servidor MCP de documentação do Claude Code usando transporte HTTP e usa allowedTools com um curinga para permitir todas as ferramentas do servidor.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Use the docs MCP server to explain what hooks are in Claude Code",
options: {
mcpServers: {
"claude-code-docs": {
type: "http",
url: "https://code.claude.com/docs/mcp"
}
},
allowedTools: ["mcp__claude-code-docs__*"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

O agente conecta ao servidor de documentação, busca informações sobre hooks e retorna os resultados.

Adicionar um servidor MCP

Você pode configurar servidores MCP em código ao chamar query(), ou em um arquivo .mcp.json carregado via settingSources.

Em código

Passe servidores MCP diretamente na opção mcpServers. Este exemplo inicia um servidor MCP de sistema de arquivos local para /Users/me/projects. Substitua esse caminho por um diretório em sua máquina:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "List files in my project",
options: {
mcpServers: {
filesystem: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
}
},
allowedTools: ["mcp__filesystem__*"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

De um arquivo de configuração

Crie um arquivo .mcp.json na raiz do seu projeto. O arquivo é detectado quando a fonte de configuração project está habilitada, o que é padrão para as opções query(). Se você definir settingSources explicitamente, inclua "project" para que este arquivo seja carregado. Substitua /Users/me/projects por um diretório em sua máquina:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

Tempo de conexão

Claude Code registra os servidores que você passa em options.mcpServers na inicialização e emite a mensagem init uma vez que a espera da primeira volta, se houver, seja resolvida. Sem options.mcpServers, Claude Code aguarda 2 segundos por servidores pendentes antes da primeira volta, portanto servidores carregados de arquivos de configuração como .mcp.json geralmente mostram pending na inicialização. Quando cada servidor options.mcpServers se conecta, e se atrasa a primeira volta, depende do seu tipo:

Tipo de servidor Atrasa a primeira volta? Tempo limite de espera da primeira volta
Servidor stdio, ou servidor HTTP/SSE sem uma lista de ferramentas em cache Sim, até que se conecte MCP_TIMEOUT, 30 segundos por padrão; a conexão falha nesse prazo
Servidor remoto com uma lista de ferramentas em cache, salva por Claude Code de uma conexão anterior Não; as ferramentas em cache estão disponíveis desde a primeira volta Nenhum; conecta na sua primeira chamada de ferramenta, e essa conexão adiada tem seu próprio tempo limite
Servidor SDK em processo Sim, até que se conecte e liste suas ferramentas Nenhum; as solicitações de conexão e listagem de ferramentas têm seus próprios tempos limite

Para bloquear a própria inicialização em uma fase separada e anterior à espera da primeira volta, antes da mensagem init ser enviada:

  • Defina MCP_CONNECTION_NONBLOCKING como 0 para bloquear em todo o lote de conexão. Claude Code limita essa espera a 5 segundos por padrão. Ajuste o limite com a variável de ambiente MCP_CONNECT_TIMEOUT_MS, em milissegundos. Servidores ainda pendentes nesse prazo continuam se conectando em segundo plano.
  • Defina alwaysLoad: true na configuração de um servidor para disponibilizar suas ferramentas em seus esquemas completos na primeira volta, isentos do adiamento de busca de ferramentas. Claude Code aguarda na inicialização pelas ferramentas desse servidor, limitado ao mesmo prazo, enquanto outros servidores continuam se conectando em segundo plano; um servidor remoto com uma lista de ferramentas em cache as fornece sem se conectar, conforme a tabela acima.

A mensagem system com subtipo init relata o status de cada servidor no momento em que é emitida; consulte Tratamento de erros para ler esses status.

Permitir ferramentas MCP

As ferramentas MCP requerem permissão explícita antes que Claude possa usá-las. Sem permissão, Claude verá que as ferramentas estão disponíveis, mas não poderá chamá-las.

Convenção de nomenclatura de ferramentas

As ferramentas MCP seguem o padrão de nomenclatura mcp__<server-name>__<tool-name>. Por exemplo, um servidor GitHub nomeado "github" com uma ferramenta list_issues se torna mcp__github__list_issues.

Auto-aprovação com allowedTools

Use allowedTools para auto-aprovar ferramentas MCP específicas para que Claude possa usá-las sem um prompt de permissão:

const _ = {
options: {
mcpServers: {
// your servers
},
allowedTools: [
"mcp__github__*", // All tools from the github server
"mcp__db__query", // Only the query tool from db server
"mcp__slack__send_message" // Only send_message from slack server
]
}
};

Curingas (*) permitem que você aprove todas as ferramentas de um servidor sem listar cada uma individualmente.

Descobrir ferramentas disponíveis

Para ver quais ferramentas um servidor MCP fornece, verifique a documentação do servidor ou inspecione o array tools na mensagem init system. Os nomes das ferramentas MCP começam com mcp__.

Claude Code emite a mensagem init após a espera de conexão de primeira volta para servidores passados em options.mcpServers, então o array tools lista as ferramentas mcp__ de cada servidor que se conectou até então, mais aquelas de servidores com uma lista de ferramentas em cache, que se conectam no primeiro uso. As ferramentas de qualquer outro servidor que não se conectou estão ausentes; veja Tratamento de erros para ler o status de cada servidor.

Este filtro imprime os nomes das ferramentas MCP:

import { query } from "@anthropic-ai/claude-agent-sdk";

const options = {
mcpServers: {
// your servers
},
};

for await (const message of query({ prompt: "...", options })) {
if (message.type === "system" && message.subtype === "init") {
const mcpTools = message.tools.filter((name) => name.startsWith("mcp__"));
console.log("Available MCP tools:", mcpTools);
}
}

Você também pode pedir a Claude para listar as ferramentas disponíveis de um servidor.

Tipos de transporte

Os servidores MCP se comunicam com seu agente usando diferentes protocolos de transporte. Verifique a documentação do servidor para ver qual transporte ele suporta:

  • Se a documentação fornece um comando para executar (como npx @modelcontextprotocol/server-filesystem), use stdio
  • Se a documentação fornece uma URL, use HTTP ou SSE
  • Se você está construindo suas próprias ferramentas em código, use um servidor MCP SDK

Servidores stdio

Processos locais que se comunicam via stdin/stdout. Use isso para servidores MCP que você executa na mesma máquina. Para o formulário .mcp.json, use os mesmos campos mostrados em De um arquivo de configuração. Em código, passe o comando e seus argumentos. Substitua /Users/me/projects por um diretório em sua máquina:

const _ = {
options: {
mcpServers: {
filesystem: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
}
},
allowedTools: ["mcp__filesystem__read_file", "mcp__filesystem__list_directory"]
}
};

Servidores HTTP/SSE

Use HTTP ou SSE para servidores MCP hospedados em nuvem e APIs remotas. Para o formulário .mcp.json, use os mesmos campos do exemplo em Cabeçalhos HTTP para servidores remotos, com "type": "sse" para um servidor SSE. Em código, passe a URL do servidor:

const _ = {
options: {
mcpServers: {
"remote-api": {
type: "sse",
url: "https://api.example.com/mcp/sse",
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`
}
}
},
allowedTools: ["mcp__remote-api__*"]
}
};

Para o transporte HTTP transmissível, use "type": "http" em vez disso. Em arquivos de configuração .mcp.json e outros JSON, "streamable-http" é aceito como um alias para "http". O tipo McpHttpServerConfig dos SDKs declara apenas "http", então use "http" para servidores que você passa em código.

Servidores SDK MCP

Defina ferramentas personalizadas diretamente no código da sua aplicação em vez de executar um processo de servidor separado. Consulte o guia de ferramentas personalizadas para detalhes de implementação.

Um servidor MCP SDK registrado por uma solicitação de controle initialize começa a se conectar assim que Claude Code processa a solicitação.

Quando você tem muitas ferramentas MCP configuradas, as definições de ferramentas podem consumir uma porção significativa da sua janela de contexto. A busca de ferramentas resolve isso ao reter as definições de ferramentas do contexto e carregar apenas as que Claude precisa para cada turno.

A busca de ferramentas está ativada por padrão. Consulte Busca de ferramentas para opções de configuração, melhores práticas e uso da busca de ferramentas com ferramentas SDK personalizadas.

Autenticação

A maioria dos servidores MCP requer autenticação para acessar serviços externos. Passe credenciais através de variáveis de ambiente na configuração do servidor.

Passar credenciais via variáveis de ambiente

Use o campo env para passar chaves de API, tokens e outras credenciais para o servidor MCP:

const _ = {
options: {
mcpServers: {
"api-server": {
command: "npx",
args: ["-y", "@your-org/api-mcp-server"],
env: {
API_KEY: process.env.API_KEY
}
}
},
allowedTools: ["mcp__api-server__*"]
}
};

Cabeçalhos HTTP para servidores remotos

Para servidores HTTP e SSE, passe cabeçalhos de autenticação diretamente na configuração do servidor:

const _ = {
options: {
mcpServers: {
"secure-api": {
type: "http",
url: "https://api.example.com/mcp",
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`
}
}
},
allowedTools: ["mcp__secure-api__*"]
}
};

Para um exemplo completo de funcionamento de um servidor remoto autenticado com cabeçalhos, consulte Listar problemas de um repositório.

Autenticação OAuth2

A especificação MCP suporta OAuth 2.1 para autorização. O SDK não abre um navegador nem executa um fluxo OAuth interativo. Quando um servidor configurado retorna um desafio de autorização e nenhum token armazenado está disponível, a execução do agente continua sem as ferramentas desse servidor, e o servidor relata o status needs-auth. O array mcp_servers da mensagem de inicialização do sistema ainda pode mostrar pending para esse servidor quando for emitido. Para confirmar se um servidor precisa de credenciais, consulte mcpServerStatus() no SDK TypeScript ou get_mcp_status() em Python.

Para fornecer credenciais, complete o fluxo OAuth em sua própria aplicação e passe o token de acesso resultante nos headers do servidor:

// Após completar o fluxo OAuth em sua aplicação.
// Implemente getAccessTokenFromOAuthFlow para seu provedor OAuth.
const accessToken = await getAccessTokenFromOAuthFlow();

const options = {
mcpServers: {
"oauth-api": {
type: "http",
url: "https://api.example.com/mcp",
headers: {
Authorization: `Bearer ${accessToken}`
}
}
},
allowedTools: ["mcp__oauth-api__*"]
};

Exemplos

Listar problemas de um repositório

Este exemplo se conecta ao servidor MCP do GitHub remoto para listar problemas recentes. O exemplo inclui registro de depuração para verificar a conexão MCP e as chamadas de ferramentas.

Antes de executar, crie um token de acesso pessoal do GitHub com acesso de leitura aos repositórios que você deseja consultar e defina-o como uma variável de ambiente:

export GITHUB_TOKEN=YOUR_GITHUB_PAT

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "List the 3 most recent issues in anthropics/claude-code",
options: {
mcpServers: {
github: {
type: "http",
url: "https://api.githubcopilot.com/mcp/",
headers: {
Authorization: `Bearer ${process.env.GITHUB_TOKEN}`
}
}
},
allowedTools: ["mcp__github__list_issues"]
}
})) {
// Verify MCP server connected successfully
if (message.type === "system" && message.subtype === "init") {
console.log("MCP servers:", message.mcp_servers);
}

// Log when Claude calls an MCP tool
if (message.type === "assistant") {
for (const block of message.message.content) {
if (block.type === "tool_use" && block.name.startsWith("mcp__")) {
console.log("MCP tool called:", block.name);
}
}
}

// Print the final result
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

Na linha MCP servers:, um status de connected para github confirma que o token funciona. Se Claude Code tiver uma lista de ferramentas em cache para o servidor, o status pode ler pending em vez disso e o servidor se conecta na sua primeira chamada de ferramenta. Se o status for failed ou needs-auth, consulte Tratamento de erros antes de confiar no resultado, pois Claude pode voltar para ferramentas integradas quando o servidor não está disponível.

Consultar um banco de dados

Este exemplo usa DBHub para consultar um banco de dados Postgres. O agente descobre automaticamente o esquema do banco de dados, escreve a consulta SQL e retorna os resultados.

A ferramenta execute_sql do DBHub executa qualquer SQL que o agente emita, incluindo gravações, a menos que você o restrinja. Definir readonly = true no arquivo de configuração do DBHub faz com que o DBHub rejeite instruções INSERT, UPDATE, DELETE e DDL, para que o exemplo não possa modificar seus dados mesmo se o agente emitir uma gravação. O DBHub resolve ${DATABASE_URL} do ambiente do processo quando carrega a configuração, portanto a string de conexão fica fora do arquivo. Crie este dbhub.toml ao lado do seu script:

[[sources]]
id = "production"
dsn = "${DATABASE_URL}"

[[tools]]
name = "execute_sql"
source = "production"
readonly = true

O script então aponta o DBHub para o arquivo de configuração em vez de passar uma string de conexão diretamente. Antes de executar, defina a variável de ambiente DATABASE_URL para sua string de conexão. Substitua os valores de espaço reservado pelos detalhes do seu banco de dados:

export DATABASE_URL=postgresql://user:password@localhost:5432/mydb

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
// Natural language query - Claude writes the SQL
prompt: "How many users signed up last week? Break it down by day.",
options: {
mcpServers: {
postgres: {
command: "npx",
// dbhub.toml sets readonly = true, so execute_sql rejects writes
args: ["-y", "@bytebase/dbhub", "--config", "dbhub.toml"]
}
},
allowedTools: ["mcp__postgres__execute_sql"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

Tratamento de erros

Os servidores MCP podem falhar ao conectar por várias razões: o processo do servidor pode não estar instalado, as credenciais podem ser inválidas ou um servidor remoto pode estar inacessível.

Claude Code emite uma mensagem system com subtipo init no início de cada consulta. Esta mensagem inclui o status de conexão para cada servidor MCP. O campo status pode ser "pending", "connected", "failed", "needs-auth" ou "disabled". Claude Code emite a mensagem init após o tempo de espera de conexão da primeira volta para servidores passados em options.mcpServers, portanto, tal servidor que se conectou dentro do tempo de espera mostra "connected".

Na mensagem init, não trate "pending" como uma falha por si só. Pode significar qualquer um destes:

Verifique "failed" ou "needs-auth" para detectar servidores que não serão utilizáveis:

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
for await (const message of query({
prompt: "Process data",
options: {
mcpServers: {
// Replace dataServer with your server configuration
"data-processor": dataServer
}
}
})) {
if (message.type === "system" && message.subtype === "init") {
const unavailableServers = message.mcp_servers.filter(
(s) => s.status === "failed" || s.status === "needs-auth"
);

if (unavailableServers.length > 0) {
console.warn("Unavailable MCP servers:", unavailableServers);
}
}

if (message.type === "result" && message.subtype === "error_during_execution") {
console.error("Execution failed");
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, the error subtype branch above has
// already run; a failure to start or reach the Claude Code process
// yields no result message. MCP servers that fail to connect don't
// throw: use the status check above, and note that servers still
// "pending" at init need a later status check.
console.log(`Session ended with an error: ${error}`);
}

O status de um servidor remoto também pode mudar após relatar "connected". Quando a conexão com ele cai no meio da sessão, Claude Code move o servidor de volta para "pending" enquanto reconecta. Uma chamada posterior a mcpServerStatus() em TypeScript, ou ClaudeSDKClient.get_mcp_status() em Python, pode então relatar "pending" para um servidor que você viu conectado anteriormente, sem nenhuma mudança de configuração do seu lado.

Após cinco tentativas de reconexão falharem, o servidor relata "failed" ou "needs-auth" quando precisa ser autorizado novamente. Para tentar novamente manualmente, chame reconnectMcpServer() em TypeScript ou ClaudeSDKClient.reconnect_mcp_server() em Python.

Troubleshooting

Server shows "failed" status

Verifique a mensagem init para ver quais servidores falharam ao conectar:

if (message.type === "system" && message.subtype === "init") {
for (const server of message.mcp_servers) {
if (server.status === "failed") {
console.error(`Server ${server.name} failed to connect`);
}
}
}

Um status "pending" não significa que o servidor falhou. Consulte Tratamento de erros para os casos que ele cobre na inicialização. Para obter status atualizados posteriormente na sessão, chame o método mcpServerStatus() da consulta no SDK TypeScript, ou ClaudeSDKClient.get_mcp_status() em Python.

Causas comuns:

  • Variáveis de ambiente ausentes: Certifique-se de que tokens e credenciais necessários estejam definidos. Para servidores stdio, verifique se o campo env corresponde ao que o servidor espera.
  • Servidor não instalado: Para comandos npx, verifique se o pacote existe e se Node.js está no seu PATH.
  • String de conexão inválida: Para servidores de banco de dados, verifique o formato da string de conexão e se o banco de dados está acessível.
  • Problemas de rede: Para servidores HTTP/SSE remotos, verifique se a URL está acessível e se qualquer firewall permite a conexão.

Tools not being called

Se Claude vir ferramentas mas não as usar, verifique se você concedeu permissão com allowedTools:

const _ = {
options: {
mcpServers: {
// your servers
},
allowedTools: ["mcp__servername__*"] // Auto-approve calls from this server
}
};

Connection timeouts

As conexões do servidor MCP expiram após 30 segundos por padrão. Para alterar quanto tempo uma chamada de ferramenta em execução pode levar, defina MCP_TOOL_TIMEOUT. Se seu servidor levar mais tempo para iniciar, a conexão falhará. Aumente o limite de conexão com a variável de ambiente MCP_TIMEOUT, em milissegundos. Para servidores que precisam de mais tempo de inicialização, também considere:

  • Usar um servidor mais leve, se disponível
  • Pré-aquecer o servidor antes de iniciar seu agente
  • Verificar os logs do servidor para causas de inicialização lenta

Em TypeScript, você pode definir o limite de chamada de ferramenta para um único servidor MCP do SDK passando timeout para createSdkMcpServer().

Tool output exceeds maximum allowed tokens

O SDK aplica o mesmo limite de saída MCP que Claude Code. Quando um resultado de ferramenta sem conteúdo de imagem é maior que 25.000 tokens, Claude Code salva a saída em um arquivo e substitui o resultado da ferramenta por uma mensagem de erro que nomeia o caminho do arquivo, para que o agente possa ler a saída novamente em porções.

Aumente o limite com a variável de ambiente MAX_MCP_OUTPUT_TOKENS. Consulte Limites de saída MCP e avisos para o comportamento completo, incluindo como um servidor pode declarar um limite por ferramenta mais alto com a anotação anthropic/maxResultSizeChars.