Saltar al contenido principal
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, su 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 su aplicación SDK.
Esta página cubre la configuración de MCP para el Agent SDK. Para agregar servidores MCP a la CLI de Claude Code de modo que se carguen en cada proyecto, consulte Alcances de instalación de MCP.

Inicio rápido

Este ejemplo se conecta al servidor MCP de documentación de Claude Code usando transporte HTTP y utiliza 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

Puede configurar servidores MCP en código al llamar a query(), o en un archivo .mcp.json cargado a través de settingSources.

En código

Pase 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

Cree un archivo .mcp.json en la raíz de su proyecto. El archivo se recoge cuando la fuente de configuración project está habilitada, que lo está para las opciones predeterminadas de query(). Si establece settingSources explícitamente, incluya "project" para que este archivo se cargue:
{
  "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 GitHub llamado "github" con una herramienta list_issues se convierte en mcp__github__list_issues.

Aprobación automática con allowedTools

Use allowedTools para aprobar automáticamente herramientas MCP específicas para que Claude pueda usarlas sin un aviso de permiso:
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
    ]
  }
};
Los comodines (*) le permiten permitir todas las herramientas de un servidor sin enumerar cada una individualmente.
Prefiera allowedTools sobre modos de permiso para acceso a MCP. permissionMode: "acceptEdits" no aprueba automáticamente herramientas MCP (solo ediciones de archivos y comandos Bash del sistema de archivos). permissionMode: "bypassPermissions" sí aprueba automáticamente herramientas MCP pero también desactiva todos los demás avisos de seguridad, lo que es más amplio de lo necesario. Un comodín en allowedTools otorga exactamente el servidor MCP que desea y nada más. Consulte Modos de permiso para una comparación completa.

Descubrir herramientas disponibles

Para ver qué herramientas proporciona un servidor MCP, consulte la documentación del servidor o conéctese al servidor e inspeccione 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 su agente utilizando diferentes protocolos de transporte. Consulte la documentación del servidor para ver qué transporte admite:
  • Si los documentos le dan un comando para ejecutar (como npx @modelcontextprotocol/server-github), use stdio
  • Si los documentos le dan una URL, use HTTP o SSE
  • Si está construyendo sus propias herramientas en código, use un servidor MCP SDK

Servidores stdio

Procesos locales que se comunican a través de stdin/stdout. Use esto para servidores MCP que ejecuta en la misma 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 o SSE para servidores MCP alojados en la nube y 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 el transporte HTTP transmisible, use "type": "http" en su lugar. En .mcp.json y otros archivos de configuración JSON, "streamable-http" se acepta como un alias para "http". La opción programática mcpServers acepta solo "http".

Servidores MCP SDK

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

Búsqueda de herramientas MCP

Cuando tiene muchas herramientas MCP configuradas, las definiciones de herramientas pueden consumir una parte significativa de su ventana de contexto. La búsqueda de herramientas resuelve esto al retener las definiciones de herramientas del contexto y cargar solo las que Claude necesita para cada turno. La búsqueda de herramientas está habilitada de forma predeterminada. Consulte Búsqueda de herramientas para opciones de configuración y detalles. Para más detalles, incluidas las mejores prácticas y el uso de búsqueda de herramientas con herramientas SDK personalizadas, consulte la guía de búsqueda de herramientas.

Autenticación

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

Pasar credenciales a través de variables de entorno

Use el campo env para pasar claves API, tokens y otras credenciales al 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 un repositorio para un ejemplo completo y funcional con registro de depuración.

Encabezados HTTP para servidores remotos

Para servidores HTTP y SSE, pase encabezados de autenticación directamente en la configuración del 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__*"]
  }
};

Autenticación OAuth2

La especificación MCP admite OAuth 2.1 para autorización. El SDK no maneja flujos OAuth automáticamente, pero puede pasar tokens de acceso a través de encabezados después de completar el flujo OAuth en su 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 GitHub MCP para enumerar problemas recientes. El ejemplo incluye registro de depuración para verificar la conexión MCP y las llamadas de herramientas. Antes de ejecutar, cree un token de acceso personal de GitHub con alcance repo y establézcalo 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.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 utiliza el servidor Postgres MCP 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. Verifique 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”

Verifique 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úrese de que los tokens y credenciales requeridos estén configurados. Para servidores stdio, verifique que el campo env coincida con lo que espera el servidor.
  • Servidor no instalado: Para comandos npx, verifique que el paquete exista y que Node.js esté en su PATH.
  • Cadena de conexión inválida: Para servidores de base de datos, verifique el formato de la cadena de conexión y que la base de datos sea accesible.
  • Problemas de red: Para servidores HTTP/SSE remotos, verifique que la URL sea accesible y que los firewalls permitan la conexión.

Las herramientas no se están llamando

Si Claude ve herramientas pero no las usa, verifique que haya otorgado permiso con allowedTools:
const _ = {
  options: {
    mcpServers: {
      // your servers
    },
    allowedTools: ["mcp__servername__*"] // Auto-approve calls from this server
  }
};

Tiempos de espera de conexión

El SDK de MCP tiene un tiempo de espera predeterminado de 60 segundos para conexiones de servidor. Si su servidor tarda más en iniciarse, la conexión fallará. Para servidores que necesitan más tiempo de inicio, considere:
  • Usar un servidor más ligero si está disponible
  • Precalentar el servidor antes de iniciar su agente
  • Verificar los registros del servidor para causas de inicialización lenta

Recursos relacionados