Conectar Claude Code a herramientas mediante MCP

Claude Code puede conectarse a cientos de herramientas externas y fuentes de datos a través del Model Context Protocol (MCP), un estándar de código abierto para integraciones de IA con herramientas. Los servidores MCP dan a Claude Code acceso a sus herramientas, bases de datos y APIs. Conecte un servidor cuando se encuentre copiando datos en el chat desde otra herramienta, como un rastreador de problemas o un panel de monitoreo. Una vez conectado, Claude puede leer y actuar en ese sistema directamente en lugar de trabajar con lo que pegue.

Qué puede hacer con MCP

Con servidores MCP conectados, puede pedirle a Claude Code que:

Implemente características desde rastreadores de problemas: “Agregue la característica descrita en el problema JIRA ENG-4521 y cree un PR en GitHub.”
Analice datos de monitoreo: “Verifique Sentry y Statsig para verificar el uso de la característica descrita en ENG-4521.”
Consulte bases de datos: “Encuentre correos electrónicos de 10 usuarios aleatorios que utilizaron la característica ENG-4521, basándose en nuestra base de datos PostgreSQL.”
Integre diseños: “Actualice nuestra plantilla de correo electrónico estándar basándose en los nuevos diseños de Figma que se publicaron en Slack”
Automatice flujos de trabajo: “Cree borradores de Gmail invitando a estos 10 usuarios a una sesión de retroalimentación sobre la nueva característica.”
Reaccione a eventos externos: Un servidor MCP también puede actuar como un canal que envía mensajes a su sesión, para que Claude reaccione a mensajes de Telegram, chats de Discord o eventos de webhook mientras está fuera.

Buscar y crear servidores MCP

Explore conectores revisados en el Directorio de Anthropic. Los conectores del Directorio utilizan la misma infraestructura MCP que Claude Code, por lo que puede agregar cualquier servidor remoto listado allí con claude mcp add.

Verifique que confía en cada servidor antes de conectarlo. Los servidores que obtienen contenido externo pueden exponerlo al riesgo de inyección de indicaciones.

Para crear su propio servidor, consulte la guía del servidor MCP para los fundamentos del protocolo y la documentación de construcción de conectores de Claude para autenticación, pruebas y envío al Directorio. También puede hacer que Claude cree un servidor para usted con el plugin oficial mcp-server-dev.

Instalar el plugin

En una sesión de Claude Code, ejecute:

/plugin install mcp-server-dev@claude-plugins-official

Luego ejecute /reload-plugins para activarlo en la sesión actual.

Ejecutar la skill de construcción

/mcp-server-dev:build-mcp-server

Claude le pregunta sobre su caso de uso y crea un servidor HTTP remoto o un servidor stdio local.

Instalación de servidores MCP

Los servidores MCP se pueden configurar de tres formas diferentes según sus necesidades:

Opción 1: Agregar un servidor HTTP remoto

Los servidores HTTP son la opción recomendada para conectarse a servidores MCP remotos. Este es el transporte más ampliamente soportado para servicios basados en la nube.

# Sintaxis básica
claude mcp add --transport http <name> <url>

# Ejemplo real: Conectar a Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Ejemplo con token Bearer
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Cuando configure servidores MCP a través de JSON en .mcp.json, ~/.claude.json, o claude mcp add-json, el campo type acepta streamable-http como un alias para http. La especificación de MCP utiliza el nombre streamable-http para este transporte, por lo que las configuraciones copiadas de la documentación del servidor funcionan sin modificación.

Opción 2: Agregar un servidor SSE remoto

El transporte SSE (Server-Sent Events) está deprecado. Use servidores HTTP en su lugar, donde estén disponibles.

# Sintaxis básica
claude mcp add --transport sse <name> <url>

# Ejemplo real: Conectar a Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Ejemplo con encabezado de autenticación
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Opción 3: Agregar un servidor stdio local

Los servidores stdio se ejecutan como procesos locales en su máquina. Son ideales para herramientas que necesitan acceso directo al sistema o scripts personalizados. Claude Code establece CLAUDE_PROJECT_DIR en el entorno del servidor generado a la raíz del proyecto, por lo que su servidor puede resolver rutas relativas al proyecto sin depender del directorio de trabajo. Este es el mismo directorio que los hooks reciben en su variable CLAUDE_PROJECT_DIR. Léalo desde dentro de su proceso de servidor, por ejemplo process.env.CLAUDE_PROJECT_DIR en Node o os.environ["CLAUDE_PROJECT_DIR"] en Python. Su servidor también puede llamar a la solicitud MCP roots/list, que devuelve el directorio desde el cual se lanzó Claude Code. Esta variable se establece en el entorno del servidor, no en el entorno propio de Claude Code, por lo que hacer referencia a ella mediante la expansión ${VAR} en un archivo .mcp.json con alcance de proyecto o usuario en command o args requiere un valor predeterminado como ${CLAUDE_PROJECT_DIR:-.}. Las configuraciones MCP proporcionadas por plugins sustituyen ${CLAUDE_PROJECT_DIR} directamente y no necesitan el valor predeterminado.

# Sintaxis básica
claude mcp add [options] <name> -- <command> [args...]

# Ejemplo real: Agregar servidor Airtable
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

Importante: Orden de opcionesTodas las opciones (--transport, --env, --scope, --header) deben venir antes del nombre del servidor. El -- (doble guión) luego separa el nombre del servidor del comando y los argumentos que se pasan al servidor MCP.Por ejemplo:

claude mcp add --transport stdio myserver -- npx server → ejecuta npx server
claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080 → ejecuta python server.py --port 8080 con KEY=value en el entorno

Esto evita conflictos entre las banderas de Claude y las banderas del servidor.

Gestión de sus servidores

Una vez configurados, puede gestionar sus servidores MCP con estos comandos:

# Listar todos los servidores configurados
claude mcp list

# Obtener detalles para un servidor específico
claude mcp get github

# Eliminar un servidor
claude mcp remove github

# (dentro de Claude Code) Verificar estado del servidor
/mcp

El panel /mcp muestra el recuento de herramientas junto a cada servidor conectado e indica los servidores que anuncian la capacidad de herramientas pero no exponen ninguna herramienta. El nombre del servidor workspace está reservado para uso interno. Si su configuración define un servidor con ese nombre, Claude Code lo omite al cargar y muestra una advertencia pidiéndole que lo renombre.

Actualizaciones dinámicas de herramientas

Claude Code admite notificaciones list_changed de MCP, permitiendo que los servidores MCP actualicen dinámicamente sus herramientas disponibles, indicaciones y recursos sin requerir que se desconecte y reconecte. Cuando un servidor MCP envía una notificación list_changed, Claude Code actualiza automáticamente las capacidades disponibles de ese servidor.

Reconexión automática

Si un servidor HTTP o SSE se desconecta durante la sesión, Claude Code se reconecta automáticamente con retroceso exponencial: hasta cinco intentos, comenzando con un retraso de un segundo y duplicándose cada vez. El servidor aparece como pendiente en /mcp mientras la reconexión está en progreso. Después de cinco intentos fallidos, el servidor se marca como fallido y puede reintentar manualmente desde /mcp. Los servidores stdio son procesos locales y no se reconectan automáticamente. El mismo retroceso se aplica cuando un servidor HTTP o SSE falla su conexión inicial al iniciar. A partir de v2.1.121, Claude Code reintenta la conexión inicial hasta tres veces en errores transitorios como una respuesta 5xx, una conexión rechazada o un tiempo de espera agotado, luego marca el servidor como fallido si aún no puede conectarse. Los errores de autenticación y no encontrado no se reintentan porque requieren un cambio de configuración para resolverse.

Mensajes push con canales

Un servidor MCP también puede enviar mensajes directamente a su sesión para que Claude pueda reaccionar a eventos externos como resultados de CI, alertas de monitoreo o mensajes de chat. Para habilitar esto, su servidor declara la capacidad claude/channel y usted la activa con la bandera --channels al iniciar. Vea Canales para usar un canal oficialmente soportado, o Referencia de canales para construir el suyo propio.

Consejos:

Use la bandera --scope para especificar dónde se almacena la configuración:
- local (predeterminado): Disponible solo para usted en el proyecto actual (se llamaba project en versiones anteriores)
- project: Compartido con todos en el proyecto a través del archivo .mcp.json
- user: Disponible para usted en todos los proyectos (se llamaba global en versiones anteriores)
Establezca variables de entorno con banderas --env (por ejemplo, --env KEY=value)
Configure el tiempo de espera de inicio del servidor MCP usando la variable de entorno MCP_TIMEOUT (por ejemplo, MCP_TIMEOUT=10000 claude establece un tiempo de espera de 10 segundos)
Claude Code mostrará una advertencia cuando la salida de la herramienta MCP exceda 10,000 tokens. Para aumentar este límite, establezca la variable de entorno MAX_MCP_OUTPUT_TOKENS (por ejemplo, MAX_MCP_OUTPUT_TOKENS=50000)
Use /mcp para autenticarse con servidores remotos que requieren autenticación OAuth 2.0

Servidores MCP proporcionados por plugins

Los plugins pueden agrupar servidores MCP, proporcionando automáticamente herramientas e integraciones cuando el plugin está habilitado. Los servidores MCP de plugins funcionan de manera idéntica a los servidores configurados por el usuario. Cómo funcionan los servidores MCP de plugins:

Los plugins definen servidores MCP en .mcp.json en la raíz del plugin o en línea en plugin.json
Cuando un plugin está habilitado, sus servidores MCP se inician automáticamente
Las herramientas MCP del plugin aparecen junto a las herramientas MCP configuradas manualmente
Los servidores de plugins se gestionan a través de la instalación de plugins (no mediante comandos /mcp)

Ejemplo de configuración MCP de plugin: En .mcp.json en la raíz del plugin:

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

O en línea en plugin.json:

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Características de MCP de plugins:

Ciclo de vida automático: Al iniciar la sesión, los servidores de los plugins habilitados se conectan automáticamente. Si habilita o deshabilita un plugin durante una sesión, ejecute /reload-plugins para conectar o desconectar sus servidores MCP
Variables de entorno: Use ${CLAUDE_PLUGIN_ROOT} para archivos agrupados en el plugin, ${CLAUDE_PLUGIN_DATA} para estado persistente que sobrevive a las actualizaciones de plugins, y ${CLAUDE_PROJECT_DIR} para la raíz del proyecto estable
Acceso a variables de entorno del usuario: Acceso a las mismas variables de entorno que los servidores configurados manualmente
Múltiples tipos de transporte: Soporte para transportes stdio, SSE e HTTP (el soporte de transporte puede variar según el servidor)

Visualización de servidores MCP de plugins:

# Dentro de Claude Code, vea todos los servidores MCP incluyendo los de plugins
/mcp

Los servidores de plugins aparecen en la lista con indicadores que muestran que provienen de plugins. Beneficios de los servidores MCP de plugins:

Distribución agrupada: Herramientas y servidores empaquetados juntos
Configuración automática: No se necesita configuración manual de MCP
Consistencia del equipo: Todos obtienen las mismas herramientas cuando se instala el plugin

Vea la referencia de componentes de plugins para detalles sobre cómo agrupar servidores MCP con plugins.

Alcances de instalación de MCP

Los servidores MCP se pueden configurar en tres alcances. El alcance que elija controla en qué proyectos se carga el servidor y si la configuración se comparte con su equipo. Los administradores también pueden implementar servidores a nivel empresarial a través de configuración administrada.

Alcance	Se carga en	Compartido con equipo	Almacenado en
Local	Solo proyecto actual	No	`~/.claude.json`
Proyecto	Solo proyecto actual	Sí, a través del control de versiones	`.mcp.json` en la raíz del proyecto
Usuario	Todos sus proyectos	No	`~/.claude.json`

Alcance local

El alcance local es el predeterminado. Un servidor con alcance local se carga solo en el proyecto donde lo agregó y permanece privado para usted. Claude Code lo almacena en ~/.claude.json bajo la ruta de ese proyecto, por lo que el mismo servidor no aparecerá en sus otros proyectos. Use el alcance local para servidores de desarrollo personal, configuraciones experimentales o servidores con credenciales que no desea en el control de versiones.

El término “alcance local” para servidores MCP difiere de la configuración local general. Los servidores MCP con alcance local se almacenan en ~/.claude.json (su directorio de inicio), mientras que la configuración local general usa .claude/settings.local.json (en el directorio del proyecto). Vea Configuración para detalles sobre ubicaciones de archivos de configuración.

# Agregar un servidor con alcance local (predeterminado)
claude mcp add --transport http stripe https://mcp.stripe.com

# Especificar explícitamente alcance local
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

El comando escribe el servidor en la entrada de su proyecto actual dentro de ~/.claude.json. El ejemplo a continuación muestra el resultado cuando lo ejecuta desde /path/to/your/project:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

Alcance de proyecto

Los servidores con alcance de proyecto habilitan la colaboración en equipo al almacenar configuraciones en un archivo .mcp.json en el directorio raíz de su proyecto. Este archivo está diseñado para ser verificado en el control de versiones, asegurando que todos los miembros del equipo tengan acceso a las mismas herramientas y servicios MCP. Cuando agrega un servidor con alcance de proyecto, Claude Code crea o actualiza automáticamente este archivo con la estructura de configuración apropiada.

# Agregar un servidor con alcance de proyecto
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

El archivo .mcp.json resultante sigue un formato estandarizado:

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

Por razones de seguridad, Claude Code solicita aprobación antes de usar servidores con alcance de proyecto desde archivos .mcp.json. Si necesita restablecer estas opciones de aprobación, use el comando claude mcp reset-project-choices.

Alcance de usuario

Los servidores con alcance de usuario se almacenan en ~/.claude.json y proporcionan accesibilidad entre proyectos, haciéndolos disponibles en todos los proyectos en su máquina mientras permanecen privados para su cuenta de usuario. Este alcance funciona bien para servidores de utilidad personal, herramientas de desarrollo o servicios que usa frecuentemente en diferentes proyectos.

# Agregar un servidor de usuario
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Jerarquía de alcance y precedencia

Cuando el mismo servidor está definido en más de un lugar, Claude Code se conecta a él una sola vez, usando la definición de la fuente de mayor precedencia:

Alcance local
Alcance de proyecto
Alcance de usuario
Servidores proporcionados por plugins
Conectores de claude.ai

Los tres alcances coinciden duplicados por nombre. Los plugins y conectores coinciden por punto final, por lo que uno que apunta a la misma URL o comando que un servidor anterior se trata como un duplicado.

Expansión de variables de entorno en `.mcp.json`

Claude Code admite la expansión de variables de entorno en archivos .mcp.json, permitiendo que los equipos compartan configuraciones mientras mantienen flexibilidad para rutas específicas de máquinas y valores sensibles como claves API. Sintaxis soportada:

${VAR} - Se expande al valor de la variable de entorno VAR
${VAR:-default} - Se expande a VAR si está establecida, de lo contrario usa default

Ubicaciones de expansión: Las variables de entorno se pueden expandir en:

command - La ruta del ejecutable del servidor
args - Argumentos de línea de comandos
env - Variables de entorno pasadas al servidor
url - Para tipos de servidor HTTP
headers - Para autenticación de servidor HTTP

Ejemplo con expansión de variables:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Si una variable de entorno requerida no está establecida y no tiene un valor predeterminado, Claude Code no podrá analizar la configuración.

Ejemplos prácticos

Ejemplo: Monitorear errores con Sentry

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Autentíquese con su cuenta de Sentry:

/mcp

Luego depure problemas de producción:

¿Cuáles son los errores más comunes en las últimas 24 horas?

Muéstrame el seguimiento de pila para el error ID abc123

¿Qué despliegue introdujo estos nuevos errores?

Ejemplo: Conectar a GitHub para revisiones de código

El servidor MCP remoto de GitHub se autentica con un token de acceso personal de GitHub pasado como encabezado. Para obtener uno, abra su configuración de token de GitHub, genere un nuevo token de grano fino con acceso a los repositorios con los que desea que Claude trabaje, luego agregue el servidor:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

Luego trabaje con GitHub:

Revise el PR #456 y sugiera mejoras

Cree un nuevo problema para el error que acabamos de encontrar

Muéstrame todos los PR abiertos asignados a mí

Ejemplo: Consultar su base de datos PostgreSQL

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

Luego consulte su base de datos de forma natural:

¿Cuál es nuestro ingreso total este mes?

Muéstrame el esquema para la tabla de pedidos

Encuentre clientes que no han realizado una compra en 90 días

Autenticarse con servidores MCP remotos

Muchos servidores MCP basados en la nube requieren autenticación. Claude Code admite OAuth 2.0 para conexiones seguras. Claude Code marca un servidor remoto como que requiere autenticación cuando el servidor responde con 401 Unauthorized o 403 Forbidden. Cualquiera de estos códigos de estado marca el servidor en /mcp para que pueda completar el flujo de OAuth. Un servidor personalizado que devuelve un encabezado WWW-Authenticate que apunta a su servidor de autorización obtiene el mismo descubrimiento automático que cualquier otro servidor remoto.

Agregar el servidor que requiere autenticación

Por ejemplo:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Use el comando /mcp dentro de Claude Code

En Claude Code, use el comando:

/mcp

Luego siga los pasos en su navegador para iniciar sesión.

Consejos:

Los tokens de autenticación se almacenan de forma segura y se actualizan automáticamente
Use “Clear authentication” en el menú /mcp para revocar el acceso
Si su navegador no se abre automáticamente, copie la URL proporcionada y ábrala manualmente
Si el redireccionamiento del navegador falla con un error de conexión después de autenticarse, pegue la URL de devolución de llamada completa de la barra de direcciones de su navegador en el indicador de URL que aparece en Claude Code
La autenticación OAuth funciona con servidores HTTP

Usar un puerto de devolución de llamada OAuth fijo

Algunos servidores MCP requieren un URI de redireccionamiento específico registrado de antemano. De forma predeterminada, Claude Code elige un puerto disponible aleatorio para la devolución de llamada de OAuth. Use --callback-port para fijar el puerto de modo que coincida con un URI de redireccionamiento preregistrado de la forma http://localhost:PORT/callback. Puede usar --callback-port por sí solo (con registro dinámico de clientes) o junto con --client-id (con credenciales preconfiguradas).

# Puerto de devolución de llamada fijo con registro dinámico de clientes
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Usar credenciales OAuth preconfiguradas

Algunos servidores MCP no admiten configuración automática de OAuth mediante Registro Dinámico de Clientes. Si ve un error como “Incompatible auth server: does not support dynamic client registration”, el servidor requiere credenciales preconfiguradas. Claude Code también admite servidores que usan un Documento de Metadatos de ID de Cliente (CIMD) en lugar de Registro Dinámico de Clientes, y los descubre automáticamente. Si el descubrimiento automático falla, registre una aplicación OAuth a través del portal de desarrolladores del servidor primero, luego proporcione las credenciales al agregar el servidor.

Registrar una aplicación OAuth con el servidor

Cree una aplicación a través del portal de desarrolladores del servidor y anote su ID de cliente y secreto de cliente.Muchos servidores también requieren un URI de redireccionamiento. Si es así, elija un puerto y registre un URI de redireccionamiento en el formato http://localhost:PORT/callback. Use ese mismo puerto con --callback-port en el siguiente paso.

Agregar el servidor con sus credenciales

Elija uno de los siguientes métodos. El puerto utilizado para --callback-port puede ser cualquier puerto disponible. Solo necesita coincidir con el URI de redireccionamiento que registró en el paso anterior.

claude mcp add
claude mcp add-json
claude mcp add-json (solo puerto de devolución de llamada)
CI / variable de entorno

Use --client-id para pasar el ID de cliente de su aplicación. La bandera --client-secret solicita el secreto con entrada enmascarada:

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Incluya el objeto oauth en la configuración JSON y pase --client-secret como una bandera separada:

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

Use --callback-port sin un ID de cliente para fijar el puerto mientras usa registro dinámico de clientes:

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

Establezca el secreto a través de una variable de entorno para omitir el indicador interactivo:

MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Autenticarse en Claude Code

Ejecute /mcp en Claude Code y siga el flujo de inicio de sesión del navegador.

Consejos:

El secreto del cliente se almacena de forma segura en su llavero del sistema (macOS) o un archivo de credenciales, no en su configuración
Si el servidor usa un cliente OAuth público sin secreto, use solo --client-id sin --client-secret
--callback-port se puede usar con o sin --client-id
Estas banderas solo se aplican a transportes HTTP y SSE. No tienen efecto en servidores stdio
Use claude mcp get <name> para verificar que las credenciales OAuth estén configuradas para un servidor

Anular el descubrimiento de metadatos de OAuth

Apunte Claude Code a una URL de metadatos de servidor de autorización OAuth específica para omitir la cadena de descubrimiento predeterminada. Establezca authServerMetadataUrl cuando los puntos finales estándar del servidor MCP generen errores, o cuando desee enrutar el descubrimiento a través de un proxy interno. De forma predeterminada, Claude Code primero verifica los Metadatos de Recursos Protegidos RFC 9728 en /.well-known/oauth-protected-resource, luego recurre a los metadatos del servidor de autorización RFC 8414 en /.well-known/oauth-authorization-server. Establezca authServerMetadataUrl en el objeto oauth de la configuración de su servidor en .mcp.json:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

La URL debe usar https://. authServerMetadataUrl requiere Claude Code v2.1.64 o posterior. Los scopes_supported de la URL de metadatos anulan los alcances que el servidor ascendente anuncia.

Restringir alcances de OAuth

Establezca oauth.scopes para fijar los alcances que Claude Code solicita durante el flujo de autorización. Esta es la forma soportada de restringir un servidor MCP a un subconjunto aprobado por el equipo de seguridad cuando el servidor de autorización ascendente anuncia más alcances de los que desea otorgar. El valor es una cadena única separada por espacios, que coincide con el formato del parámetro scope en RFC 6749 §3.3.

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

oauth.scopes tiene precedencia sobre tanto authServerMetadataUrl como los alcances que el servidor descubre en /.well-known. Déjelo sin establecer para permitir que el servidor MCP determine el conjunto de alcances solicitados. Si el servidor de autorización anuncia offline_access en scopes_supported, Claude Code lo añade a los alcances fijados para que el token de acceso pueda actualizarse sin un nuevo inicio de sesión en el navegador. Si el servidor luego devuelve un 403 insufficient_scope para una llamada de herramienta, Claude Code se reautentica con los mismos alcances fijados. Amplíe oauth.scopes cuando una herramienta que necesita requiera un alcance fuera del fijo.

Usar encabezados dinámicos para autenticación personalizada

Si su servidor MCP usa un esquema de autenticación diferente a OAuth (como Kerberos, tokens de corta duración o un SSO interno), use headersHelper para generar encabezados de solicitud en el momento de la conexión. Claude Code ejecuta el comando y fusiona su salida en los encabezados de conexión.

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

El comando también puede ser en línea:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

Requisitos:

El comando debe escribir un objeto JSON de pares clave-valor de cadena en stdout
El comando se ejecuta en un shell con un tiempo de espera de 10 segundos
Los encabezados dinámicos anulan cualquier headers estático con el mismo nombre

El ayudante se ejecuta nuevamente en cada conexión (al iniciar la sesión y al reconectar). No hay almacenamiento en caché, por lo que su script es responsable de cualquier reutilización de tokens. Claude Code establece estas variables de entorno al ejecutar el ayudante:

Variable	Valor
`CLAUDE_CODE_MCP_SERVER_NAME`	el nombre del servidor MCP
`CLAUDE_CODE_MCP_SERVER_URL`	la URL del servidor MCP

Use estas para escribir un único script de ayudante que sirva múltiples servidores MCP.

headersHelper ejecuta comandos de shell arbitrarios. Cuando se define en alcance de proyecto o local, solo se ejecuta después de que acepte el diálogo de confianza del espacio de trabajo.

Agregar servidores MCP desde configuración JSON

Si tiene una configuración JSON para un servidor MCP, puede agregarla directamente:

Agregar un servidor MCP desde JSON

# Sintaxis básica
claude mcp add-json <name> '<json>'

# Ejemplo: Agregar un servidor HTTP con configuración JSON
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Ejemplo: Agregar un servidor stdio con configuración JSON
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Ejemplo: Agregar un servidor HTTP con credenciales OAuth preconfiguradas
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

Verificar que el servidor fue agregado

claude mcp get weather-api

Consejos:

Asegúrese de que el JSON esté correctamente escapado en su shell
El JSON debe cumplir con el esquema de configuración del servidor MCP
Puede usar --scope user para agregar el servidor a su configuración de usuario en lugar de la específica del proyecto

Importar servidores MCP desde Claude Desktop

Si ya ha configurado servidores MCP en Claude Desktop, puede importarlos:

Importar servidores desde Claude Desktop

# Sintaxis básica 
claude mcp add-from-claude-desktop 

Seleccionar qué servidores importar

Después de ejecutar el comando, verá un diálogo interactivo que le permite seleccionar qué servidores desea importar.

Verificar que los servidores fueron importados

claude mcp list

Consejos:

Esta característica solo funciona en macOS y Windows Subsystem for Linux (WSL)
Lee el archivo de configuración de Claude Desktop desde su ubicación estándar en esas plataformas
Use la bandera --scope user para agregar servidores a su configuración de usuario
Los servidores importados tendrán los mismos nombres que en Claude Desktop
Si ya existen servidores con los mismos nombres, obtendrán un sufijo numérico (por ejemplo, server_1)

Usar servidores MCP desde Claude.ai

Si ha iniciado sesión en Claude Code con una cuenta de Claude.ai, los servidores MCP que ha agregado en Claude.ai están automáticamente disponibles en Claude Code:

Configurar servidores MCP en Claude.ai

Agregue servidores en claude.ai/customize/connectors. En planes de Equipo y Empresa, solo los administradores pueden agregar servidores.

Autenticar el servidor MCP

Complete los pasos de autenticación requeridos en Claude.ai.

Ver y gestionar servidores en Claude Code

En Claude Code, use el comando:

/mcp

Los servidores de Claude.ai aparecen en la lista con indicadores que muestran que provienen de Claude.ai.

Un servidor que ha agregado en Claude Code tiene precedencia sobre un conector de claude.ai que apunta a la misma URL. Cuando esto sucede, /mcp enumera el conector como oculto y muestra cómo eliminar el duplicado si prefiere usar el conector. Para desactivar servidores MCP de Claude.ai en Claude Code, establezca la variable de entorno ENABLE_CLAUDEAI_MCP_SERVERS en false:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Usar Claude Code como servidor MCP

Puede usar Claude Code mismo como servidor MCP al que otras aplicaciones pueden conectarse:

# Iniciar Claude como servidor MCP stdio
claude mcp serve

Puede usar esto en Claude Desktop agregando esta configuración a claude_desktop_config.json:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Configurar la ruta del ejecutable: El campo command debe hacer referencia al ejecutable de Claude Code. Si el comando claude no está en el PATH del sistema, deberá especificar la ruta completa al ejecutable.Para encontrar la ruta completa:

which claude

Luego use la ruta completa en su configuración:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Sin la ruta correcta del ejecutable, encontrará errores como spawn claude ENOENT.

Consejos:

El servidor proporciona acceso a las herramientas de Claude como View, Edit, LS, etc.
En Claude Desktop, intente pedirle a Claude que lea archivos en un directorio, haga ediciones y más.
Tenga en cuenta que este servidor MCP solo expone las herramientas de Claude Code a su cliente MCP, por lo que su propio cliente es responsable de implementar la confirmación del usuario para llamadas de herramientas individuales.

Límites de salida de MCP y advertencias

Cuando las herramientas MCP producen salidas grandes, Claude Code ayuda a gestionar el uso de tokens para evitar abrumar el contexto de su conversación:

Umbral de advertencia de salida: Claude Code muestra una advertencia cuando la salida de cualquier herramienta MCP excede 10,000 tokens
Límite configurable: Puede ajustar los tokens de salida MCP máximos permitidos usando la variable de entorno MAX_MCP_OUTPUT_TOKENS
Límite predeterminado: El máximo predeterminado es 25,000 tokens
Alcance: La variable de entorno se aplica a herramientas que no declaran su propio límite. Las herramientas que establecen anthropic/maxResultSizeChars usan ese valor en su lugar para contenido de texto, independientemente de lo que MAX_MCP_OUTPUT_TOKENS esté establecido. Las herramientas que devuelven datos de imagen aún están sujetas a MAX_MCP_OUTPUT_TOKENS

Para aumentar el límite para herramientas que producen salidas grandes:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Esto es particularmente útil cuando se trabaja con servidores MCP que:

Consultan grandes conjuntos de datos o bases de datos
Generan reportes o documentación detallados
Procesan archivos de registro extensos o información de depuración

Aumentar el límite para una herramienta específica

Si está construyendo un servidor MCP, puede permitir que herramientas individuales devuelvan resultados más grandes que el umbral predeterminado de persistencia en disco estableciendo _meta["anthropic/maxResultSizeChars"] en la entrada de la herramienta en la respuesta tools/list. Claude Code aumenta el umbral de esa herramienta al valor anotado, hasta un límite máximo de 500,000 caracteres. Esto es útil para herramientas que devuelven salidas inherentemente grandes pero necesarias, como esquemas de bases de datos o árboles de archivos completos. Sin la anotación, los resultados que exceden el umbral predeterminado se persisten en disco y se reemplazan con una referencia de archivo en la conversación.

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

La anotación se aplica independientemente de MAX_MCP_OUTPUT_TOKENS para contenido de texto, por lo que los usuarios no necesitan aumentar la variable de entorno para herramientas que la declaran. Las herramientas que devuelven datos de imagen aún están sujetas al límite de tokens.

Si frecuentemente encuentra advertencias de salida con servidores MCP específicos que no controla, considere aumentar el límite MAX_MCP_OUTPUT_TOKENS. También puede pedirle al autor del servidor que agregue la anotación anthropic/maxResultSizeChars o que pagine sus respuestas. La anotación no tiene efecto en herramientas que devuelven contenido de imagen; para esas, aumentar MAX_MCP_OUTPUT_TOKENS es la única opción.

Responder a solicitudes de elicitación de MCP

Los servidores MCP pueden solicitar entrada estructurada de usted durante una tarea usando elicitación. Cuando un servidor necesita información que no puede obtener por sí solo, Claude Code muestra un diálogo interactivo y pasa su respuesta de vuelta al servidor. No se requiere configuración de su parte: los diálogos de elicitación aparecen automáticamente cuando un servidor los solicita. Los servidores pueden solicitar entrada de dos formas:

Modo de formulario: Claude Code muestra un diálogo con campos de formulario definidos por el servidor (por ejemplo, un indicador de nombre de usuario y contraseña). Complete los campos y envíe.
Modo de URL: Claude Code abre una URL del navegador para autenticación o aprobación. Complete el flujo en el navegador, luego confirme en la CLI.

Para responder automáticamente a solicitudes de elicitación sin mostrar un diálogo, use el hook Elicitation. Si está construyendo un servidor MCP que usa elicitación, vea la especificación de elicitación de MCP para detalles de protocolo y ejemplos de esquema.

Usar recursos MCP

Los servidores MCP pueden exponer recursos que puede referenciar usando menciones @, similar a cómo referencia archivos.

Referenciar recursos MCP

Listar recursos disponibles

Escriba @ en su indicación para ver los recursos disponibles de todos los servidores MCP conectados. Los recursos aparecen junto a los archivos en el menú de autocompletado.

Referenciar un recurso específico

Use el formato @server:protocol://resource/path para referenciar un recurso:

¿Puede analizar @github:issue://123 y sugerir una solución?

Por favor revise la documentación de API en @docs:file://api/authentication

Múltiples referencias de recursos

Puede referenciar múltiples recursos en una sola indicación:

Compare @postgres:schema://users con @docs:file://database/user-model

Consejos:

Los recursos se obtienen automáticamente e incluyen como adjuntos cuando se referencian
Las rutas de recursos son búsquedas difusas en el autocompletado de menciones @
Claude Code proporciona automáticamente herramientas para listar y leer recursos MCP cuando los servidores los admiten
Los recursos pueden contener cualquier tipo de contenido que proporcione el servidor MCP (texto, JSON, datos estructurados, etc.)

Escalar con MCP Tool Search

Tool Search mantiene el uso de contexto MCP bajo al diferir las definiciones de herramientas hasta que Claude las necesite. Solo los nombres de herramientas se cargan al iniciar la sesión, por lo que agregar más servidores MCP tiene un impacto mínimo en su ventana de contexto.

Cómo funciona

Tool Search está habilitado de forma predeterminada. Las herramientas MCP se difieren en lugar de cargarse en el contexto de antemano, y Claude usa una herramienta de búsqueda para descubrir las relevantes cuando una tarea las necesita. Solo las herramientas que Claude realmente usa entran en el contexto. Desde su perspectiva, las herramientas MCP funcionan exactamente como antes. Si prefiere carga basada en umbral, establezca ENABLE_TOOL_SEARCH=auto para cargar esquemas de antemano cuando se ajusten dentro del 10% de la ventana de contexto y diferir solo el desbordamiento. Vea Configurar búsqueda de herramientas para todas las opciones.

Para autores de servidores MCP

Si está construyendo un servidor MCP, el campo de instrucciones del servidor se vuelve más útil con Tool Search habilitado. Las instrucciones del servidor ayudan a Claude a entender cuándo buscar sus herramientas, similar a cómo funcionan las skills. Agregue instrucciones claras y descriptivas del servidor que expliquen:

Qué categoría de tareas manejan sus herramientas
Cuándo Claude debe buscar sus herramientas
Capacidades clave que proporciona su servidor

Claude Code trunca descripciones de herramientas e instrucciones del servidor en 2KB cada una. Manténgalas concisas para evitar truncamiento, y ponga detalles críticos cerca del inicio.

Configurar búsqueda de herramientas

Tool Search está habilitado de forma predeterminada: las herramientas MCP se difieren y se descubren bajo demanda. Claude Code lo desactiva de forma predeterminada en Vertex AI. También se desactiva cuando ANTHROPIC_BASE_URL apunta a un host que no es de primera parte, ya que la mayoría de los proxies no reenvían bloques tool_reference. Establezca ENABLE_TOOL_SEARCH explícitamente para anular cualquiera de estos comportamientos predeterminados. Tool Search requiere un modelo que admita bloques tool_reference: Sonnet 4 y posterior, u Opus 4 y posterior. Los modelos Haiku no lo admiten. En Vertex AI, Tool Search se admite para Claude Sonnet 4.5 y posterior y Claude Opus 4.5 y posterior. Controle el comportamiento de búsqueda de herramientas con la variable de entorno ENABLE_TOOL_SEARCH:

Valor	Comportamiento
(sin establecer)	Todas las herramientas MCP diferidas y cargadas bajo demanda. Recurre a carga de antemano en Vertex AI o cuando `ANTHROPIC_BASE_URL` es un host que no es de primera parte
`true`	Todas las herramientas MCP diferidas. Claude Code envía el encabezado beta incluso en Vertex AI y a través de proxies. Las solicitudes fallan en modelos de Vertex AI anteriores a Sonnet 4.5 u Opus 4.5, o en proxies que no admiten bloques `tool_reference`
`auto`	Modo de umbral: las herramientas se cargan de antemano si se ajustan dentro del 10% de la ventana de contexto, diferidas de lo contrario
`auto:N`	Modo de umbral con un porcentaje personalizado, donde `N` es 0-100. Por ejemplo, `auto:5` para 5%
`false`	Todas las herramientas MCP cargadas de antemano, sin diferimiento

# Usar un umbral personalizado del 5%
ENABLE_TOOL_SEARCH=auto:5 claude

# Desactivar búsqueda de herramientas completamente
ENABLE_TOOL_SEARCH=false claude

O establezca el valor en su campo env de settings.json. También puede desactivar la herramienta ToolSearch específicamente:

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

Eximir un servidor del diferimiento

Si las herramientas de un servidor deben ser siempre visibles para Claude sin un paso de búsqueda, establezca alwaysLoad en true en la configuración de ese servidor. Cada herramienta de ese servidor se carga entonces en el contexto al iniciar la sesión independientemente de la configuración ENABLE_TOOL_SEARCH. Use esto para un pequeño número de herramientas que Claude necesita en cada turno, ya que cada herramienta de antemano consume contexto que de otro modo estaría disponible para su conversación. La siguiente entrada .mcp.json exime un servidor HTTP mientras deja otros servidores diferidos:

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

El campo alwaysLoad está disponible en todos los tipos de servidor y requiere Claude Code v2.1.121 o posterior. Un servidor MCP también puede marcar herramientas individuales como siempre cargadas incluyendo "anthropic/alwaysLoad": true en el objeto _meta de la herramienta, que tiene el mismo efecto solo para esa herramienta. Establecer alwaysLoad: true también bloquea el inicio hasta que el servidor se conecte, limitado al tiempo de espera de conexión estándar de 5 segundos. Esto se aplica incluso cuando MCP_CONNECTION_NONBLOCKING=1 está establecido, ya que las herramientas deben estar presentes cuando se construye el primer mensaje. Otros servidores aún se conectan en segundo plano cuando el modo no bloqueante está habilitado.

Usar indicaciones MCP como comandos

Los servidores MCP pueden exponer indicaciones que se vuelven disponibles como comandos en Claude Code.

Ejecutar indicaciones MCP

Descubrir indicaciones disponibles

Escriba / para ver todos los comandos disponibles, incluyendo los de servidores MCP. Las indicaciones MCP aparecen con el formato /mcp__servername__promptname.

Ejecutar una indicación sin argumentos

/mcp__github__list_prs

Ejecutar una indicación con argumentos

Muchas indicaciones aceptan argumentos. Páselos separados por espacios después del comando:

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug en flujo de inicio de sesión" high

Consejos:

Las indicaciones MCP se descubren dinámicamente desde servidores conectados
Los argumentos se analizan basándose en los parámetros definidos de la indicación
Los resultados de la indicación se inyectan directamente en la conversación
Los nombres de servidor e indicación se normalizan (los espacios se convierten en guiones bajos)

Configuración MCP gestionada

Para organizaciones que necesitan control centralizado sobre servidores MCP, Claude Code admite dos opciones de configuración:

Control exclusivo con managed-mcp.json: Implemente un conjunto fijo de servidores MCP que los usuarios no pueden modificar ni extender
Control basado en políticas con listas de permitidos/bloqueados: Permita que los usuarios agreguen sus propios servidores, pero restrinja cuáles están permitidos

Estas opciones permiten a los administradores de TI:

Controlar a qué servidores MCP pueden acceder los empleados: Implemente un conjunto estandarizado de servidores MCP aprobados en toda la organización
Prevenir servidores MCP no autorizados: Restrinja a los usuarios de agregar servidores MCP no aprobados
Desactivar MCP completamente: Elimine completamente la funcionalidad MCP si es necesario

Opción 1: Control exclusivo con managed-mcp.json

Cuando implementa un archivo managed-mcp.json, toma control exclusivo sobre todos los servidores MCP. Los usuarios no pueden agregar, modificar ni usar ningún servidor MCP que no esté definido en este archivo. Este es el enfoque más simple para organizaciones que desean control completo. Los administradores del sistema implementan el archivo de configuración en un directorio de todo el sistema:

macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
Linux y WSL: /etc/claude-code/managed-mcp.json
Windows: C:\Program Files\ClaudeCode\managed-mcp.json

Estas son rutas de todo el sistema (no directorios de inicio de usuario como ~/Library/...) que requieren privilegios de administrador. Están diseñadas para ser implementadas por administradores de TI.

El archivo managed-mcp.json usa el mismo formato que un archivo .mcp.json estándar:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.company.com"
      }
    }
  }
}

Opción 2: Control basado en políticas con listas de permitidos y bloqueados

En lugar de tomar control exclusivo, los administradores pueden permitir que los usuarios configuren sus propios servidores MCP mientras aplican restricciones sobre qué servidores están permitidos. Este enfoque usa allowedMcpServers y deniedMcpServers en el archivo de configuración gestionada.

Elegir entre opciones: Use la Opción 1 (managed-mcp.json) cuando desee implementar un conjunto fijo de servidores sin personalización del usuario. Use la Opción 2 (listas de permitidos/bloqueados) cuando desee permitir que los usuarios agreguen sus propios servidores dentro de restricciones de política.

Opciones de restricción

Cada entrada en la lista de permitidos o bloqueados puede restringir servidores de tres formas:

Por nombre de servidor (serverName): Coincide con el nombre configurado del servidor
Por comando (serverCommand): Coincide con el comando exacto y los argumentos utilizados para iniciar servidores stdio
Por patrón de URL (serverUrl): Coincide con URLs de servidor remoto con soporte de comodín

Importante: Cada entrada debe tener exactamente uno de serverName, serverCommand o serverUrl.

Configuración de ejemplo

{
  "allowedMcpServers": [
    // Permitir por nombre de servidor
    { "serverName": "github" },
    { "serverName": "sentry" },

    // Permitir por comando exacto (para servidores stdio)
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },

    // Permitir por patrón de URL (para servidores remotos)
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    // Bloquear por nombre de servidor
    { "serverName": "dangerous-server" },

    // Bloquear por comando exacto (para servidores stdio)
    { "serverCommand": ["npx", "-y", "unapproved-package"] },

    // Bloquear por patrón de URL (para servidores remotos)
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

Cómo funcionan las restricciones basadas en comandos

Coincidencia exacta:

Los arrays de comandos deben coincidir exactamente - tanto el comando como todos los argumentos en el orden correcto
Ejemplo: ["npx", "-y", "server"] NO coincidirá con ["npx", "server"] o ["npx", "-y", "server", "--flag"]

Comportamiento del servidor stdio:

Cuando la lista de permitidos contiene cualquier entrada serverCommand, los servidores stdio deben coincidir con uno de esos comandos
Los servidores stdio no pueden pasar solo por nombre cuando hay restricciones de comando presentes
Esto asegura que los administradores puedan aplicar qué comandos están permitidos ejecutarse

Comportamiento del servidor no-stdio:

Los servidores remotos (HTTP, SSE, WebSocket) usan coincidencia basada en URL cuando existen entradas serverUrl en la lista de permitidos
Si no existen entradas de URL, los servidores remotos recurren a coincidencia basada en nombre
Las restricciones de comando no se aplican a servidores remotos

Cómo funcionan las restricciones basadas en URL

Los patrones de URL admiten comodines usando * para coincidir con cualquier secuencia de caracteres. Esto es útil para permitir dominios completos o subdominios. Ejemplos de comodín:

https://mcp.company.com/* - Permitir todas las rutas en un dominio específico
https://*.example.com/* - Permitir cualquier subdominio de example.com
http://localhost:*/* - Permitir cualquier puerto en localhost

La coincidencia de nombres de host no distingue entre mayúsculas y minúsculas e ignora un punto FQDN final, coincidiendo con la semántica de DNS. Un patrón como *://Mcp.Example.com/* coincide con https://mcp.example.com/api, y https://mcp.example.com. se trata igual que https://mcp.example.com. Los esquemas y rutas permanecen sensibles a mayúsculas y minúsculas. Comportamiento del servidor remoto:

Cuando la lista de permitidos contiene cualquier entrada serverUrl, los servidores remotos deben coincidir con uno de esos patrones de URL
Los servidores remotos no pueden pasar solo por nombre cuando hay restricciones de URL presentes
Esto asegura que los administradores puedan aplicar qué puntos finales remotos están permitidos

Ejemplo: Lista de permitidos solo de URL

{
  "allowedMcpServers": [
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ]
}

Resultado:

Servidor HTTP en https://mcp.company.com/api: ✅ Permitido (coincide con patrón de URL)
Servidor HTTP en https://api.internal.corp/mcp: ✅ Permitido (coincide con subdominio comodín)
Servidor HTTP en https://external.com/mcp: ❌ Bloqueado (no coincide con ningún patrón de URL)
Servidor stdio con cualquier comando: ❌ Bloqueado (sin entradas de nombre o comando para coincidir)

Ejemplo: Lista de permitidos solo de comando

{
  "allowedMcpServers": [
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

Resultado:

Servidor stdio con ["npx", "-y", "approved-package"]: ✅ Permitido (coincide con comando)
Servidor stdio con ["node", "server.js"]: ❌ Bloqueado (no coincide con comando)
Servidor HTTP llamado “my-api”: ❌ Bloqueado (sin entradas de nombre para coincidir)

Ejemplo: Lista de permitidos mixta de nombre y comando

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

Resultado:

Servidor stdio llamado “local-tool” con ["npx", "-y", "approved-package"]: ✅ Permitido (coincide con comando)
Servidor stdio llamado “local-tool” con ["node", "server.js"]: ❌ Bloqueado (existen entradas de comando pero no coincide)
Servidor stdio llamado “github” con ["node", "server.js"]: ❌ Bloqueado (los servidores stdio deben coincidir con comandos cuando existen entradas de comando)
Servidor HTTP llamado “github”: ✅ Permitido (coincide con nombre)
Servidor HTTP llamado “other-api”: ❌ Bloqueado (el nombre no coincide)

Ejemplo: Lista de permitidos solo de nombre

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "internal-tool" }
  ]
}

Resultado:

Servidor stdio llamado “github” con cualquier comando: ✅ Permitido (sin restricciones de comando)
Servidor stdio llamado “internal-tool” con cualquier comando: ✅ Permitido (sin restricciones de comando)
Servidor HTTP llamado “github”: ✅ Permitido (coincide con nombre)
Cualquier servidor llamado “other”: ❌ Bloqueado (el nombre no coincide)

Comportamiento de la lista de permitidos (`allowedMcpServers`)

undefined (predeterminado): Sin restricciones - los usuarios pueden configurar cualquier servidor MCP
Array vacío []: Bloqueo completo - los usuarios no pueden configurar ningún servidor MCP
Lista de entradas: Los usuarios solo pueden configurar servidores que coincidan por nombre, comando o patrón de URL

Comportamiento de la lista de bloqueados (`deniedMcpServers`)

undefined (predeterminado): Ningún servidor está bloqueado
Array vacío []: Ningún servidor está bloqueado
Lista de entradas: Los servidores especificados están explícitamente bloqueados en todos los alcances

Notas importantes

La Opción 1 y la Opción 2 se pueden combinar: Si existe managed-mcp.json, tiene control exclusivo y los usuarios no pueden agregar servidores. Las listas de permitidos/bloqueados aún se aplican a los servidores gestionados mismos.
La lista de bloqueados tiene precedencia absoluta: Si un servidor coincide con una entrada de lista de bloqueados (por nombre, comando o URL), será bloqueado incluso si está en la lista de permitidos
Las restricciones basadas en nombre, comando y URL funcionan juntas: un servidor pasa si coincide con cualquiera de una entrada de nombre, una entrada de comando o un patrón de URL (a menos que esté bloqueado por lista de bloqueados)

Cuando se usa managed-mcp.json: Los usuarios no pueden agregar servidores MCP a través de claude mcp add o archivos de configuración. La configuración allowedMcpServers y deniedMcpServers aún se aplica para filtrar qué servidores gestionados se cargan realmente.

Agentes y trabajo paralelo

Herramientas y plugins

Automatización

Solución de problemas

Documentation Index

​Qué puede hacer con MCP

​Buscar y crear servidores MCP

​Instalación de servidores MCP

​Opción 1: Agregar un servidor HTTP remoto

​Opción 2: Agregar un servidor SSE remoto

​Opción 3: Agregar un servidor stdio local

​Gestión de sus servidores

​Actualizaciones dinámicas de herramientas

​Reconexión automática

​Mensajes push con canales

​Servidores MCP proporcionados por plugins

​Alcances de instalación de MCP

​Alcance local

​Alcance de proyecto

​Alcance de usuario

​Jerarquía de alcance y precedencia

​Expansión de variables de entorno en .mcp.json

​Ejemplos prácticos

​Ejemplo: Monitorear errores con Sentry

​Ejemplo: Conectar a GitHub para revisiones de código

​Ejemplo: Consultar su base de datos PostgreSQL

​Autenticarse con servidores MCP remotos

​Usar un puerto de devolución de llamada OAuth fijo

​Usar credenciales OAuth preconfiguradas

​Anular el descubrimiento de metadatos de OAuth

​Restringir alcances de OAuth

​Usar encabezados dinámicos para autenticación personalizada

​Agregar servidores MCP desde configuración JSON

​Importar servidores MCP desde Claude Desktop

​Usar servidores MCP desde Claude.ai

​Usar Claude Code como servidor MCP

​Límites de salida de MCP y advertencias

​Aumentar el límite para una herramienta específica

​Responder a solicitudes de elicitación de MCP

​Usar recursos MCP

​Referenciar recursos MCP

​Escalar con MCP Tool Search

​Cómo funciona

​Para autores de servidores MCP

​Configurar búsqueda de herramientas

​Eximir un servidor del diferimiento

​Usar indicaciones MCP como comandos

​Ejecutar indicaciones MCP

​Configuración MCP gestionada

​Opción 1: Control exclusivo con managed-mcp.json

​Opción 2: Control basado en políticas con listas de permitidos y bloqueados

​Opciones de restricción

​Configuración de ejemplo

​Cómo funcionan las restricciones basadas en comandos

​Cómo funcionan las restricciones basadas en URL

​Comportamiento de la lista de permitidos (allowedMcpServers)

​Comportamiento de la lista de bloqueados (deniedMcpServers)

​Notas importantes

Qué puede hacer con MCP

Buscar y crear servidores MCP

Instalación de servidores MCP

Opción 1: Agregar un servidor HTTP remoto

Opción 2: Agregar un servidor SSE remoto

Opción 3: Agregar un servidor stdio local

Gestión de sus servidores

Actualizaciones dinámicas de herramientas

Reconexión automática

Mensajes push con canales

Servidores MCP proporcionados por plugins

Alcances de instalación de MCP

Alcance local

Alcance de proyecto

Alcance de usuario

Jerarquía de alcance y precedencia

Expansión de variables de entorno en `.mcp.json`

Ejemplos prácticos

Ejemplo: Monitorear errores con Sentry

Ejemplo: Conectar a GitHub para revisiones de código

Ejemplo: Consultar su base de datos PostgreSQL

Autenticarse con servidores MCP remotos

Usar un puerto de devolución de llamada OAuth fijo

Usar credenciales OAuth preconfiguradas

Anular el descubrimiento de metadatos de OAuth

Restringir alcances de OAuth

Usar encabezados dinámicos para autenticación personalizada

Agregar servidores MCP desde configuración JSON

Importar servidores MCP desde Claude Desktop

Usar servidores MCP desde Claude.ai

Usar Claude Code como servidor MCP

Límites de salida de MCP y advertencias

Aumentar el límite para una herramienta específica

Responder a solicitudes de elicitación de MCP

Usar recursos MCP

Referenciar recursos MCP

Escalar con MCP Tool Search

Cómo funciona

Para autores de servidores MCP

Configurar búsqueda de herramientas

Eximir un servidor del diferimiento

Usar indicaciones MCP como comandos

Ejecutar indicaciones MCP

Configuración MCP gestionada

Opción 1: Control exclusivo con managed-mcp.json

Opción 2: Control basado en políticas con listas de permitidos y bloqueados

Opciones de restricción

Configuración de ejemplo

Cómo funcionan las restricciones basadas en comandos

Cómo funcionan las restricciones basadas en URL

Comportamiento de la lista de permitidos (`allowedMcpServers`)

Comportamiento de la lista de bloqueados (`deniedMcpServers`)

Notas importantes