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 utilizaallowedTools con un comodín para permitir todas las herramientas del servidor.
Agregar un servidor MCP
Puede configurar servidores MCP en código al llamar aquery(), o en un archivo .mcp.json cargado a través de settingSources.
En código
Pase servidores MCP directamente en la opciónmcpServers:
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:
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 nomenclaturamcp__<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
UseallowedTools para aprobar automáticamente herramientas MCP específicas para que Claude pueda usarlas sin un aviso de permiso:
*) 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ónsystem:
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:- En código
- .mcp.json
Servidores HTTP/SSE
Use HTTP o SSE para servidores MCP alojados en la nube y APIs remotas:- En código
- .mcp.json
"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 campoenv para pasar claves API, tokens y otras credenciales al servidor MCP:
- En código
- .mcp.json
Encabezados HTTP para servidores remotos
Para servidores HTTP y SSE, pase encabezados de autenticación directamente en la configuración del servidor:- En código
- .mcp.json
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: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 alcancerepo y establézcalo como variable de entorno:
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: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 mensajesystem 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:
Solución de problemas
El servidor muestra estado “failed”
Verifique el mensajeinit para ver qué servidores no se conectaron:
- Variables de entorno faltantes: Asegúrese de que los tokens y credenciales requeridos estén configurados. Para servidores stdio, verifique que el campo
envcoincida 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 conallowedTools:
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
- Guía de herramientas personalizadas: Construya su propio servidor MCP que se ejecute en proceso con su aplicación SDK
- Permisos: Controle qué herramientas MCP puede usar su agente con
allowedToolsydisallowedTools - 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: Explore servidores MCP disponibles para bases de datos, APIs y más