Skip to main content
Todas las guías
Contenido de la guía

Contenido de la guía

Tiempo de estudio: 12 min
#automation#mcp#claude-code#typescript#devtools
Intermedio12 min

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.

Publicado:

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

EscenarioSin MCP (Claude Code estándar)Con Servidores MCP conectados
Acceso a archivosRestringido exclusivamente al directorio del proyectoAcceso a cualquier carpeta externa autorizada
Datos de repositoriosArchivos locales mediante git diff / git logLectura de issues, PRs, revisiones y APIs de GitHub
Bases de datosSolo si se ejecuta manualmente un cliente CLI localInspección directa de esquemas, tablas y consultas SQL
Búsqueda de informaciónBúsqueda local con grep / ripgrepBúsqueda web en tiempo real mediante Brave Search
Servicios internosNo disponible sin complejos scripts bashLlamadas 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.
Nota

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.
json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/mcp-filesystem",
        "./docs"
      ]
    }
  }
}

Parámetros de configuración

Cada entrada en mcpServers consta de tres campos clave:

ParámetroTipoObligatorioDescripción y funciónEjemplos
commandstringSíComando ejecutable para iniciar el proceso del servidor"npx", "node", "uvx", "docker"
argsstring[]SíArgumentos de inicio (nombre del paquete, rutas, flags)["-y", "@anthropic-ai/mcp-filesystem", "/ruta"]
envobjectNoVariables de entorno para tokens y claves de API{"GITHUB_TOKEN": "ghp_...", "DEBUG": "1"}
Consejo

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:

ServidorPaquete oficialAcceso / AutenticaciónCapacidades principales
Filesystem@anthropic-ai/mcp-filesystemRutas de directorios locales permitidosLectura, escritura y búsqueda fuera de la raíz del proyecto
GitHub@anthropic-ai/mcp-githubPersonal Access Token (GITHUB_TOKEN)Búsqueda en repositorios, gestión de issues y PRs
PostgreSQL@anthropic-ai/mcp-postgresCadena de conexión URIInspección de esquemas, lectura de tablas y SQL
Brave Search@anthropic-ai/mcp-brave-searchClave 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" ] } } }
Consejo

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 │ └─────────────────────────────────────────────────────────────┘
Atención

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" } } } }
  1. 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" ] } } }
  1. 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
Consejo

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
Consejo

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
Consejo

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

  • Niveles de configuración: Servidores globales en ~/.claude/settings.json; herramientas de proyecto en .claude/settings.json.
  • Seguridad: Tokens excluidos de git; bases de datos conectadas con privilegios mínimos (solo lectura).
  • Verificación: Herramientas comprobadas con prompts de prueba al iniciar la sesión.
  • Extensibilidad: Servidor TypeScript personalizado disponible como plantilla mediante @modelcontextprotocol/sdk.
Esta guía es completamente gratuita. Si te ahorró una noche, puedes apoyar el crecimiento del proyecto.
Apoyar al autor