Pular para o conteúdo principal
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.
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 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:
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:
{
  "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.

Aprovação automática com allowedTools

Use allowedTools para aprovar automaticamente 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ê 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ção system:
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:
const _ = {
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: process.env.GITHUB_TOKEN
        }
      }
    },
    allowedTools: ["mcp__github__list_issues", "mcp__github__search_issues"]
  }
};

Servidores HTTP/SSE

Use HTTP ou SSE para servidores MCP hospedados em nuvem e APIs remotas:
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 em fluxo contínuo, use "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 campo env para passar chaves de API, tokens e outras credenciais para o servidor MCP:
const _ = {
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: process.env.GITHUB_TOKEN
        }
      }
    },
    allowedTools: ["mcp__github__list_issues"]
  }
};
Consulte Listar problemas de um repositório para um exemplo completo e funcional com registro 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:
const _ = {
  options: {
    mcpServers: {
      "secure-api": {
        type: "http",
        url: "https://api.example.com/mcp",
        headers: {
          Authorization: `Bearer ${process.env.API_TOKEN}`
        }
      }
    },
    allowedTools: ["mcp__secure-api__*"]
  }
};

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 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 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.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 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:
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:
const _ = {
  options: {
    mcpServers: {
      // your servers
    },
    allowedTools: ["mcp__servername__*"] // Auto-approve calls from this server
  }
};

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