Conectar a ferramentas externas com MCP

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 da 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 que o SDK carrega automaticamente.

Em código

Passe servidores MCP diretamente na opção mcpServers:

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 SDK carrega isso automaticamente:

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

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.

Conceder acesso com allowedTools

Use allowedTools para especificar quais ferramentas MCP Claude pode usar:

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ê autorize todas as ferramentas de um servidor sem listar cada uma individualmente.

Alternativa: Alterar o modo de permissão

Em vez de listar ferramentas permitidas, você pode alterar o modo de permissão para conceder acesso mais amplo:

• permissionMode: "acceptEdits": Aprova automaticamente o uso de ferramentas (ainda solicita para operações destrutivas)
• permissionMode: "bypassPermissions": Ignora todos os prompts de segurança, incluindo para operações destrutivas como exclusão de arquivos ou execução de comandos shell. Use com cuidado, especialmente em produção. Este modo se propaga para subagentos gerados pela ferramenta Task.

options: {
  mcpServers: { /* your servers */ },
  permissionMode: "acceptEdits"  // No need for allowedTools
}

Veja Permissões para mais detalhes sobre modos de permissão.

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 system init:

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

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:

Servidores HTTP/SSE

Use HTTP ou SSE para servidores MCP hospedados em nuvem e APIs remotas:

Para HTTP (não-streaming), use "type": "http" em vez disso.

Servidores MCP SDK

Defina ferramentas personalizadas diretamente no código de sua aplicação em vez de executar um processo de servidor separado. Veja 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 MCP resolve isso carregando ferramentas dinamicamente sob demanda em vez de pré-carregar todas elas.

Como funciona

A busca de ferramentas é executada em modo automático por padrão. Ela é ativada quando suas descrições de ferramentas MCP consumiriam mais de 10% da janela de contexto. Quando acionada:

1. As ferramentas MCP são marcadas com defer_loading: true em vez de serem carregadas no contexto antecipadamente
2. Claude usa uma ferramenta de busca para descobrir ferramentas MCP relevantes quando necessário
3. Apenas as ferramentas que Claude realmente precisa são carregadas no contexto

A busca de ferramentas requer modelos que suportam blocos tool_reference: Sonnet 4 e posterior, ou Opus 4 e posterior. Os modelos Haiku não suportam busca de ferramentas.

Configurar busca de ferramentas

Controle o comportamento da busca de ferramentas com a variável de ambiente ENABLE_TOOL_SEARCH:

Defina o valor na opção env:

const options = {
  mcpServers: { /* your MCP servers */ },
  env: {
    ENABLE_TOOL_SEARCH: "auto:5"  // Enable at 5% threshold
  }
};

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:

Veja Listar problemas de um repositório para um exemplo completo e funcional com log de depuração.

Cabeçalhos HTTP para servidores remotos

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

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:

// After completing OAuth flow in your app
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 conecta ao servidor MCP do GitHub para listar problemas recentes. O exemplo inclui log 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 escopo repo e defina-o como uma variável de ambiente:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

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": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: 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.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);
  }
}

Consultar um banco de dados

Este exemplo usa o servidor MCP do Postgres 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:

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

// Connection string from environment variable
const connectionString = process.env.DATABASE_URL;

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",
        // Pass connection string as argument to the server
        args: ["-y", "@modelcontextprotocol/server-postgres", connectionString]
      }
    },
    // Allow only read queries, not writes
    allowedTools: ["mcp__postgres__query"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

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 mensagem system 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:

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

for await (const message of query({
  prompt: "Process data",
  options: {
    mcpServers: {
      "data-processor": dataServer
    }
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    const failedServers = message.mcp_servers.filter(
      s => s.status !== "connected"
    );

    if (failedServers.length > 0) {
      console.warn("Failed to connect:", failedServers);
    }
  }

  if (message.type === "result" && message.subtype === "error_during_execution") {
    console.error("Execution failed");
  }
}

Solução de problemas

Servidor mostra status "failed"

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`);
    }
  }
}

Causas comuns:

• Variáveis de ambiente ausentes: Certifique-se de que tokens e credenciais necessários estão 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á 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 com allowedTools ou alterando o modo de permissão:

options: {
  mcpServers: { /* your servers */ },
  allowedTools: ["mcp__servername__*"]  // Required for Claude to use the tools
}

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 allowedTools e disallowedTools
• Referência do SDK TypeScript: Referência completa da API incluindo opções de configuração MCP
• Referência do SDK Python: Referência completa da API incluindo opções de configuração MCP
• Diretório de servidores MCP: Procure servidores MCP disponíveis para bancos de dados, APIs e muito mais