Guías

Conectar con herramientas externas usando MCP

Configura servidores MCP para extender tu agente con herramientas externas. Cubre tipos de transporte, búsqueda de herramientas para conjuntos grandes de herramientas, autenticación y manejo de errores.

El Protocolo de Contexto de Modelo (MCP) es un estándar abierto para conectar agentes de IA a herramientas externas y fuentes de datos. Con MCP, tu agente puede consultar bases de datos, integrarse con APIs como Slack y GitHub, y conectarse a otros servicios sin escribir implementaciones de herramientas personalizadas.

Los servidores MCP pueden ejecutarse como procesos locales, conectarse a través de HTTP o ejecutarse directamente dentro de tu aplicación SDK.

Inicio rápido

Este ejemplo se conecta al servidor MCP de documentación de Claude Code usando transporte HTTP y usa allowedTools con un comodín para permitir todas las herramientas del 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);
  }
}

El agente se conecta al servidor de documentación, busca información sobre hooks y devuelve los resultados.

Agregar un servidor MCP

Puedes configurar servidores MCP en código al llamar a query(), o en un archivo .mcp.json que el SDK carga automáticamente.

En código

Pasa servidores MCP directamente en la opción 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);
  }
}

Desde un archivo de configuración

Crea un archivo .mcp.json en la raíz de tu proyecto. El SDK lo carga automáticamente:

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

Permitir herramientas MCP

Las herramientas MCP requieren permiso explícito antes de que Claude pueda usarlas. Sin permiso, Claude verá que las herramientas están disponibles pero no podrá llamarlas.

Convención de nomenclatura de herramientas

Las herramientas MCP siguen el patrón de nomenclatura mcp__<server-name>__<tool-name>. Por ejemplo, un servidor de GitHub llamado "github" con una herramienta list_issues se convierte en mcp__github__list_issues.

Otorgar acceso con allowedTools

Usa allowedTools para especificar qué herramientas MCP puede usar Claude:

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
  ]
}

Los comodines (*) te permiten permitir todas las herramientas de un servidor sin listar cada una individualmente.

Alternativa: Cambiar el modo de permiso

En lugar de listar herramientas permitidas, puedes cambiar el modo de permiso para otorgar acceso más amplio:

permissionMode: "acceptEdits": Aprueba automáticamente el uso de herramientas (aún solicita operaciones destructivas)
permissionMode: "bypassPermissions": Omite todos los avisos de seguridad, incluidos los de operaciones destructivas como eliminación de archivos o ejecución de comandos de shell. Úsalo con cuidado, especialmente en producción. Este modo se propaga a los suagentes generados por la herramienta Task.

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

Consulta Permisos para más detalles sobre los modos de permiso.

Descubrir herramientas disponibles

Para ver qué herramientas proporciona un servidor MCP, consulta la documentación del servidor o conéctate al servidor e inspecciona el mensaje de inicialización 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

Los servidores MCP se comunican con tu agente usando diferentes protocolos de transporte. Consulta la documentación del servidor para ver qué transporte admite:

Si los documentos te dan un comando para ejecutar (como npx @modelcontextprotocol/server-github), usa stdio
Si los documentos te dan una URL, usa HTTP o SSE
Si estás construyendo tus propias herramientas en código, usa un servidor MCP SDK

Servidores stdio

Procesos locales que se comunican a través de stdin/stdout. Usa esto para servidores MCP que ejecutas en la misma máquina:

Servidores HTTP/SSE

Usa HTTP o SSE para servidores MCP alojados en la nube y APIs remotas:

Para HTTP (sin streaming), usa "type": "http" en su lugar.

Servidores MCP SDK

Define herramientas personalizadas directamente en el código de tu aplicación en lugar de ejecutar un proceso de servidor separado. Consulta la guía de herramientas personalizadas para detalles de implementación.

Búsqueda de herramientas MCP

Cuando tienes muchas herramientas MCP configuradas, las definiciones de herramientas pueden consumir una parte significativa de tu ventana de contexto. La búsqueda de herramientas MCP resuelve esto cargando herramientas dinámicamente bajo demanda en lugar de precargar todas ellas.

Cómo funciona

La búsqueda de herramientas se ejecuta en modo automático de forma predeterminada. Se activa cuando las descripciones de tus herramientas MCP consumirían más del 10% de la ventana de contexto. Cuando se activa:

Las herramientas MCP se marcan con defer_loading: true en lugar de cargarse en contexto por adelantado
Claude usa una herramienta de búsqueda para descubrir herramientas MCP relevantes cuando sea necesario
Solo se cargan en contexto las herramientas que Claude realmente necesita

La búsqueda de herramientas requiere modelos que admitan bloques tool_reference: Sonnet 4 y posteriores, u Opus 4 y posteriores. Los modelos Haiku no admiten búsqueda de herramientas.

Configurar búsqueda de herramientas

Controla el comportamiento de búsqueda de herramientas con la variable de entorno ENABLE_TOOL_SEARCH:

Valor	Comportamiento
`auto`	Se activa cuando las herramientas MCP superan el 10% del contexto (predeterminado)
`auto:5`	Se activa en el umbral del 5% (personaliza el porcentaje)
`true`	Siempre habilitado
`false`	Deshabilitado, todas las herramientas MCP cargadas por adelantado

Establece el valor en la opción env:

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

Autenticación

La mayoría de los servidores MCP requieren autenticación para acceder a servicios externos. Pasa credenciales a través de variables de entorno en la configuración del servidor.

Pasar credenciales a través de variables de entorno

Usa el campo env para pasar claves API, tokens y otras credenciales al servidor MCP:

Consulta Listar problemas de un repositorio para un ejemplo completo y funcional con registro de depuración.

Encabezados HTTP para servidores remotos

Para servidores HTTP y SSE, pasa encabezados de autenticación directamente en la configuración del servidor:

Autenticación OAuth2

La especificación MCP admite OAuth 2.1 para autorización. El SDK no maneja flujos OAuth automáticamente, pero puedes pasar tokens de acceso a través de encabezados después de completar el flujo OAuth en tu aplicación:

// 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__*"]
};

Ejemplos

Listar problemas de un repositorio

Este ejemplo se conecta al servidor MCP de GitHub para listar problemas recientes. El ejemplo incluye registro de depuración para verificar la conexión MCP y las llamadas de herramientas.

Antes de ejecutar, crea un token de acceso personal de GitHub con alcance repo y establécelo como variable de entorno:

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 una base de datos

Este ejemplo usa el servidor MCP de Postgres para consultar una base de datos. La cadena de conexión se pasa como argumento al servidor. El agente descubre automáticamente el esquema de la base de datos, escribe la consulta SQL y devuelve los 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);
  }
}

Manejo de errores

Los servidores MCP pueden fallar al conectarse por varias razones: el proceso del servidor podría no estar instalado, las credenciales podrían ser inválidas o un servidor remoto podría ser inaccesible.

El SDK emite un mensaje system con subtipo init al inicio de cada consulta. Este mensaje incluye el estado de conexión para cada servidor MCP. Verifica el campo status para detectar fallos de conexión antes de que el agente comience a trabajar:

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

Solución de problemas

El servidor muestra estado "failed"

Verifica el mensaje init para ver qué servidores no se conectaron:

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 comunes:

Variables de entorno faltantes: Asegúrate de que los tokens y credenciales requeridos estén configurados. Para servidores stdio, verifica que el campo env coincida con lo que espera el servidor.
Servidor no instalado: Para comandos npx, verifica que el paquete exista y que Node.js esté en tu PATH.
Cadena de conexión inválida: Para servidores de base de datos, verifica el formato de la cadena de conexión y que la base de datos sea accesible.
Problemas de red: Para servidores HTTP/SSE remotos, verifica que la URL sea alcanzable y que los firewalls permitan la conexión.

Las herramientas no se están llamando

Si Claude ve herramientas pero no las usa, verifica que hayas otorgado permiso con allowedTools o cambiando el modo de permiso:

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

Tiempos de espera de conexión

El SDK de MCP tiene un tiempo de espera predeterminado de 60 segundos para conexiones de servidor. Si tu servidor tarda más en iniciarse, la conexión fallará. Para servidores que necesitan más tiempo de inicio, considera:

Usar un servidor más ligero si está disponible
Precalentar el servidor antes de iniciar tu agente
Verificar los registros del servidor para causas de inicialización lenta

Recursos relacionados

Guía de herramientas personalizadas: Construye tu propio servidor MCP que se ejecute en proceso con tu aplicación SDK
Permisos: Controla qué herramientas MCP puede usar tu agente con allowedTools y disallowedTools
Referencia del SDK de TypeScript: Referencia completa de la API incluyendo opciones de configuración de MCP
Referencia del SDK de Python: Referencia completa de la API incluyendo opciones de configuración de MCP
Directorio de servidores MCP: Explora servidores MCP disponibles para bases de datos, APIs y más

Was this page helpful?