MCP (Protocolo modelo de contexto)

Esta carpeta contiene documentación completa y ejemplos para configuraciones de servidores MCP y su uso con Claude Code.

Introducción

MCP (Model Context Protocol) es una forma estandarizada para que Claude acceda a herramientas externas, API y fuentes de datos en tiempo real. A diferencia de Memory, MCP ofrece acceso en vivo a datos cambiantes.

Características clave: - Acceso en tiempo real a servicios externos - Sincronización de datos en vivo - Arquitectura amplia - Autenticación segura - Interacciones basadas en herramientas

MCP Architecture

graph TB
    A["Claude"]
    B["Servidor MCP"]
    C["Servicio externo"]

    A -->|Solicitud: list_issues| B
    B -->|Query| C
    C -->|Data| B
    B -->|Response| A

    A -->|Solicitud: create_issue| B
    B -->|Action| C
    C -->|Result| B
    B -->|Response| A

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#f3e5f5,stroke:#333,color:#333
    style C fill:#e8f5e9,stroke:#333,color:#333

Ecosistema MCP

graph TB
    A["Claude"] -->|MCP| B["Sistema de archivos<br/>Servidor MCP"]
    A -->|MCP| C["GitHub<br/>Servidor MCP"]
    A -->|MCP| D["Base de datos<br/>Servidor MCP"]
    A -->|MCP| E["Slack<br/>Servidor MCP"]
    A -->|MCP| F["Google Docs<br/>Servidor MCP"]

    B -->|Archivo E/S| G["Archivos locales"]
    C -->|API| H["GitHub Repos"]
    D -->|Query| I["PostgreSQL/MySQL"]
    E -->|Messages| J["Espacio de trabajo de Slack"]
    F -->|Docs| K["Google Drive"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#f3e5f5,stroke:#333,color:#333
    style C fill:#f3e5f5,stroke:#333,color:#333
    style D fill:#f3e5f5,stroke:#333,color:#333
    style E fill:#f3e5f5,stroke:#333,color:#333
    style F fill:#f3e5f5,stroke:#333,color:#333
    style G fill:#e8f5e9,stroke:#333,color:#333
    style H fill:#e8f5e9,stroke:#333,color:#333
    style I fill:#e8f5e9,stroke:#333,color:#333
    style J fill:#e8f5e9,stroke:#333,color:#333
    style K fill:#e8f5e9,stroke:#333,color:#333

Métodos de instalación MCP

Claude Code admite múltiples protocolos de transporte para conexiones de servidor MCP:

Transporte HTTP (recomendado)

# Basic HTTP connection
claude mcp add --transport http notion https://mcp.notion.com/mcp

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

Stdio Transporte (local)

Para los servidores MCP en ejecución local:

# Local Node.js server
claude mcp add --transport stdio myserver -- npx @myorg/mcp-server

# With environment variables
claude mcp add --transport stdio myserver --env KEY=value -- npx server

CLAUDE_PROJECT_DIR para servidores stdio (v2.1.139+)

Cada servidor de stdio MCP se genera con CLAUDE_PROJECT_DIR=<absolute path to repo root> ya instalado en su entorno, la misma convención utilizada para los hooks. Plugin y proyecto .mcp.json archivos pueden hacer referencia ${CLAUDE_PROJECT_DIR} en la ventana command, args, y env valores, y la sustitución ocurre antes execve():

{
  "mcpServers": {
    "repo-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR:-.}/.claude/mcp/repo-tools.js"],
      "env": {
        "REPO_ROOT": "${CLAUDE_PROJECT_DIR:-.}"
      }
    }
  }
}

Nota: En proyectos, configuraciones locales y de usuario, escriba ${CLAUDE_PROJECT_DIR:-.} con un valor predeterminado: la variable se establece en el entorno del servidor, no en el propio Claude Code. ${CLAUDE_PROJECT_DIR} directamente.

Use esto cuando su servidor stdio necesite leer archivos relativos a la raíz del proyecto independientemente de dónde se haya lanzado Claude Code.

Los servidores MCP de stdio también reciben CLAUDE_CODE_SESSION_ID (combinando el valor pasado a hooks y Bash), incluyendo cuando la sesión se reanuda con --resume (v2.1.163+).

Transporte SSE (depreciado)

Servidor-Enviar Eventos de transporte es obsoleto en favor de http pero todavía apoyado:

claude mcp add --transport sse legacy-server https://example.com/sse

Transporte WebSocket (ws)

Los servidores WebSocket mantienen una conexión bidireccional persistente, que se adapta a los servidores MCP remotos que empujan eventos a Claude sin preaviso. Utilice HTTP en su lugar cuando su servidor sólo responde a las peticiones, ya que HTTP soporta OAuth y el claude mcp add --transport bandera, mientras que WebSocket no soporta ninguno de los dos.

Porque --transport no acepta ws, configurarlo en .mcp.json o a través claude mcp add-json:

{
  "type": "ws",
  "url": "wss://mcp.example.com/socket",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}

Los type: "ws" la entrada acepta el mismo url, headers, headersHelper, timeout, y alwaysLoad campos como http. La autenticación es solo encabezado — no hay flujo OAuth para servidores WebSocket.

NotaDesde el v2.1.285, claude mcp list WebSocket (ws) servidores con su URL y estado de salud (las versiones anteriores los dejaron fuera). claude mcp get <name> o la /mcp panel.

Al igual que HTTP y SSE, las conexiones WebSocket utilizan una ventana de 5 minutos de inactividad; stdio y WebSocket no tienen temporizador por petición. A url entrada sin type es un nombre de error "http", "sse", y "ws" como valores válidos.

Directorios de trabajo de la sesión (raíz/lista)

Los servidores MCP pueden descubrir los directorios de trabajo de la sesión: el directorio de lanzamiento más todos --add-dir/additionalDirectories las entradas se devuelven a través del MCP roots/list solicitud, y una notifications/roots/list_changed la notificación se envía siempre que el conjunto cambie (v2.1.203). El tiempo de inactividad ahora también se aplica a los servidores stdio (30 minutos), con un servidor por servidor timeout actuando como un suelo inactivo (v2.1.203).

Nota específica para Windows

En Windows nativas (no WSL), use cmd /c para comandos npx:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Autenticación OAuth 2.0

Claude Code admite OAuth 2.0 para servidores MCP que lo requieran. Al conectarse a un servidor habilitado para OAuth, Claude Code maneja todo el flujo de autenticación:

# Connect to an OAuth-enabled MCP server (interactive flow)
claude mcp add --transport http my-service https://my-service.example.com/mcp

# Pre-configure OAuth credentials for non-interactive setup
claude mcp add --transport http my-service https://my-service.example.com/mcp \
  --client-id "your-client-id" \
  --client-secret "your-client-secret" \
  --callback-port 8080

Descubrimiento de metadatos OAuth

Si su servidor MCP devuelve errores en el parámetro estándar de metadatos OAuth (/.well-known/oauth-authorization-server) pero expone un endpoint OIDC en funcionamiento, puede decirle a Claude Code que obtenga metadatos OAuth de una URL específica. authServerMetadataUrl en la ventana oauth objeto de la configuración del servidor:

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

El URL debe usarse https://. Esta opción requiere Claude Code v2.1.64 o posterior.

Aviso de inicio de autenticación y actualización de cabeza dinámica (v2.1.193)

• Aviso de autenticación de inicio (v2.1.193+): Al inicio, Claude Code presenta un aviso en el que se enumeran los servidores MCP que todavía necesitan autenticación, por lo que un servidor que necesita un inicio de sesión no se deja sin funcionar en silencio.
• headersHelper auto-refrescar (v2.1.193+): Si usted suministra auth personalizado vía un headersHelper, el ayudante se vuelve a llamar automáticamente cuando un servidor devuelve HTTP 401 o 403. Las credenciales se actualizan al vuelo sin una reconexión manual. Ver Usar encabezados dinámicos para autenticación personalizada.

Aviso (v2.1.238): A headersHelper en un proyecto .mcp.json, y servidores MCP en línea en proyecto o --add-dir archivos de agente, ahora requieren que el diálogo de confianza de esa carpeta haya sido aceptado, incluyendo claude -p. Tales ayudantes también funcionan sin variables de entorno de credencial heredadas; los ayudantes de usuario, manejado y claude.ai-scope se ejecutan desde el directorio de configuración de Claude. Una configuración de proyecto que se basó en credenciales heredadas o en la ejecución no confiable dejará de funcionar hasta que acepte el diálogo de confianza y proporcione credenciales de otra manera.

Conectores MCP Claude.ai

Los servidores MCP configurados en su cuenta de Claude.ai están disponibles automáticamente en Claude Code. Esto significa que cualquier conexión MCP que haya configurado a través de la interfaz web de Claude.ai será accesible sin configuración adicional.

Los conectores MCP Claude.ai también están disponibles en --print modo (v2.1.83+), permitiendo el uso no interactivo y con scripts.

Nota de inicio (v2.1.117+): La conexión concurrente es la predeterminada cuando se configuran servidores MCP tanto locales como claude.ai (anteriormente serial), reduciendo la latencia de inicio cuando se utilizan varios servidores.

Para deshabilitar los servidores MCP de Claude.ai en Claude Code, establezca la ENABLE_CLAUDEAI_MCP_SERVERS variable de entorno a false:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Nota: Esta función solo está disponible para usuarios que hayan iniciado sesión con cuentas de Claude.ai.

Proceso de configuración de MCP

sequenceDiagram
    participant User
    participant Claude as Claude Code
    participant Config as Config File
    participant Service as External Service

    User->>Claude: Type /mcp
    Claude->>Claude: List available MCP servers
    Claude->>User: Show options
    User->>Claude: Select GitHub MCP
    Claude->>Config: Update configuration
    Config->>Claude: Activate connection
    Claude->>Service: Test connection
    Service-->>Claude: Authentication successful
    Claude->>User: ✅ MCP connected!

/mcp comando

Tipo /mcp dentro de una sesión para listar servidores conectados, activar flujos OAuth e inspeccionar el estado de conexión.

• Desde v2.1.121, MCP vuelve a introducir la conexión inicial hasta 3 veces en errores transitorios.
• Desde v2.1.128, /mcp muestra la conteo de herramientas para cada servidor conectado y visualmente banderas de servidores informando 0 herramientas así que servidores mal configurados se destacan de un vistazo.

Búsqueda de herramientas MCP

La búsqueda de herramientas está activada por defecto: las herramientas MCP son diferidas y descubiertas bajo demanda, por lo que sus definiciones no llenan el contexto del modelo. ANTHROPIC_BASE_URL puerta de entrada, que debe defer_loading campos de herramientas y tool_reference bloques; desde v2.1.305 Claude Code retoma una solicitud que la pasarela rechaza con una búsqueda de 400 o 422 sin herramienta. ENABLE_TOOL_SEARCH=false para cargar cada herramienta por adelantado y omitir las solicitudes rechazadas. Antes de v2.1.304, la búsqueda de herramientas estaba fuera detrás de una puerta de enlace a menos que ENABLE_TOOL_SEARCH era true, autoo bien auto:N.

Nota: La búsqueda de herramientas requiere un modelo que soporte tool_reference bloques: Claude Opus 4, Claude Sonnet 4, Claude Haiku 4.5, y modelos posteriores (Opus 4.5, Sonnet 4.5, Haiku 4.5 y más tarde en la plataforma de agente de Google Cloud).

Búsqueda de herramienta de bypassing por servidor (v2.1.121+)

Si se necesitan las herramientas de un servidor MCP en cada turno, marque su configuración con "alwaysLoad": true omitir el aplazamiento de la búsqueda de herramientas y mantener sus herramientas siempre disponibles:

{
  "mcpServers": {
    "always-on-tool": {
      "command": "node",
      "args": ["./tools/always.js"],
      "alwaysLoad": true
    }
  }
}

Use con moderación — cada herramienta siempre cargada consume contexto que de otro modo podría ser utilizado para la búsqueda de herramientas para sacar a la superficie una herramienta más relevante.

Para mantener todas las herramientas de un servidor detrás de la búsqueda de herramientas, establecer "alwaysLoad": false en la entrada de ese servidor (v2.1.287+). Esto incluye las herramientas que el autor del servidor ha marcado para cargar por adelantado; si sale alwaysLoad fuera, esas herramientas marcadas cargan por delante. Los autores del servidor marcan una herramienta individual al establecer "anthropic/alwaysLoad" en el de esa herramienta _meta objeto, y el nivel del servidor alwaysLoad configurarlo en su configuración puede anularlo.

Autores del servidor: marque las herramientas que son seguras de llamar dos veces con el idempotentHint o readOnlyHint anotación en su tools/list desde v2.1.307, Claude Code repite una llamada que estaba pendiente cuando una conexión HTTP o claude.ai conector cerrado sólo para esas herramientas; otras llamadas fallan con connection closed before the tool call was answered.

Actualizaciones dinámicas de herramientas

Claude Code admite MCP list_changed notificaciones. Cuando un servidor MCP añade, elimina o modifica dinámicamente sus herramientas disponibles, Claude Code recibe la actualización y ajusta su lista de herramientas automáticamente; no se requiere reconexión ni reinicio.

Aplicaciones MCP

MCP Apps es la primera extensión oficial de MCP, lo que permite que las llamadas a la herramienta MCP devuelvan componentes interactivos de interfaz de usuario que se renderizan directamente en la interfaz de chat. En lugar de respuestas de texto simples, los servidores MCP pueden entregar paneles de control, formularios, visualizaciones de datos y flujos de trabajo de múltiples pasos, todos ellos mostrados en línea sin salir de la conversación.

MCP Elicitation

Los servidores MCP pueden solicitar información estructurada del usuario a través de diálogos interactivos (v2.1.49+). Esto permite que un servidor MCP solicite información adicional en medio flujo de trabajo, por ejemplo, solicitando una confirmación, seleccionando de una lista de opciones o rellenando los campos requeridos, añadiendo interactividad a las interacciones del servidor MCP.

Descripción de la herramienta y tapa de instrucción

Claude Code trunca cada descripción de la herramienta MCP y las instrucciones de cada servidor para mantener los servidores verbose del contexto hinchado. 4,096 caracteres para las instrucciones del servidor y para las descripciones de las herramientas que se cargan por adelantado (v2.1.296; 2.048 desde v2.1.84 hasta entonces), y 16.384 caracteres para descripciones Claude carga a través de la búsqueda de herramientas (v2.1.295), desde v2.1.280, CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH los anula: el número que se establece reemplaza ambos límites (8192 Desde v2.1.299, descripciones e instrucciones de los servidores MCP de Anthropic api.anthropic.com Claude en su totalidad. Ponga los detalles críticos cerca del comienzo de una descripción.

MCP Prompts como comandos de barra

Los servidores MCP pueden exponer los avisos que aparecen como comandos de barra en Claude Code. Los anuncios son accesibles utilizando la convención de nombres:

/mcp__<server>__<prompt>

Por ejemplo, si un servidor llamado github expone un aviso llamado review, usted puede invocarlo como /mcp__github__review.

Deduplicación del servidor

Cuando el mismo servidor MCP se define en múltiples ámbitos (local, proyecto, usuario), la configuración local tiene prioridad. Esto le permite anular la configuración MCP a nivel de proyecto o de usuario con personalizaciones locales sin conflictos.

Recientes fijaciones del ciclo de vida (v2.1.136)

Se han corregido dos fallos de larga data del ciclo de vida MCP en v2.1.136, por lo que vale la pena actualizarlos si ejecuta configuraciones multiservidor:

• Los servidores MCP persisten en todos /clear: Servidores configurados a través .mcp.json, plugins o conectores claude.ai ya no desaparecen después /clear en código VS, JetBrains, o el agente SDK. Versiones anteriores silenciosamente los dejó caer y requirió un reinicio.
• Solución OAuth de refresco-token concurrente-refresh: Las configuraciones de múltiples servidores OAuth ya no pierden tokens de actualización cuando varios servidores corren para actualizarse simultáneamente. Esto elimina el patrón "cada mañana tengo que volver a aautar" que afectó a las configuraciones con múltiples servidores MCP protegidos por OAuth.

Recursos MCP vía @ Menciones

Puede hacer referencia a los recursos MCP directamente en sus consultas utilizando el @ mencionar sintaxis:

@server-name:protocol://resource/path

Por ejemplo, para hacer referencia a un recurso de base de datos específico:

@database:postgres://mydb/users

Esto permite a Claude obtener e incluir contenido de recursos MCP en línea como parte del contexto de conversación.

Ámbitos de aplicación del MCP

Las configuraciones de MCP se pueden almacenar en diferentes ámbitos con diferentes niveles de intercambio:

Seleccione un alcance al añadir un servidor con --scope (forma corta) -s) Omitirlo y utilizar Claude Code local:

# Project scope — writes to .mcp.json so the team shares it
claude mcp add --scope project --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"

# User scope — available in every project
claude mcp add --scope user --transport stdio memory -- npx @modelcontextprotocol/server-memory

Uso del alcance del proyecto

Almacenar las configuraciones MCP específicas del proyecto en .mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

Los miembros del equipo verán una solicitud de aprobación sobre el primer uso de MCPs de proyecto. En un espacio de trabajo no confiable, los servidores que un repo auto-aprobado a través de un comprometido .claude/settings.json son no auto-espaciado por claude mcp list/get — se muestran ⏸ Pending approval hasta que acepte el diálogo de confianza, y enableAllProjectMcpServers se ignora en una carpeta no confiable (v2.1.196).

Gestión de configuración MCP

Añadir servidores MCP

# Add HTTP-based server
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"

# Add local stdio server
claude mcp add --transport stdio database -- npx @company/db-server

# List all MCP servers
claude mcp list

# Get details on specific server
claude mcp get github

# Remove an MCP server
claude mcp remove github

# Reset project-specific approval choices
claude mcp reset-project-choices

# Authenticate an MCP server from the CLI (v2.1.186+)
claude mcp login github

# Sign out of an MCP server (v2.1.186+)
claude mcp logout github

# Import from Claude Desktop
claude mcp add-from-claude-desktop

# Add a server from a JSON blob (useful for scripted setup)
claude mcp add-json events-server '{"type":"stdio","command":"npx","args":["@modelcontextprotocol/server-events"]}'

Nota: En las configuraciones de JSON — .mcp.json, ~/.claude.jsono bien claude mcp add-json — los type campo acepta streamable-http como alias para http. La especificación MCP utiliza el nombre streamable-http para este transporte, por lo que las configuraciones copiadas de un trabajo de documentación propia de un servidor no modificado.

Desde el v2.1.238, claude mcp list y claude mcp get mostrar servidores desactivados como ⊘ Disabled sin conectarse con ellos para un chequeo médico.

claude mcp login <name> / claude mcp logout <name> son el equivalente no interactivo del flujo de OAuth en el /mcp menú — autenticar o cerrar sesión sin abrirlo. Añadir --no-browser a login para completar OAuth sobre SSH o en una sesión sin interfaz (reorienta el flujo a través de stdin).

Tabla de servidores MCP disponibles

Ejemplos prácticos

Ejemplo 1: Configuración de GitHub MCP

Archivo: .mcp.json (raíz del proyecto)

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

Herramientas disponibles de GitHub MCP:

Gestión de solicitudes

• list_prs - Listar todas las relaciones públicas en el repositorio
• get_pr - Obtenga detalles de relaciones públicas incluyendo diff
• create_pr - Crear nuevas relaciones públicas
• update_pr - Actualizar la descripción/título de PR
• merge_pr - Fusionar PR a la rama principal
• review_pr - Añadir comentarios de revisión

Solicitud de ejemplo:

/mcp__github__get_pr 456

# Returns:
Title: Add dark mode support
Author: @alice
Description: Implements dark theme using CSS variables
Status: OPEN
Reviewers: @bob, @charlie

Gestión de problemas

• list_issues - Enumerar todos los temas
• get_issue - Obtener detalles del problema
• create_issue - Crear un nuevo problema
• close_issue - Es un asunto cerrado.
• add_comment - Añadir comentario a la edición

Información del repositorio

• get_repo_info - Detalles del repositorio
• list_files - Estructura del árbol de archivos
• get_file_content - Leer el contenido del archivo
• search_code - Buscar en la base de código

Operaciones de comisión

• list_commits - Enviando historia
• get_commit - Detalles específicos del compromiso
• create_commit - Crear un nuevo commit

Configuración:

export GITHUB_PERSONAL_ACCESS_TOKEN="your_github_token"
# Or use the CLI to add directly:
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"

Expansión de Variables de Entorno en Configuración

Las configuraciones de MCP soportan la expansión variable del entorno con los valores predeterminados de reserva. ${VAR} y ${VAR:-default} la sintaxis funciona en los siguientes campos: command, args, env, url, y headers.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}",
        "X-Custom-Header": "${CUSTOM_HEADER:-default-value}"
      }
    },
    "local-server": {
      "command": "${MCP_BIN_PATH:-npx}",
      "args": ["${MCP_PACKAGE:-@company/mcp-server}"],
      "env": {
        "DB_URL": "${DATABASE_URL:-postgresql://localhost/dev}"
      }
    }
  }
}

Las variables se expanden en tiempo de ejecución: - ${VAR} - Utiliza la variable de entorno; si no está configurada (y no tiene valor predeterminado), el servidor todavía carga con el literal ${VAR}, y claude mcp list y /mcp advertir sobre la variable que falta - ${VAR:-default} - Utiliza la variable de entorno, vuelve a ser predeterminada si no se establece

Ejemplo 2: Configuración de la base de datos MCP

Configuración:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
    }
  }
}

Ejemplo de uso:

User: Fetch all users with more than 10 orders

Claude: I'll query your database to find that information.

# Using MCP database tool:
SELECT u.*, COUNT(o.id) as order_count
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.id
HAVING COUNT(o.id) > 10
ORDER BY order_count DESC;

# Results:
- Alice: 15 orders
- Bob: 12 orders
- Charlie: 11 orders

Configuración:

export DATABASE_URL="postgresql://user:pass@localhost/mydb"
claude mcp add --transport stdio database -- npx -y @bytebase/dbhub \
  --dsn "$DATABASE_URL"

Aviso: Esta configuración le da a Claude acceso de escritura. DBHub execute_sql herramienta ejecuta cualquier SQL que recibe, incluyendo UPDATE, DELETE, y DROP, a menos que active el modo de sólo lectura. Utilice una base de datos local o de lanzamiento, nunca la producción.

Configuración de solo lectura (recomendada):

Crear un usuario de base de datos que solo puede ejecutarse SELECT (Ejemplo PostgreSQL):

CREATE ROLE claude_readonly LOGIN PASSWORD 'change-me';
GRANT CONNECT ON DATABASE mydb TO claude_readonly;
GRANT USAGE ON SCHEMA public TO claude_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;

Activar el modo de solo lectura en una dbhub.toml. El viejo --readonly bandera ya no funciona. DBHub rellena ${DATABASE_URL} de su entorno, por lo que no hay credenciales en el archivo:

[[sources]]
id = "default"
dsn = "${DATABASE_URL}"

[[tools]]
name = "execute_sql"
source = "default"
readonly = true

A continuación, señalar DBHub en el archivo en lugar de pasar --dsn. Eliminar el acceso de escritura database servidor que usted agregó anteriormente primero, porque Claude Code no añadirá un segundo servidor con el mismo nombre:

# Replace the write-access server added above
claude mcp remove database
export DATABASE_URL="postgresql://claude_readonly:change-me@localhost/mydb"
claude mcp add --transport stdio database -- npx -y @bytebase/dbhub \
  --config "$PWD/dbhub.toml"

El modo de sólo lectura filtra texto SQL y ha tenido bypasses en el pasado (fijado en DBHub 0.22.6), por lo que la SELECT-sólo el usuario es lo que realmente protege sus datos. Ver Modo de sólo lectura DBHub.

Ejemplo 3: Flujo de trabajo multi-MCP

Escenario: Generación de Informes Diarios

# Daily Report Workflow using Multiple MCPs

## Setup
1. GitHub MCP - fetch PR metrics
2. Database MCP - query sales data
3. Slack MCP - post report
4. Filesystem MCP - save report

## Workflow

### Step 1: Fetch GitHub Data
/mcp__github__list_prs completed:true last:7days

Output:
- Total PRs: 42
- Average merge time: 2.3 hours
- Review turnaround: 1.1 hours

### Step 2: Query Database
SELECT COUNT(*) as sales, SUM(amount) as revenue
FROM orders
WHERE created_at > NOW() - INTERVAL '1 day'

Output:
- Sales: 247
- Revenue: $12,450

### Step 3: Generate Report
Combine data into HTML report

### Step 4: Save to Filesystem
Write report.html to /reports/

### Step 5: Post to Slack
Send summary to #daily-reports channel

Final Output:
✅ Report generated and posted
📊 47 PRs merged this week
💰 $12,450 in daily sales

Configuración:

export GITHUB_PERSONAL_ACCESS_TOKEN="your_github_token"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_BOT_TOKEN="your_slack_bot_token"
export SLACK_TEAM_ID="your_slack_team_id"
# Add each MCP server via the CLI or configure them in .mcp.json

Ejemplo 4: Operaciones MCP del sistema de archivos

Configuración:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

Operaciones disponibles:

Configuración:

# Use the CLI to add directly:
claude mcp add --transport stdio filesystem -- npx @modelcontextprotocol/server-filesystem /home/user/projects

MCP vs Memoria: Matriz de Decisión

graph TD
    A["¿Necesita datos externos?"]
    A -->|No| B["Usar memoria"]
    A -->|Yes| C["¿Cambia con frecuencia?"]
    C -->|No/Rarely| B
    C -->|Yes/Often| D["Usar MCP"]

    B -->|Stores| E["Preferencias<br/>Contexto<br/>Histórico"]
    D -->|Accesses| F["APIs en vivo<br/>Bases de datos<br/>Servicios"]

    style A fill:#fff3e0,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#fff3e0,stroke:#333,color:#333
    style D fill:#f3e5f5,stroke:#333,color:#333
    style E fill:#e8f5e9,stroke:#333,color:#333
    style F fill:#e8f5e9,stroke:#333,color:#333

Patrón de solicitud/respuesta

sequenceDiagram
    participant App as Claude
    participant MCP as MCP Server
    participant DB as Database

    App->>MCP: Request: "SELECT * DE LOS Usuarios DÓNDE id=1"
    MCP->>DB: Execute query
    DB-->>MCP: Result set
    MCP-->>App: Return parsed data
    App->>App: Process result
    App->>App: Continue task

    Note over MCP,DB: Real-time access<br/>No caching

Variables de entorno

Almacenar credenciales sensibles en variables de entorno:

# ~/.bashrc or ~/.zshrc
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxxxxxxxxxxx"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_BOT_TOKEN="your-slack-bot-token"
export SLACK_TEAM_ID="T0000000000"

Luego refiérelos en configuración MCP:

{
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
  }
}

Claude como servidor MCP (claude mcp serve)

Claude Code en sí mismo puede actuar como un servidor MCP para otras aplicaciones. Esto permite que las herramientas externas, editores y sistemas de automatización aprovechen las capacidades de Claude a través del protocolo MCP estándar.

# Start Claude Code as an MCP server on stdio
claude mcp serve

Otras aplicaciones pueden conectarse a este servidor como lo harían con cualquier servidor MCP basado en stdio. Por ejemplo, para añadir Claude Code como servidor MCP en otra instancia de Claude Code:

claude mcp add --transport stdio claude-agent -- claude mcp serve

Esto es útil para construir flujos de trabajo multi-agente donde una instancia de Claude orquesta a otra.

Configuración MCP administrada (Enterprise)

Para las implementaciones empresariales, los administradores de TI aplican la política de servidores MCP a través de dos mecanismos distintos: managed-mcp.json archivo que despliega un conjunto fijo de servidores con control exclusivo, y el allowedMcpServers / deniedMcpServers las teclas de configuración que el filtro que configura los servidores pueden cargar.

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

managed-mcp.json utiliza el mismo formato que un proyecto .mcp.json — de alto nivel mcpServers map. Implementa servidores; no los filtra:

{
  "mcpServers": {
    "example-remote": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"]
    }
  }
}

Cualquier usuario en la máquina puede leer este archivo, así que nunca poner credenciales en un env bloque. Usar ${VAR} expansión, OAuth, o headersHelper En lugar de eso.

Nota (v2.1.305): Servidores en managed-mcp.json No hace falta allowedMcpServers entrada. La lista de permisos comprueba un servidor administrado sólo cuando se utiliza ${VAR} Expansión exterior env; antes de v2.1.305 también verificó los servidores que utilizaron ${VAR} solo en env. Si usted confiaba en allowedMcpServers para mantener dicho servidor apagado, ahora se carga en la actualización sin ningún aviso; añadir un deniedMcpServers entrada para él en su lugar.

Filtrado: listas de permisos y negacionistas

allowedMcpServers, deniedMcpServers, y allowAllClaudeAiMcps son teclas de configuración, no campos de managed-mcp.json. Póngalos en una fuente de configuración administrada — configuración administrada por el servidor, managed-settings.json, un perfil MDM o el registro — para que sean ejecutables:

• allowedMcpServers -- lista de permisos de servidores permitidos. allowManagedMcpServersOnly: true junto a ella, en la misma fuente administrada, o listas de permisos se fusionan desde cada ámbito y un usuario puede ampliar el suyo.
• deniedMcpServers -- negalist de servidores bloqueados. Combina desde todos los alcances independientemente.
• allowAllClaudeAiMcps -- carga conectores de nube claude.ai junto a un desplegado managed-mcp.json (v2.1.149+). Lea sólo desde niveles de políticas controlados por el administrador.

Cada entrada es un objeto con una soltero clave:

Configuración de ejemplo:

{
  "allowedMcpServers": [
    { "serverUrl": "https://mcp.example.com/*" },
    { "serverCommand": ["/usr/local/bin/company-mcp-server", "--config", "/etc/company/mcp-config.json"] }
  ],
  "deniedMcpServers": [
    { "serverName": "untrusted-server" },
    { "serverUrl": "http://*" }
  ],
  "allowManagedMcpServersOnly": true
}

Una tercera configuración administrada, managedMcpServers (v2.1.259+), permite a una organización proporcionar servidores HTTP/SSE MCP a cada usuario. Las entradas utilizan la misma forma que .mcp.json; las entradas que nombran un comando a ejecutar se omiten.

Nota: Cuando ambas cosas allowedMcpServers y deniedMcpServers coinciden con un servidor, la regla de denegación tiene prioridad.

Servidores MCP provistos de complementos

Los complementos pueden incluir sus propios servidores MCP, haciéndolos disponibles automáticamente cuando el complemento está instalado. Los servidores MCP proporcionados por Plugin se pueden definir de dos maneras:

1. Independiente .mcp.json -- Coloque una .mcp.json archivo en el directorio raíz del complemento
2. Inline in plugin.json -- Definir servidores MCP directamente dentro del manifiesto del complemento

Usar la ${CLAUDE_PLUGIN_ROOT} variable a rutas de referencia relativas al directorio de instalación del plugin:

{
  "mcpServers": {
    "plugin-tools": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp-server.js"],
      "env": {
        "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config.json"
      }
    }
  }
}

PCM con subagentes

Los servidores MCP se pueden definir en línea dentro de la frontmatter agente utilizando el mcpServers: key, ajustándolos a un subagente específico en lugar de todo el proyecto. Esto es útil cuando un agente necesita acceso a un servidor MCP particular que otros agentes en el flujo de trabajo no requieren.

---
name: my-tool-agent
description: Uses my-tool for specialized operations
mcpServers:
  my-tool:
    type: http
    url: https://my-tool.example.com/mcp
---

You are an agent with access to my-tool for specialized operations.

Los servidores MCP con alcance de subagent solo están disponibles en el contexto de ejecución de ese agente y no se comparten con los agentes padre o hermano.

Límites de salida MCP

Claude Code impone límites a la salida de herramientas MCP para evitar desbordamiento de contexto:

El límite máximo de salida es configurable a través del MAX_MCP_OUTPUT_TOKENS variable de entorno:

# Increase the max output to 50,000 tokens
export MAX_MCP_OUTPUT_TOKENS=50000

Llamadas automáticas de herramientas de largo recorrido (v2.1.212)

Las llamadas de la herramienta MCP que duran más de 2 minutos ahora se mueven al fondo automáticamente, por lo que la sesión permanece usable en lugar de bloquear una herramienta lenta. El umbral es configurable, y el comportamiento puede ser afinado o desactivado, a través de CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS:

# Change the auto-background threshold to 5 minutes (300,000ms)
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=300000

Configúralo. 0 para desactivar el fondo automático; CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 lo desactiva junto con comandos de fondo y subagentes de fondo. Para limitar el tiempo que puede correr una llamada, añada un servidor timeout en milisegundos (límite de reloj de pared duro) o MCP_TOOL_TIMEOUT a través de servidores (por defecto alrededor de 28 horas).

Tareas de MCP (pública beta, v2.1.304+)

Un servidor que soporta la extensión de tareas MCP puede ejecutar un trabajo largo: la llamada a la herramienta de Claude vuelve tan pronto como el servidor acepta el trabajo, el pie de página muestra un conteo como 1 MCP task, y Claude obtiene el resultado cuando termina el trabajo. /tasks con x. Una tarea en un servidor remoto sigue ejecutándose después de que salga; reanude la misma sesión para seguirla de nuevo. Las tareas necesitan revisión del protocolo 2026-07-28, búsqueda de la bandera de función (así que no Bedrock, Vertex, Fundición o telemetría apagado) y una terminal CLI, Agent SDK o GitHub Acciones sesión. claude -p --input-format stream-json, y cualquiera de las necesidades CLAUDE_AUTO_BACKGROUND_TASKS=1 (un plano claude -p "<prompt>" VS Code y la aplicación de escritorio no los reciben, y las llamadas de los subagentes nunca se convierten en tareas. Para hacer que Claude espere el resultado de una tarea, establezca CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND=1 (o CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0 esperar a cada llamada de MCP).

Solución del context bloat con la ejecución de código

Como escalas de adopción MCP, conectar a docenas de servidores con cientos o miles de herramientas crea un desafío significativo: bloat contextEste es posiblemente el mayor problema con MCP a escala, y el equipo de ingeniería de Anthropic ha propuesto una solución elegante, utilizando la ejecución de código en lugar de llamadas directas a herramientas.

Fuente: Ejecución de código con MCP: Construyendo agentes más eficientes — Blog de Ingeniería Antrópica

El problema: dos fuentes de residuos de token

1. Las definiciones de herramientas sobrecargan la ventana de contexto

La mayoría de los clientes MCP cargan todas las definiciones de herramientas por adelantado. Cuando se conectan a miles de herramientas, el modelo debe procesar cientos de miles de tokens antes de incluso leer la solicitud del usuario.

2. Los resultados intermedios consumen fichas adicionales

Cada resultado de herramienta intermedia pasa a través del contexto del modelo. Considere transferir una transcripción de reunión de Google Drive a Salesforce — la transcripción completa fluye a través del contexto dos veces: una vez al leerlo, y otra vez al escribirlo al destino. Una transcripción de reunión de 2 horas podría significar más de 50.000 fichas adicionales.

graph LR
    A["Model"] -->|"Tool Call: getDocument"| B["Servidor MCP"]
    B -->|"Transcripción completa (tokens de 50K)"| A
    A -->|"Llamada de herramientas: updateRecord<br/>(reenvia una transcripción completa)"| B
    B -->|"Confirmación"| A

    style A fill:#ffcdd2,stroke:#333,color:#333
    style B fill:#f3e5f5,stroke:#333,color:#333

La solución: Herramientas MCP como API de código

En lugar de pasar definiciones de herramientas y resultados a través de la ventana de contexto, el agente escribe código que llama a las herramientas MCP como APIs. El código se ejecuta en un entorno de ejecución sandboxed, y sólo el resultado final vuelve al modelo.

graph LR
    A["Model"] -->|"Código de escritura"| B["Ejecución de código<br/>Medio ambiente"]
    B -->|"Llama directamente a las herramientas"| C["Servidores MCP"]
    C -->|"Los datos permanecen en<br/>ejecución env"| B
    B -->|"Sólo el resultado final<br/>(Tokens mínimos)"| A

    style A fill:#c8e6c9,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#f3e5f5,stroke:#333,color:#333

Cómo funciona

Las herramientas MCP se presentan como un árbol de archivos de funciones mecanografiadas:

servers/
├── google-drive/
│   ├── getDocument.ts
│   └── index.ts
├── salesforce/
│   ├── updateRecord.ts
│   └── index.ts
└── ...

Cada archivo de herramienta contiene un envoltorio escrito:

// ./servers/google-drive/getDocument.ts
import { callMCPTool } from "../../../client.js";

interface GetDocumentInput {
  documentId: string;
}

interface GetDocumentResponse {
  content: string;
}

export async function getDocument(
  input: GetDocumentInput
): Promise<GetDocumentResponse> {
  return callMCPTool<GetDocumentResponse>(
    'google_drive__get_document', input
  );
}

El agente entonces escribe código para orquestar las herramientas:

import * as gdrive from './servers/google-drive';
import * as salesforce from './servers/salesforce';

// Data flows directly between tools — never through the model
const transcript = (
  await gdrive.getDocument({ documentId: 'abc123' })
).content;

await salesforce.updateRecord({
  objectType: 'SalesMeeting',
  recordId: '00Q5f000001abcXYZ',
  data: { Notes: transcript }
});

Resultado: El uso de token disminuye de ~150.000 a ~2.000, una reducción del 98,7%.

Principales beneficios

Ejemplo: Filtrar grandes conjuntos de datos

// Without code execution — all 10,000 rows flow through context
// TOOL CALL: gdrive.getSheet(sheetId: 'abc123')
//   -> returns 10,000 rows in context

// With code execution — filter in the execution environment
const allRows = await gdrive.getSheet({ sheetId: 'abc123' });
const pendingOrders = allRows.filter(
  row => row["Status"] === 'pending'
);
console.log(`Found ${pendingOrders.length} pending orders`);
console.log(pendingOrders.slice(0, 5)); // Only 5 rows reach the model

Ejemplo: Lazo sin Round-Tripping

// Poll for a deployment notification — runs entirely in code
let found = false;
while (!found) {
  const messages = await slack.getChannelHistory({
    channel: 'C123456'
  });
  found = messages.some(
    m => m.text.includes('deployment complete')
  );
  if (!found) await new Promise(r => setTimeout(r, 5000));
}
console.log('Deployment notification received');

Las compensaciones a considerar

La ejecución de código introduce su propia complejidad. El código generado por el agente en ejecución requiere:

• A entorno seguro de ejecución con caja de arena con límites de recursos adecuados
• Vigilancia y tala de código ejecutado
• Adicional gastos generales de infraestructura en comparación con las llamadas directas a la herramienta

Los beneficios —los costos de token reducidos, latencia menor, la composición mejorada de las herramientas— deben sopesarse con estos costos de implementación.Para los agentes con sólo unos pocos servidores MCP, las llamadas directas a herramientas pueden ser más simples.Para los agentes a escala (decenas de servidores, cientos de herramientas), la ejecución de código es una mejora significativa.

MCPorter: Un tiempo de ejecución para la composición de la herramienta MCP

MCPorter es un kit de herramientas TypeScript y CLI que hace que llamar a servidores MCP sea práctico sin caldera, y ayuda a reducir la hinchazón del contexto mediante exposición selectiva a herramientas y envolturas mecanografiadas.

Lo que resuelve: En lugar de cargar todas las definiciones de herramientas de todos los servidores MCP por adelantado, MCPorter le permite descubrir, inspeccionar y llamar a herramientas específicas bajo demanda, manteniendo su contexto inclinado.

Características principales:

Instalación:

npx mcporter list          # No install required — discover servers instantly
pnpm add mcporter          # Add to a project
brew install steipete/tap/mcporter  # macOS via Homebrew

Ejemplo — componiendo herramientas en TypeScript:

import { createRuntime, createServerProxy } from "mcporter";

const runtime = await createRuntime();
const gdrive = createServerProxy(runtime, "google-drive");
const salesforce = createServerProxy(runtime, "salesforce");

// Data flows between tools without passing through the model context
const doc = await gdrive.getDocument({ documentId: "abc123" });
await salesforce.updateRecord({
  objectType: "SalesMeeting",
  recordId: "00Q5f000001abcXYZ",
  data: { Notes: doc.text() }
});

Ejemplo: llamada a la herramienta CLI:

# Call a specific tool directly
npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'

# List available servers and tools
npx mcporter list

MCPorter complementa el enfoque de ejecución de código descrito anteriormente proporcionando la infraestructura de tiempo de ejecución para llamar a las herramientas MCP como APIs mecanografiadas, lo que hace sencillo mantener los datos intermedios fuera del contexto del modelo.

Mejores prácticas

Consideraciones de seguridad

¿Hacer?

• Usar variables de entorno para todas las credenciales
• Rotar fichas y claves API regularmente (recomendado mensualmente)
• Usar tokens de solo lectura cuando sea posible
• Limitar el alcance de acceso del servidor MCP al mínimo requerido
• Monitoree el uso del servidor MCP y los registros de acceso
• Utilizar OAuth para servicios externos cuando estén disponibles
• Aplicar el límite de tasa en las solicitudes de MCP
• Ensayo de las conexiones MCP antes del uso de producción
• Documentar todas las conexiones MCP activas
• Mantener actualizados los paquetes de servidor MCP

No lo hagas.

• No codifique credenciales en archivos de configuración
• No comprometas fichas o secretos a git
• No comparta fichas en chats de equipo o correos electrónicos
• No use fichas personales para proyectos de equipo
• No concedas permisos innecesarios.
• No ignore los errores de autenticación
• No expongas públicamente los puntos finales de MCP
• No ejecute servidores MCP con privilegios de root/admin
• No cachear datos sensibles en registros
• No deshabilitar los mecanismos de autenticación

Mejores prácticas de configuración

1. Control de versiones: Mantener .mcp.json en git pero use variables de entorno para secretos
2. Privilegio menor: Conceder permisos mínimos necesarios para cada servidor MCP
3. Aislado: Ejecutar diferentes servidores MCP en procesos separados cuando sea posible
4. Supervisión: Registrar todas las solicitudes MCP y errores para pistas de auditoría
5. Ensayos: Pruebe todas las configuraciones MCP antes de implementarlas en la producción

Consejos de rendimiento

• Cache datos de acceso frecuente a nivel de aplicación
• Utilizar consultas MCP específicas para reducir la transferencia de datos
• Monitorear los tiempos de respuesta para las operaciones MCP
• Considerar la limitación de tarifas para API externas
• Utilizar lotes cuando se realicen múltiples operaciones

Instrucciones de instalación

Requisitos previos

• Nodo.js y npm instalados
• Claude Code CLI instalado
• tokens/credenciales API para servicios externos

Configuración paso a paso

1. Añadir su primer servidor MCP utilizando el CLI (ejemplo: GitHub):

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

O crear un .mcp.json archivo en su raíz de proyecto:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

1. Establecer variables de entorno:

export GITHUB_PERSONAL_ACCESS_TOKEN="your_github_personal_access_token"

1. Prueba la conexión:

claude /mcp

1. Utilizar herramientas MCP:

/mcp__github__list_prs
/mcp__github__create_issue "Title" "Description"

Instalación para Servicios Específicos

GitHub MCP:

npm install -g @modelcontextprotocol/server-github

Base de datos MCP:

npm install -g @bytebase/dbhub

Sistema de archivos MCP:

npm install -g @modelcontextprotocol/server-filesystem

MCP de Slack (paquete obsoleto):

npm install -g @modelcontextprotocol/server-slack

Solución de problemas

Iniciar con la salida de error (v2.1.219+)

Si un servidor no se conecta, ejecute claude mcp list (o /mcp dentro de una sesión) antes de cambiar nada. Claude Code ahora imprime el Código de estado HTTP y texto de error del servidor al lado del servidor que falla, así que usted consigue 401 Unauthorized o 404 Not Found en lugar de un genérico "no se ha conectado":

# Shows connection status plus HTTP status and error text for failures
claude mcp list

Lea el estado primero — le dice que solución aplica:

• 401 / 403 → credenciales malas o caducadas; re-autenticar con claude mcp login <name>
• 404 → URL incorrecta (falta /mcp o /sse sufijo de camino es la causa habitual)
• 5xx / timeout → el servidor remoto está desconectado; ver Tiempo de conexión

Espacio blanco oculto en valores de configuración (v2.1.219+)

Claude Code advierte cuando un valor de configuración MCP tiene espacio en blanco que conduce o sigue. Esta es una causa común y difícil de localizar de fallas de la aut: un token copia-pegado desde un navegador o un mensaje de chat a menudo lleva un espacio o newline, que se envía literalmente en el Authorization cabecera y falla como una credencial inválida.

Si ve esta advertencia, vuelva a comprobar el valor en .mcp.json (o el env var se expande de) y recortarlo:

# Reveals hidden leading/trailing whitespace between the delimiters
printf '[%s]\n' "$GITHUB_PERSONAL_ACCESS_TOKEN"

Servidores omitidos en ejecuciones sin interfaz (v2.1.219+)

Servidores pasados a través --mcp-config que fallan la validación de configuración son omitida en lugar de abortar la ejecución, por lo que un guión sin interfaz puede parecer funcionar mientras que falta la mitad de sus herramientas. Claude Code ahora informa cuáles fueron eliminados:

• Sin interfaz / -p corre: el stream-json init evento lleva un mcp_server_errors campo que enumera cada entrada omitida. Compruebe antes de confiar en la salida de la ejecución.
• Ejecutaciones interactivas de terminales: el mismo problema se imprime como una advertencia de inicio cuando la sesión comienza.

# Inspect skipped --mcp-config entries in a headless run
claude -p "list my tools" --mcp-config ./servers.json \
  --output-format stream-json --verbose \
  | jq -r 'select(.type == "system" and .subtype == "init") | .mcp_server_errors'

Servidor MCP no encontrado

# Verify MCP server is installed
npm list -g @modelcontextprotocol/server-github

# Install if missing
npm install -g @modelcontextprotocol/server-github

Autenticación fallida

# Verify environment variable is set
echo $GITHUB_PERSONAL_ACCESS_TOKEN

# Re-export if needed
export GITHUB_PERSONAL_ACCESS_TOKEN="your_token"

# Verify token has correct permissions
# Check GitHub token scopes at: https://github.com/settings/tokens

Tiempo de conexión

• Comprobar la conectividad de red: ping api.github.com
• Verificar que el punto final de la API es accesible
• Comprobar los límites de velocidad en la API
• Levante el servidor timeout (milisegundos) en su entrada de configuración, o MCP_TOOL_TIMEOUT para todos los servidores
• Comprobar si hay problemas de firewall o proxy

El servidor MCP se rompe

• Compruebe los registros del servidor MCP: ~/.claude/logs/
• Verificar todas las variables de entorno se establecen
• Asegúrese de que los permisos de archivo adecuados
• Intente reinstalar el paquete de servidor MCP
• Comprobar si hay procesos en conflicto en el mismo puerto

Conceptos relacionados

Memoria frente a MCP

• Memoria: Almacena datos persistentes e inmutables (preferencias, contexto, historia)
• MCP: Accesos en directo, cambios de datos (API, bases de datos, servicios en tiempo real)

Cuándo usar cada uno

• Usar memoria para: Preferencias de usuario, historial de conversación, contexto aprendido
• Usar MCP para: Problemas actuales de GitHub, consultas en vivo de bases de datos, datos en tiempo real

Integración con otras características de Claude

• Combine MCP con memoria para un contexto rico
• Utilice herramientas MCP en avisos para un mejor razonamiento
• Aprovechar múltiples MCP para flujos de trabajo complejos

Recursos adicionales

• Documentación oficial del MCP
• Especificación del protocolo de MCP
• Repositorio GitHub MCP
• Servidores MCP disponibles
• MCPorter — TypeScript runtime & CLI para llamar a servidores MCP sin placa de caldera
• Ejecución de código con MCP — El blog de ingeniería de Anthropic sobre la resolución de la hinchazón de contexto
• Referencia al código CLI de Claude
• Documentación API de Claude

Última actualización: 26 de octubre de 2026 Versión de Claude Code: 2.1.310 Fuentes: - https://code.claude.com/docs/en/mcp - https://code.claude.com/docs/en/managed-mcp - https://code.claude.com/docs/en/changelog - https://github.com/anthropics/claude-code/releases/tag/v2.1.117 - https://github.com/anthropics/claude-code/releases/tag/v2.1.139 - https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md - https://code.claude.com/docs/en/model-config - https://code.claude.com/docs/en/mcp#configure-tool-search - https://code.claude.com/docs/en/env-vars - https://github.com/anthropics/claude-code/releases/tag/v2.1.285 - https://github.com/anthropics/claude-code/releases/tag/v2.1.296 - https://code.claude.com/docs/en/mcp#tool-search-for-mcp-server-authors - https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcp-json - https://code.claude.com/docs/en/sub-agents - https://code.claude.com/docs/en/changelog#2-1-304 - https://code.claude.com/docs/en/changelog#2-1-305 - https://code.claude.com/docs/en/mcp#tool-search-through-an-llm-gateway - https://code.claude.com/docs/en/managed-mcp#how-allowlists-and-denylists-apply-to-the-managed-set - https://code.claude.com/docs/en/mcp#mcp-tasks-that-run-on-the-server - https://code.claude.com/docs/en/mcp#what-a-call-needs-to-become-an-mcp-task - https://code.claude.com/docs/en/mcp#make-claude-wait-for-the-result-of-an-mcp-task - https://code.claude.com/docs/en/mcp#automatic-backgrounding-of-long-tool-calls - https://code.claude.com/docs/en/mcp#time-limits-on-mcp-tool-calls - https://code.claude.com/docs/en/changelog#2-1-307 - https://code.claude.com/docs/en/mcp#mark-tools-that-are-safe-to-call-twice Modelos compatibles: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5