# Servidores MCP y Claude Code: guía práctica de conexión y desarrollo > Cómo ampliar las capacidades de Claude Code mediante Model Context Protocol: conexión del sistema de archivos, GitHub, PostgreSQL, Brave Search y creación de un servidor propio en TypeScript. De forma predeterminada, Claude Code ya permite leer archivos locales, ejecutar comandos en la terminal y editar el código de un proyecto. Sin embargo, en flujos de trabajo reales esto rara vez es suficiente: a menudo se necesita consultar una base de datos PostgreSQL, revisar Pull Requests abiertos en GitHub, consultar documentación técnica actualizada en la nube o invocar APIs corporativas internas. Para solucionar este problema se diseñó el **Model Context Protocol (MCP)**: un estándar abierto creado por Anthropic que transforma Claude Code de un asistente local a un potente centro de orquestación de sistemas y servicios externos. En esta guía práctica analizaremos la arquitectura de MCP, conectaremos servidores oficiales listos para producción, crearemos un servidor personalizado en TypeScript y consolidaremos los conocimientos con ejercicios guiados. --- ## 1. Qué es un Servidor MCP **Model Context Protocol (MCP)** es un protocolo abierto de comunicación que estandariza la interacción entre modelos de lenguaje (LLM) y herramientas o fuentes de datos externas. En lugar de programar integraciones aisladas para cada servicio, MCP introduce una arquitectura cliente-servidor unificada: ```text ┌─────────────────────────────────────────────────────────────┐ │ Claude Code (Cliente) │ └──────────────────────────────┬──────────────────────────────┘ │ JSON-RPC 2.0 (stdio / SSE) ▼ ┌─────────────────────────────────────────────────────────────┐ │ Servidor MCP (Adaptador) │ └──────┬───────────────────────┼───────────────────────┬──────┘ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Archivos │ │ GitHub API │ │ Base de │ │ locales │ │ e Issues │ │ datos SQL │ └─────────────┘ └─────────────┘ └─────────────┘ ``` Todo servidor MCP proporciona al modelo tres primitivas fundamentales: - **Tools (Herramientas)** — Funciones ejecutables con esquemas JSON tipados que Claude Code puede invocar de forma autónoma (por ejemplo, `create_issue`, `execute_query`). - **Resources (Recursos)** — Datos o esquemas pasivos que el asistente lee como contexto de entrada (archivos, esquemas de BD, registros). - **Prompts (Plantillas de prompts)** — Flujos contextuales preconfigurados que agilizan tareas operativas frecuentes. ### Comparativa de capacidades | Escenario | Sin MCP (Claude Code estándar) | Con Servidores MCP conectados | | :--- | :--- | :--- | | **Acceso a archivos** | Restringido exclusivamente al directorio del proyecto | Acceso a cualquier carpeta externa autorizada | | **Datos de repositorios** | Archivos locales mediante `git diff` / `git log` | Lectura de issues, PRs, revisiones y APIs de GitHub | | **Bases de datos** | Solo si se ejecuta manualmente un cliente CLI local | Inspección directa de esquemas, tablas y consultas SQL | | **Búsqueda de información** | Búsqueda local con grep / ripgrep | Búsqueda web en tiempo real mediante Brave Search | | **Servicios internos** | No disponible sin complejos scripts bash | Llamadas directas a microservicios mediante SDK tipado | --- ## 2. Arquitectura y ciclo de vida de una petición La comunicación se basa en el estándar **JSON-RPC 2.0**. En entornos locales, el intercambio de datos se realiza a través de flujos estándar de entrada/salida (`stdio`), mientras que los servidores remotos emplean Server-Sent Events (`SSE`) o HTTP. ### Ciclo de vida paso a paso 1. **Inicialización y Handshake:** Al iniciar Claude Code, lee la configuración, arranca los procesos de los servidores y solicita la lista de herramientas disponibles (`tools/list`). 2. **Publicación de capacidades:** Cada servidor MCP devuelve sus métodos con esquemas JSON de parámetros y descripciones detalladas. 3. **Detección de intención:** Cuando describes una tarea en lenguaje natural, Claude compara la petición con las herramientas registradas. 4. **Invocación de herramienta:** Si la tarea requiere datos externos, el modelo envía una petición estructurada `tools/call` al servidor con argumentos válidos. 5. **Ejecución en el servidor:** El servidor interactúa con la API, base de datos o disco y devuelve los datos al cliente. 6. **Síntesis de respuesta:** Claude interpreta los resultados sin procesar y elabora una respuesta clara y estructurada. > [!NOTE] > La interacción es transparente para el desarrollador: no necesitas memorizar firmas de métodos ni sintaxis de APIs. Claude selecciona automáticamente la herramienta adecuada según el contexto. --- ## 3. Cómo conectar un Servidor MCP a Claude Code Los servidores se configuran en formato JSON bajo la clave `mcpServers`. Claude Code admite dos niveles de configuración: 1. **Configuración de proyecto (`.claude/settings.json`)** — Aplicable únicamente a la carpeta actual y lista para compartirse en el repositorio con el equipo. 2. **Configuración global (`~/.claude/settings.json`)** — Disponible en todos los proyectos del usuario en el sistema operativo. :::tabs === Proyecto (.claude/settings.json) ```json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "./docs" ] } } } ``` === Global (~/.claude/settings.json) ```json { "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_tu_token_aqui" } } } } ``` ::: ### Parámetros de configuración Cada entrada en `mcpServers` consta de tres campos clave: | Parámetro | Tipo | Obligatorio | Descripción y función | Ejemplos | | :--- | :--- | :--- | :--- | :--- | | `command` | `string` | Sí | Comando ejecutable para iniciar el proceso del servidor | `"npx"`, `"node"`, `"uvx"`, `"docker"` | | `args` | `string[]` | Sí | Argumentos de inicio (nombre del paquete, rutas, flags) | `["-y", "@anthropic-ai/mcp-filesystem", "/ruta"]` | | `env` | `object` | No | Variables de entorno para tokens y claves de API | `{"GITHUB_TOKEN": "ghp_...", "DEBUG": "1"}` | > [!TIP] > Si utilizas herramientas MCP basadas en Python, puedes usar `uvx` en lugar de `npx`: `"command": "uvx", "args": ["mcp-server-git"]`. --- ## 4. Catálogo de Servidores MCP listos para usar Existen paquetes oficiales y comunitarios listos para producción para las herramientas más habituales: | Servidor | Paquete oficial | Acceso / Autenticación | Capacidades principales | | :--- | :--- | :--- | :--- | | **Filesystem** | `@anthropic-ai/mcp-filesystem` | Rutas de directorios locales permitidos | Lectura, escritura y búsqueda fuera de la raíz del proyecto | | **GitHub** | `@anthropic-ai/mcp-github` | Personal Access Token (`GITHUB_TOKEN`) | Búsqueda en repositorios, gestión de issues y PRs | | **PostgreSQL** | `@anthropic-ai/mcp-postgres` | Cadena de conexión URI | Inspección de esquemas, lectura de tablas y SQL | | **Brave Search** | `@anthropic-ai/mcp-brave-search` | Clave de API de búsqueda (`BRAVE_API_KEY`) | Acceso a información web reciente sin alucinaciones | ### 1. Filesystem Server Permite a Claude Code acceder a directorios fuera del repositorio actual (por ejemplo, a una bóveda de notas Obsidian): ```json { "mcpServers": { "docs": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "/Users/username/Developer/knowledge-base" ] } } } ``` ### 2. GitHub Server Permite interactuar directamente con repositorios de la organización: consultar issues, comentar en PRs y revisar commits: ```json { "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } } } ``` ### 3. PostgreSQL Server Permite ejecutar consultas de análisis o diagnóstico directamente contra la base de datos: ```json { "mcpServers": { "postgres": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-postgres", "postgresql://postgres:password@localhost:5432/my_app_db" ] } } } ``` ### 4. Brave Search Server Integra un motor de búsqueda web para verificar documentación reciente y cambios en librerías: ```json { "mcpServers": { "brave-search": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-brave-search" ], "env": { "BRAVE_API_KEY": "BSAu_tu_clave_de_api" } } } } ``` --- ## 5. Cómo utiliza Claude Code las herramientas en conversación Una vez configurado el servidor, no necesitas introducir comandos especiales. Claude Code analiza tu petición y decide cuándo invocar cada herramienta. ### Ejemplo práctico: interacción con GitHub **Petición del usuario:** > "¿Cuáles son los issues abiertos asignados a mí en el repositorio acme/platform? Muestra un resumen de los más prioritarios." **Flujo interno en Claude Code:** 1. El modelo identifica que los archivos locales no contienen estos datos remotos. 2. Genera una llamada `mcp__github__search_issues` con filtros `repo:acme/platform state:open assignee:@me`. 3. Recibe la respuesta JSON del servidor de GitHub. 4. Sintetiza la información en un formato ordenado: ```markdown Se han encontrado 3 issues abiertos asignados a ti: 1. **#42 — Fix login redirect loop** (Prioridad: Alta, Creado: hace 2 días) 2. **#38 — Add rate limiting to auth API** (Prioridad: Media, Creado: hace 5 días) 3. **#35 — Update user profile settings page** (Prioridad: Baja, Creado: hace 1 semana) ¿Deseas examinar el código para solucionar el error del redirect loop en #42? ``` --- ## 6. Creación de un Servidor MCP propio en TypeScript Si necesitas conectar servicios internos o lógica de negocio específica, puedes crear un servidor MCP en pocos minutos con `@modelcontextprotocol/sdk`. ### Paso 1. Inicialización y dependencias Crea una carpeta de trabajo e instala los paquetes necesarios: ```bash mkdir my-mcp-server && cd my-mcp-server npm init -y npm install @modelcontextprotocol/sdk zod npm install -D typescript @types/node tsx ``` ### Paso 2. Implementación del servidor (`server.ts`) Crea el archivo `server.ts` con la definición del servidor y una herramienta personalizada: ```typescript import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; // 1. Inicialización del servidor con metadatos const server = new McpServer({ name: "internal-crm-server", version: "1.0.0", }); // 2. Registro de herramienta con validación tipada vía Zod server.tool( "lookup-user", "Consultar perfil de cliente por dirección de correo electrónico", { email: z.string().email().describe("Correo electrónico del usuario registrado"), }, async ({ email }) => { // Simulación de consulta a CRM o base de datos interna const mockUser = { id: "usr_99812", email, name: "Alejandro Morales", plan: "Enterprise", status: "active", createdAt: "2024-03-15T10:00:00Z", }; return { content: [ { type: "text", text: JSON.stringify(mockUser, null, 2), }, ], }; } ); // 3. Inicio del transporte estándar stdio async function run() { const transport = new StdioServerTransport(); await server.connect(transport); console.error("Servidor MCP CRM interno iniciado en stdio"); } run().catch((error) => { console.error("Error al iniciar el servidor:", error); process.exit(1); }); ``` ### Paso 3. Conexión a la configuración de Claude Code Añade el servidor a `.claude/settings.json`: ```json { "mcpServers": { "crm": { "command": "npx", "args": [ "tsx", "/Users/username/Developer/my-mcp-server/server.ts" ] } } } ``` > [!TIP] > Usar `tsx` permite ejecutar archivos TypeScript directamente sin necesidad de compilación previa con `tsc`. --- ## 7. Seguridad y aislamiento del entorno MCP amplía la autonomía de Claude Code, pero los servidores se ejecutan con tus privilegios en tu máquina local. Aplica siempre estas medidas: ### 1. El servidor hereda tus permisos de usuario Un servidor MCP se ejecuta bajo tu cuenta de sistema operativo. Un servidor vulnerable o malicioso tiene acceso a los mismos archivos y recursos que tu terminal. ### 2. Aislamiento de claves y credenciales Nunca subas claves de API al repositorio. Almacena las credenciales en `~/.claude/settings.json` o pásalas a través de variables de entorno protegidas en `.gitignore`. ### 3. Auditoría de paquetes de terceros Antes de conectar servidores comunitarios: - Comprueba que el código fuente sea abierto y activo. - Revisa las peticiones de red que realiza al iniciar. - Inspecciona a qué rutas del disco solicita acceso. ### 4. Separación de niveles de configuración ```text ┌─────────────────────────────────────────────────────────────┐ │ ~/.claude/settings.json │ │ Herramientas globales: GitHub, Brave Search, navegador │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ .claude/settings.json │ │ Herramientas locales: DB de desarrollo, scripts propios │ └─────────────────────────────────────────────────────────────┘ ``` > [!WARNING] > No conectes servidores con permisos de escritura a bases de datos de producción en sesiones interactivas. Utiliza réplicas de solo lectura o contenedores Docker locales. --- ## 8. Taller práctico: configuración guiada Realiza estos dos ejercicios prácticos para verificar la correcta integración de los servidores. ### Tarea 1. Conexión del Servidor MCP de GitHub 1. Genera un Personal Access Token en GitHub con permisos `repo` y `read:org`. 2. Añade el servidor a `~/.claude/settings.json`: ```json { "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_tu_token_aqui" } } } } ``` 3. Inicia una sesión de Claude Code y prueba el siguiente prompt: ```bash claude ``` > **Prompt de prueba:** > "Muestra mis 5 repositorios actualizados más recientemente en GitHub y su estado actual." - [ ] Claude Code invoca la herramienta de GitHub sin errores de autenticación. - [ ] Devuelve la lista correcta de repositorios. --- ### Tarea 2. Conexión de Filesystem Server para documentación externa 1. Configura el servidor en `.claude/settings.json`: ```json { "mcpServers": { "external-docs": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "/ruta/a/tu/carpeta/de/notas" ] } } } ``` 2. Ejecuta una consulta de prueba: > **Prompt de prueba:** > "Busca en la carpeta external-docs los archivos markdown sobre la arquitectura de la API y genera un resumen." - [ ] Claude lee archivos fuera de la raíz del proyecto. - [ ] Resume la información sin perder contexto. --- ## 9. Autoevaluación rápida Comprueba tu comprensión sobre la arquitectura de Model Context Protocol. ### Pregunta 1. ¿Cuál es la función principal de un Servidor MCP? - **A.** Una máquina virtual en la nube para alojar modelos de Claude - **B.** Un proceso adaptador que ofrece a los LLM acceso estandarizado a herramientas y datos - **C.** Una librería para comprimir embeddings vectoriales - **D.** Un servidor web para alojar el frontend compilado > [!TIP] > **Respuesta correcta: B.** > Un Servidor MCP actúa como un puente entre el modelo y servicios externos mediante Tools, Resources y Prompts estandarizados. --- ### Pregunta 2. ¿Dónde se guarda la configuración exclusiva de un proyecto específico? - **A.** `~/.claude/settings.json` - **B.** `package.json` - **C.** `.claude/settings.json` en la raíz del proyecto - **D.** `CLAUDE.md` > [!TIP] > **Respuesta correcta: C.** > La configuración de proyecto reside en `.claude/settings.json`, mientras que `~/.claude/settings.json` gestiona herramientas globales. --- ### Pregunta 3. ¿Cómo determina Claude Code qué herramienta debe utilizar? - **A.** El usuario debe indicar obligatoriamente el flag `--tool=name` en cada consulta - **B.** Se debe ejecutar previamente el comando `/mcp select` - **C.** El modelo evalúa la semántica de la consulta frente a los esquemas de herramientas y decide de forma autónoma - **D.** Se ejecutan todas las herramientas a la vez y se descartan las respuestas sobrantes > [!TIP] > **Respuesta correcta: C.** > Gracias a las descripciones y esquemas de parámetros, Claude detecta la intención del usuario y envía peticiones válidas cuando es necesario. --- ## 10. Conclusiones y lista de comprobación Model Context Protocol convierte a Claude Code en un entorno de desarrollo ampliable. En lugar de copiar y pegar esquemas o volcados de datos manualmente, defines canales de comunicación seguros y reutilizables. ### Lista de comprobación para tu entorno - [x] **Niveles de configuración:** Servidores globales en `~/.claude/settings.json`; herramientas de proyecto en `.claude/settings.json`. - [x] **Seguridad:** Tokens excluidos de git; bases de datos conectadas con privilegios mínimos (solo lectura). - [x] **Verificación:** Herramientas comprobadas con prompts de prueba al iniciar la sesión. - [x] **Extensibilidad:** Servidor TypeScript personalizado disponible como plantilla mediante `@modelcontextprotocol/sdk`.