Saltar al contenido principal
Volver al blog
Claude CodeMCP ServersIntegraciones

Guía de MCP Servers: conecta Claude a tus herramientas

Ray MartínRay Martín
10 min de lectura
Guía de MCP Servers: conecta Claude a tus herramientas

¿Qué es MCP (Model Context Protocol)?

El Model Context Protocol (MCP) es un protocolo abierto que estandariza cómo las aplicaciones de IA se conectan con fuentes de datos y herramientas externas. Piensa en MCP como un puerto USB universal para modelos de lenguaje: en lugar de construir integraciones personalizadas para cada servicio, MCP proporciona una interfaz estándar que cualquier herramienta puede implementar.

Con MCP, Claude puede acceder a bases de datos, repositorios de GitHub, sistemas de archivos, APIs externas y cualquier servicio que tenga un servidor MCP disponible, todo sin salir de tu sesión de trabajo.

Arquitectura: Host, Client, Server

La arquitectura de MCP se compone de tres elementos principales:

  • Host: La aplicación que el usuario ejecuta directamente. En nuestro caso, Claude Code o Claude Desktop. El host gestiona la conexión con el usuario y coordina los clientes MCP.
  • Client: Vive dentro del host y mantiene una conexión 1:1 con un servidor MCP específico. Se encarga de la comunicación bidireccional con el servidor.
  • Server: Un proceso ligero que expone resources (datos), tools (acciones) y prompts (plantillas) a través del protocolo MCP. Cada servidor se especializa en un servicio o fuente de datos.

La comunicación entre cliente y servidor usa JSON-RPC 2.0 sobre transporte stdio (procesos locales) o SSE/HTTP (servidores remotos).

Configuración en Claude Code

Los servidores MCP se configuran de dos formas principales:

Configuración global (~/.claude/settings.json)

Para servidores que quieres disponibles en todos tus proyectos:

json 
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/usuario/proyectos"
      ]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "tu-api-key-aqui"
      }
    }
  }
}

Configuración por proyecto (.mcp.json)

Para servidores específicos de un proyecto, crea un archivo .mcp.json en la raíz del repositorio:

json 
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/mi_base_datos"
      ]
    }
  }
}

Servidores MCP populares

El ecosistema de MCP crece rápidamente. Estos son los servidores más útiles para desarrolladores:

Filesystem

Acceso controlado al sistema de archivos. Permite leer, escribir y buscar archivos dentro de directorios específicos con control de permisos.

json 
{
  "filesystem": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "/ruta/permitida"
    ]
  }
}

PostgreSQL

Conecta Claude a una base de datos PostgreSQL. Permite ejecutar consultas SQL, inspeccionar esquemas y analizar datos directamente desde tu sesión.

GitHub

Gestión completa de repositorios: crear issues, revisar pull requests, buscar código, gestionar branches y mucho más a través de la API de GitHub.

Puppeteer

Automatización del navegador. Permite a Claude navegar por páginas web, tomar capturas de pantalla, rellenar formularios y hacer web scraping.

Brave Search

Búsqueda web en tiempo real. Ideal para consultar documentación actualizada, buscar soluciones a errores o investigar APIs.

Ejemplo práctico: configurar MCP para PostgreSQL

Vamos a configurar paso a paso un servidor MCP para conectar Claude con una base de datos PostgreSQL local.

Paso 1: Verificar la base de datos

bash 
# Verificar que PostgreSQL está corriendo
pg_isready -h localhost -p 5432

# Verificar acceso a la base de datos
psql -h localhost -U tu_usuario -d tu_base_datos -c "SELECT 1;"

Paso 2: Configurar el servidor MCP

Añade la configuración en tu archivo .mcp.json:

json 
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://tu_usuario:tu_password@localhost:5432/tu_base_datos"
      ]
    }
  }
}

Paso 3: Usar en Claude Code

Una vez configurado, reinicia Claude Code y ya podrás hacer consultas naturales:

bash 
# Dentro de Claude Code puedes preguntar:
# "Muéstrame el esquema de la tabla usuarios"
# "¿Cuántos pedidos se hicieron en el último mes?"
# "Crea una migración para añadir el campo 'avatar_url' a la tabla usuarios"

Ejemplo: MCP de GitHub para gestión de PRs e issues

Configuración

json 
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_tu_token_aqui"
      }
    }
  }
}

Casos de uso

Con el servidor MCP de GitHub configurado, Claude puede:

  • Listar y filtrar issues abiertos por etiqueta o asignación.
  • Crear pull requests con título, descripción y reviewers asignados.
  • Revisar el código de un PR y dejar comentarios.
  • Buscar código en todo el repositorio.
  • Gestionar branches y releases.

Crear tu propio MCP server con TypeScript

Si necesitas conectar Claude a un servicio interno o una API personalizada, puedes crear tu propio servidor MCP. Aquí tienes un ejemplo básico:

Setup del proyecto

bash 
mkdir mi-mcp-server
cd mi-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
npx tsc --init

Implementación

typescript 
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "mi-api-server",
  version: "1.0.0",
});

// Definir un tool que consulta tu API interna
server.tool(
  "consultar-estado-servicio",
  "Consulta el estado de un microservicio interno",
  {
    servicio: z.string().describe("Nombre del microservicio"),
  },
  async ({ servicio }) => {
    try {
      const response = await fetch(
        `https://api.interna.ejemplo.com/status/${servicio}`
      );
      const data = await response.json();

      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(data, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error al consultar el servicio: ${error}`,
          },
        ],
        isError: true,
      };
    }
  }
);

// Definir un resource que expone datos estáticos
server.resource(
  "config",
  "config://servicios",
  async () => ({
    contents: [
      {
        uri: "config://servicios",
        text: JSON.stringify({
          servicios: ["auth", "payments", "notifications", "users"],
          entorno: "produccion",
        }),
      },
    ],
  })
);

// Iniciar el servidor
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP Server iniciado correctamente");
}

main().catch(console.error);

Registrar tu servidor

json 
{
  "mcpServers": {
    "mi-api": {
      "command": "npx",
      "args": ["tsx", "/ruta/a/mi-mcp-server/index.ts"]
    }
  }
}

Seguridad y buenas prácticas

  • Principio de mínimo privilegio: Otorga a cada servidor MCP solo los permisos que necesita. Si un servidor solo necesita leer datos, no le des permisos de escritura.
  • Variables de entorno: Nunca escribas credenciales directamente en los archivos de configuración. Usa variables de entorno o gestores de secretos.
  • Validación de inputs: Siempre valida los datos que recibe tu servidor MCP con esquemas Zod o similar.
  • Limitar directorios: En el servidor filesystem, especifica solo los directorios estrictamente necesarios.
  • Auditoría: Revisa periódicamente qué servidores MCP tienes configurados y elimina los que no uses.
  • Conexiones de base de datos: Usa usuarios de base de datos con permisos de solo lectura siempre que sea posible.

Debugging de servidores MCP

Cuando un servidor MCP no funciona como esperas, puedes seguir estos pasos para diagnosticar el problema:

Verificar logs

bash 
# Los servidores MCP escriben logs en stderr
# Puedes ejecutar el servidor manualmente para ver los errores:
npx -y @modelcontextprotocol/server-postgres \
  "postgresql://localhost:5432/mi_db" 2>&1

Usar el MCP Inspector

El MCP Inspector es una herramienta oficial que te permite interactuar con servidores MCP de forma visual para probar tools y resources:

bash 
# Instalar e iniciar el inspector
npx @modelcontextprotocol/inspector \
  npx -y @modelcontextprotocol/server-filesystem /tmp

Errores comunes

  • El servidor no arranca: Verifica que el paquete npm existe y está correctamente escrito en la configuración.
  • Timeout de conexión: Asegúrate de que el servicio subyacente (base de datos, API) está accesible desde tu máquina.
  • Permisos denegados: Revisa que las credenciales y tokens de acceso son válidos y tienen los permisos necesarios.
  • Herramientas no aparecen: Reinicia Claude Code después de modificar la configuración MCP. Los servidores se cargan al inicio de la sesión.

Consejo: Si un servidor MCP falla silenciosamente, ejecuta el comando del servidor directamente en tu terminal para ver los mensajes de error completos.

Compartir:

Artículos relacionados