Esta página abrange a configuração de MCP para o Agent SDK. Para adicionar servidores MCP ao Claude Code CLI para que sejam carregados em cada projeto, consulte escopos de instalação de MCP.
Início rápido
Este exemplo conecta ao servidor MCP de documentação do Claude Code usando transporte HTTP e usaallowedTools com um curinga para permitir todas as ferramentas do servidor.
Adicionar um servidor MCP
Você pode configurar servidores MCP em código ao chamarquery(), ou em um arquivo .mcp.json carregado via settingSources.
Em código
Passe servidores MCP diretamente na opçãomcpServers:
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:
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 nomenclaturamcp__<server-name>__<tool-name>. Por exemplo, um servidor GitHub nomeado "github" com uma ferramenta list_issues se torna mcp__github__list_issues.
Aprovação automática com allowedTools
UseallowedTools para aprovar automaticamente ferramentas MCP específicas para que Claude possa usá-las sem um prompt de permissão:
*) permitem que você autorize todas as ferramentas de um servidor sem listar cada uma individualmente.
Prefira
allowedTools em vez de modos de permissão para acesso MCP. permissionMode: "acceptEdits" não aprova automaticamente ferramentas MCP (apenas edições de arquivo e comandos Bash do sistema de arquivos). permissionMode: "bypassPermissions" aprova automaticamente ferramentas MCP, mas também desabilita todos os outros prompts de segurança, o que é mais amplo do que necessário. Um curinga em allowedTools concede exatamente o servidor MCP que você deseja e nada mais. Consulte Modos de permissão para uma comparação completa.Descobrir ferramentas disponíveis
Para ver quais ferramentas um servidor MCP fornece, verifique a documentação do servidor ou conecte ao servidor e inspecione a mensagem de inicializaçãosystem:
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 fornecer um comando para executar (como
npx @modelcontextprotocol/server-github), use stdio - Se a documentação fornecer uma URL, use HTTP ou SSE
- Se você estiver 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:- Em código
- .mcp.json
Servidores HTTP/SSE
Use HTTP ou SSE para servidores MCP hospedados em nuvem e APIs remotas:- Em código
- .mcp.json
"type": "http" em vez disso. Em .mcp.json e outros arquivos de configuração JSON, "streamable-http" é aceito como um alias para "http". A opção programática mcpServers aceita apenas "http".
Servidores MCP SDK
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.Busca de ferramentas MCP
Quando você tem muitas ferramentas MCP configuradas, as definições de ferramentas podem consumir uma porção significativa de sua janela de contexto. A busca de ferramentas resolve isso retendo as definições de ferramentas do contexto e carregando apenas as que Claude precisa para cada turno. A busca de ferramentas está habilitada por padrão. Consulte Busca de ferramentas para opções de configuração e detalhes. Para mais detalhes, incluindo melhores práticas e uso de busca de ferramentas com ferramentas SDK personalizadas, consulte o guia de busca de ferramentas.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 campoenv para passar chaves de API, tokens e outras credenciais para o servidor MCP:
- Em código
- .mcp.json
Cabeçalhos HTTP para servidores remotos
Para servidores HTTP e SSE, passe cabeçalhos de autenticação diretamente na configuração do servidor:- Em código
- .mcp.json
Autenticação OAuth2
A especificação MCP suporta OAuth 2.1 para autorização. O SDK não trata fluxos OAuth automaticamente, mas você pode passar tokens de acesso via cabeçalhos após completar o fluxo OAuth em sua aplicação:Exemplos
Listar problemas de um repositório
Este exemplo conecta ao servidor GitHub MCP para listar problemas recentes. O exemplo inclui registro de depuração para verificar a conexão MCP e chamadas de ferramentas. Antes de executar, crie um token de acesso pessoal do GitHub com escoporepo e defina-o como uma variável de ambiente:
Consultar um banco de dados
Este exemplo usa o servidor Postgres MCP para consultar um banco de dados. A string de conexão é passada como um argumento para o servidor. O agente descobre automaticamente o esquema do banco de dados, escreve a consulta SQL e retorna os resultados:Tratamento de erros
Os servidores MCP podem falhar ao conectar por vários motivos: o processo do servidor pode não estar instalado, as credenciais podem ser inválidas ou um servidor remoto pode estar inacessível. O SDK emite uma mensagemsystem com subtipo init no início de cada consulta. Esta mensagem inclui o status de conexão para cada servidor MCP. Verifique o campo status para detectar falhas de conexão antes que o agente comece a trabalhar:
Solução de problemas
Servidor mostra status “failed”
Verifique a mensageminit para ver quais servidores falharam ao conectar:
- Variáveis de ambiente ausentes: Certifique-se de que tokens e credenciais necessários estão definidos. Para servidores stdio, verifique se o campo
envcorresponde ao que o servidor espera. - Servidor não instalado: Para comandos
npx, verifique se o pacote existe e se Node.js está em 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 algum firewall permite a conexão.
Ferramentas não sendo chamadas
Se Claude vê ferramentas mas não as usa, verifique se você concedeu permissão comallowedTools:
Tempos limite de conexão
O SDK MCP tem um tempo limite padrão de 60 segundos para conexões de servidor. Se seu servidor levar mais tempo para iniciar, a conexão falhará. Para servidores que precisam de mais tempo de inicialização, considere:- Usar um servidor mais leve se disponível
- Pré-aquecer o servidor antes de iniciar seu agente
- Verificar logs do servidor para causas de inicialização lenta
Recursos relacionados
- Guia de ferramentas personalizadas: Construa seu próprio servidor MCP que é executado em processo com sua aplicação SDK
- Permissões: Controle quais ferramentas MCP seu agente pode usar com
allowedToolsedisallowedTools - Referência do SDK TypeScript: Referência completa da API incluindo opções de configuração de MCP
- Referência do SDK Python: Referência completa da API incluindo opções de configuração de MCP
- Diretório de servidores MCP: Procure servidores MCP disponíveis para bancos de dados, APIs e muito mais