Cómo usar servidores MCP con Claude Code (guía visual de configuración)

Claude Code es uno de los agentes de programación con IA más potentes que existen hoy. Pero de fábrica opera dentro de un sandbox limitado: puede leer y escribir archivos, ejecutar comandos de terminal y poco más. ¿Y si necesitas que Claude Code navegue por la web, consulte una base de datos, interactúe con issues de GitHub o envíe un mensaje de Slack?

Ahí es donde entran los servidores MCP.

En esta guía aprenderás exactamente qué es el Model Context Protocol (MCP), cómo los servidores MCP amplían las capacidades de Claude Code y cómo configurar los servidores MCP más populares paso a paso. También te mostraremos cómo SuperBuilder elimina por completo la complejidad de la configuración de MCP con su sistema de skills integrado.

MCP servers extending Claude Code capabilities diagram

¿Qué es MCP (Model Context Protocol)?

El Model Context Protocol es un estándar abierto creado por Anthropic que define cómo los modelos de IA se comunican con herramientas y fuentes de datos externas. Piénsalo como una capa de adaptador universal: en lugar de que cada herramienta de IA construya integraciones a medida para cada servicio, MCP proporciona un único protocolo que cualquier herramienta puede implementar.

Un servidor MCP es un proceso ligero que expone un conjunto de tools (funciones que la IA puede invocar), resources (datos que la IA puede leer) y prompts (plantillas que la IA puede usar). Cuando Claude Code se conecta a un servidor MCP, gana acceso a todas las tools que ese servidor proporciona.

Una forma sencilla de verlo:

Claude Code solo: puede leer/escribir archivos, ejecutar comandos de shell
Claude Code + servidores MCP: puede navegar por la web, consultar bases de datos, gestionar repos de GitHub, enviar mensajes, generar imágenes y cualquier otra cosa que puedas exponer a través de una tool

El protocolo usa JSON-RPC sobre entrada/salida estándar (stdio) o HTTP, lo que hace que sea sencillo de implementar en cualquier lenguaje.

Por qué MCP importa para los desarrolladores

Antes de MCP, ampliar las capacidades de un agente de IA significaba escribir plugins a medida con APIs propietarias para cada plataforma. Si construías una integración para una herramienta, tenías que reconstruirla desde cero para otra. MCP cambia esto al proporcionar:

Interoperabilidad: un servidor MCP funciona con Claude Code, Claude Desktop y cualquier otro cliente compatible con MCP
Componibilidad: puedes ejecutar varios servidores MCP simultáneamente, dándole a Claude Code acceso a decenas de tools a la vez
Simplicidad: el protocolo es ligero; un servidor MCP básico puede escribirse en menos de 100 líneas de código
Seguridad: las tools declaran sus capacidades por adelantado, y el cliente (Claude Code) controla qué tools se invocan

Servidores MCP populares para Claude Code

El ecosistema de MCP ha crecido rápidamente. Aquí están los servidores MCP más usados que los desarrolladores combinan con Claude Code.

Servidor de filesystem

El oficial @modelcontextprotocol/server-filesystem le da a Claude Code acceso controlado para leer y escribir archivos en directorios específicos. Aunque Claude Code ya tiene acceso a archivos, el servidor MCP de filesystem añade controles de permisos granulares y la capacidad de restringir el acceso a rutas concretas.

Casos de uso: operaciones de archivos en sandbox, acceso controlado a directorios de configuración, trabajar con archivos fuera de la raíz del proyecto.

Servidor de GitHub

El @modelcontextprotocol/server-github conecta Claude Code con la API de GitHub. Puede crear issues, abrir pull requests, revisar código, gestionar ramas, buscar en repositorios y más.

Casos de uso: revisiones de PR automatizadas, triaje de issues, gestión de repositorios, búsqueda de código en organizaciones.

Servidor de Slack

El @modelcontextprotocol/server-slack permite a Claude Code leer y enviar mensajes de Slack, gestionar canales y buscar en el historial de conversaciones.

Casos de uso: informes de standup automatizados, respuesta a incidentes, notificaciones de equipo, búsqueda de contexto en hilos de Slack.

Servidor de navegador / Puppeteer

El @anthropic/server-puppeteer le da a Claude Code un navegador headless que puede controlar: navegar por páginas, hacer clic en elementos, rellenar formularios y tomar capturas de pantalla.

Casos de uso: web scraping, pruebas de aplicaciones web, rellenar formularios, capturar evidencia visual de bugs.

Servidores de base de datos (PostgreSQL, SQLite)

Los servidores MCP de base de datos como @modelcontextprotocol/server-postgres y @modelcontextprotocol/server-sqlite permiten a Claude Code consultar bases de datos directamente, inspeccionar esquemas y ejecutar sentencias SQL.

Casos de uso: análisis de datos, exploración de esquemas, escritura y prueba de consultas, depuración de problemas de datos.

Configurar servidores MCP con Claude Code (método por CLI)

La forma estándar de configurar servidores MCP con Claude Code implica editar un archivo de configuración JSON. Repasemos la configuración de tres servidores populares.

Requisitos previos

Antes de empezar, asegúrate de tener:

Claude Code instalado (npm install -g @anthropic-ai/claude-code)
Node.js 18 o posterior
Las claves de API relevantes (token de GitHub, token de Slack, etc.)

Paso 1: configurar el servidor MCP de GitHub

Primero, instala el servidor MCP de GitHub globalmente:

npm install -g @modelcontextprotocol/server-github

A continuación, abre tu archivo de configuración MCP de Claude Code. Vive en ~/.claude.json en tu directorio home:

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

También puedes usar la CLI de Claude Code para añadirlo directamente:

claude mcp add github -- npx -y @modelcontextprotocol/server-github

Tras reiniciar Claude Code, verás disponibles las tools de GitHub. Puedes verificarlo pidiéndole a Claude Code que liste tus repositorios recientes o que cree un issue de prueba.

GitHub MCP server configured in Claude Code

Paso 2: configurar el servidor MCP de Slack

Instala y configura el servidor de Slack de forma similar:

npm install -g @anthropic/server-slack

Añádelo a tu ~/.claude.json:

{
  "mcpServers": {
    "github": { "..." : "..." },
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token",
        "SLACK_TEAM_ID": "T01234567"
      }
    }
  }
}

Para obtener un token de bot de Slack, necesitas crear una Slack App en el panel de la API de Slack, añadir los scopes de OAuth adecuados (channels:read, chat:write, search:read, etc.) e instalarla en tu workspace.

Paso 3: configurar el servidor MCP de PostgreSQL

Para el acceso a la base de datos:

npm install -g @modelcontextprotocol/server-postgres

Añade la configuración:

{
  "mcpServers": {
    "github": { "..." : "..." },
    "slack": { "..." : "..." },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:password@localhost:5432/mydb"
      ]
    }
  }
}

Tras añadir los tres, tu archivo ~/.claude.json contiene la configuración completa. Reinicia Claude Code y se conectará a los tres servidores MCP al arrancar.

Problemas comunes de la configuración por CLI

Configurar servidores MCP por CLI funciona, pero los desarrolladores se topan con problemas con frecuencia:

Errores de sintaxis JSON: una sola coma mal colocada en ~/.claude.json rompe todas las conexiones MCP
Problemas de rutas: el comando npx puede resolverse a distintas versiones de Node según la configuración de tu shell
Gestión de tokens: las claves de API almacenadas en texto plano en un archivo JSON se filtran con facilidad
Conflictos de versiones: los paquetes de servidores MCP pueden entrar en conflicto entre sí o con las dependencias de tu proyecto
Depuración: cuando un servidor MCP no arranca, Claude Code suele dar una salida de error mínima, lo que dificulta el diagnóstico
Requisito de reinicio: cada cambio de configuración requiere reiniciar Claude Code

Estos puntos de fricción son exactamente la razón por la que existen herramientas como SuperBuilder.

El enfoque de SuperBuilder: skills MCP en un clic

SuperBuilder es una aplicación de escritorio construida sobre Claude Code que reemplaza la configuración manual de MCP por un sistema de skills integrado. En lugar de editar archivos JSON y gestionar paquetes npm, activas capacidades con un solo interruptor.

Cómo funcionan las skills de SuperBuilder

Por debajo, SuperBuilder ejecuta su propio servidor MCP (superbuilder-skills) que se registra automáticamente con Claude Code al arrancar. Cuando activas una skill en el panel de configuración, SuperBuilder activa la tool correspondiente en su servidor MCP, sin necesidad de reiniciar.

La arquitectura es así:

SuperBuilder inicia un servidor MCP basado en HTTP en 127.0.0.1:3457
Escribe la configuración del servidor en ~/.claude.json automáticamente
Cuando Claude Code arranca, se conecta al servidor MCP de SuperBuilder
Las skills activadas exponen sus tools a través de esta única conexión

Esto significa que obtienes todos los beneficios de MCP sin nada de la sobrecarga de configuración.

Skill integrada: navegador web

La skill de navegador web de SuperBuilder no es una instancia headless de Puppeteer: es una BrowserWindow persistente con una sesión dedicada (persist:skills-browser). Esto significa:

Las cookies y el estado de sesión persisten entre peticiones. Inicia sesión en un servicio una vez y Claude Code podrá acceder a él en futuras sesiones.
Renderizado completo con Chrome DevTools. Sin rarezas de headless ni funciones que falten.
Retroalimentación visual. Puedes abrir la ventana del navegador y ver a Claude Code navegar en tiempo real.

Las tools disponibles incluyen browser_navigate, browser_click, browser_type, browser_get_content, browser_screenshot, browser_execute_js, browser_list_tabs y browser_switch_tab.

Para activarla, ve a Configuración, luego a Skills, y activa "Web Browser". Eso es todo.

// What you'd need in ~/.claude.json for Puppeteer:
{
  "mcpServers": {
    "puppeteer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/server-puppeteer"],
      "env": { "PUPPETEER_HEADLESS": "false" }
    }
  }
}

// What you need in SuperBuilder:
// Toggle: ON

SuperBuilder web browser skill in action

Skill integrada: generación de imágenes

La skill de generación de imágenes se conecta a la API DALL-E de OpenAI, permitiendo a Claude Code crear imágenes directamente dentro de tu conversación. Es útil para generar recursos provisionales, crear diagramas o producir contenido visual como parte de un flujo de trabajo de desarrollo.

La skill usa fetch nativo para comunicarse con la API de DALL-E, así que no hay dependencias adicionales que instalar. Solo añade tu clave de API de OpenAI en la configuración de la skill y actívala.

Skill integrada: consultas a base de datos

La skill de base de datos de SuperBuilder te permite registrar conexiones a bases de datos y consultarlas directamente desde Claude Code. Admite:

register_db_connection: añade una base de datos proporcionando una cadena de conexión
db_list_tables: muestra todas las tablas de la base de datos conectada
db_schema: inspecciona el esquema de una tabla específica
db_query: ejecuta consultas SQL y obtiene resultados
db_describe_all: obtiene una visión completa de la estructura de la base de datos

Esto es especialmente potente para depurar problemas de datos. Puedes pedirle a Claude Code que "compruebe si hay registros huérfanos en la tabla orders" y escribirá y ejecutará la consulta, para luego analizar los resultados.

Configuración por CLI vs. SuperBuilder: comparación lado a lado

Aspecto	Configuración por CLI	SuperBuilder
Configuración	Editar `~/.claude.json` manualmente	Interruptor en la interfaz de configuración
Dependencias	Instalar paquetes npm globalmente	Integrado, sin instalaciones
Gestión de claves de API	Texto plano en archivo JSON	Cifrado en la configuración de la app
Añadir nuevos servidores	Editar JSON, reiniciar Claude Code	Activar skill, inmediato
Depurar fallos	Leer stderr, revisar logs manualmente	Indicadores visuales de estado
Persistencia del navegador	No (nueva sesión cada vez)	Sí (sesión persistente)
Múltiples tools	Múltiples procesos de servidor	Un único servidor MCP
Actualizaciones	`npm update` manual por paquete	Automáticas con las actualizaciones de la app

CLI config vs SuperBuilder one-click comparison

Cómo construir servidores MCP personalizados

El ecosistema de MCP es abierto, y construir tu propio servidor es sencillo. Esto es útil cuando necesitas que Claude Code interactúe con una API interna, un servicio propietario o cualquier herramienta que no tenga un servidor MCP existente.

Estructura básica de un servidor MCP

Un servidor MCP necesita hacer tres cosas:

Declarar sus tools (qué funciones proporciona)
Manejar las llamadas a las tools (ejecutar la función cuando Claude Code la invoca)
Comunicarse mediante el protocolo MCP (JSON-RPC sobre stdio o HTTP)

Aquí tienes un servidor MCP mínimo en TypeScript usando el SDK oficial:

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: "my-custom-server",
  version: "1.0.0",
});

// Declare a tool
server.tool(
  "get_weather",
  "Get the current weather for a city",
  {
    city: z.string().describe("The city name"),
  },
  async ({ city }) => {
    // Your implementation here
    const weather = await fetchWeather(city);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(weather, null, 2),
        },
      ],
    };
  }
);

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);

Construir una skill personalizada para SuperBuilder

Si usas SuperBuilder, también puedes construir skills que se integren en su infraestructura MCP. Las skills de SuperBuilder siguen un patrón consistente:

Crea un módulo de skill que exporte manejadores de tools
Registra la skill con el servidor MCP de skills de SuperBuilder
Añade una entrada de configuración para que los usuarios puedan activarla/desactivarla

El sistema de skills usa las mismas primitivas de MCP por debajo, así que cualquier servidor MCP que construyas también puede envolverse como una skill de SuperBuilder. Esto te da lo mejor de ambos mundos: la skill funciona como servidor MCP independiente para usuarios de CLI, y los usuarios de SuperBuilder obtienen la experiencia en un clic.

Consejos para construir servidores MCP fiables

Basándonos en nuestra experiencia construyendo las skills integradas de SuperBuilder, aquí tienes algunas recomendaciones prácticas:

Mantén las descripciones de las tools claras y específicas. Claude Code usa la descripción de la tool para decidir cuándo invocarla. Descripciones vagas como "interactúa con el servicio" llevan a un mal uso. Sé explícito: "Busca mensajes de Slack que coincidan con una consulta en un canal específico."

Devuelve datos estructurados. En lugar de devolver texto libre, devuelve JSON que Claude Code pueda parsear y razonar. Esto hace que las preguntas de seguimiento sean más fiables.

Maneja los errores con elegancia. Si una llamada a la API falla, devuelve un mensaje de error claro como resultado de la tool en lugar de lanzar una excepción. Claude Code a menudo puede reintentar o probar un enfoque alternativo si entiende qué salió mal.

Implementa timeouts. Las peticiones de red pueden quedarse colgadas indefinidamente. Establece siempre timeouts razonables (10-30 segundos para llamadas a la API, 60 segundos para operaciones del navegador) y devuelve errores de timeout para que Claude Code no se quede esperando.

Registra logs para depurar. Escribe logs en stderr (para servidores stdio) o en un archivo de log. Cuando algo falle, agradecerás tener visibilidad de lo que estaba haciendo el servidor.

Consideraciones de seguridad para servidores MCP

Cuando conectas servidores MCP a Claude Code, le estás dando a un agente de IA acceso a servicios externos. Esto conlleva implicaciones de seguridad reales que deberías considerar antes de activar cualquier servidor en un entorno de producción.

Principio del mínimo privilegio

Concede solo los permisos mínimos que cada servidor MCP necesita. Para el servidor de GitHub, usa un personal access token granular acotado a repositorios específicos en lugar de un token clásico con acceso completo a los repos. Para servidores de base de datos, conéctate con un usuario de solo lectura a menos que necesites específicamente acceso de escritura.

Almacenamiento de tokens

El enfoque por CLI almacena los tokens en ~/.claude.json como texto plano. Cualquiera con acceso de lectura a tu directorio home puede verlos. Considera usar variables de entorno obtenidas de un gestor de secretos en lugar de codificar los valores directamente en el archivo JSON. SuperBuilder cifra las credenciales en la configuración de su app, lo que proporciona una capa de protección que el enfoque de JSON en crudo no tiene.

Exposición de red

Los servidores MCP que usan transporte HTTP (en lugar de stdio) escuchan en un puerto de red. Vincula siempre a 127.0.0.1 (solo localhost) en lugar de 0.0.0.0 para evitar el acceso externo. El servidor MCP integrado de SuperBuilder se vincula a 127.0.0.1:3457 por defecto, garantizando que solo sea accesible desde la máquina local.

Audita el uso de las tools

Mantén un ojo en qué tools está invocando Claude Code y con qué argumentos. Llamadas inesperadas a tools (como una consulta de base de datos que elimina una tabla o una navegación del navegador a una URL desconocida) pueden indicar una inyección de prompt o un malentendido. La vista de conversación de SuperBuilder muestra cada llamada a una tool y su resultado en línea, lo que facilita auditar lo que sucedió durante una sesión.

Patrones avanzados de MCP

Una vez que tengas servidores MCP básicos funcionando, hay varios patrones avanzados que desbloquean flujos de trabajo más potentes.

Encadenar varios servidores MCP

Una de las fortalezas de MCP es la componibilidad. Puedes ejecutar varios servidores simultáneamente, y Claude Code seleccionará la tool correcta del servidor correcto según el contexto. Por ejemplo:

GitHub + Slack: "Crea un issue de GitHub para este bug y luego publica un resumen en el canal de Slack #engineering"
Navegador + Base de datos: "Revisa el dashboard de producción en busca de picos de errores y luego consulta la base de datos de logs para más detalles"
Filesystem + Generación de imágenes: "Genera una imagen hero para la landing page y guárdala en el directorio public/images"

Claude Code gestiona la orquestación automáticamente: invocará la tool de GitHub para crear el issue, luego la de Slack para publicar el mensaje, todo dentro de un único turno de conversación.

Suscripciones a recursos

Los servidores MCP pueden exponer resources: datos de solo lectura a los que Claude Code puede acceder sin invocar una tool. Esto es útil para proporcionar contexto como esquemas de base de datos, documentación de API o archivos de configuración. Los resources también pueden admitir suscripciones, notificando a Claude Code cuando los datos subyacentes cambian.

Plantillas de prompt

Los servidores MCP pueden proporcionar plantillas de prompt: prompts predefinidos que guían a Claude Code a través de flujos de trabajo complejos. Por ejemplo, un servidor MCP de base de datos podría ofrecer un prompt de "revisión de migración" que indique a Claude Code que verifique un archivo de migración contra el esquema actual y señale posibles problemas.

Solución de problemas de conexión de servidores MCP

Incluso con la mejor configuración, las cosas pueden salir mal. Aquí están los problemas más comunes y cómo resolverlos.

El servidor no se conecta

Síntoma: Claude Code no muestra como disponibles las tools del servidor MCP.

Soluciones:

Verifica que ~/.claude.json sea JSON válido (usa cat ~/.claude.json | python -m json.tool)
Comprueba que la ruta del comando sea correcta (ejecuta el comando del servidor MCP manualmente en tu terminal)
Asegúrate de que las variables de entorno requeridas estén configuradas
Reinicia Claude Code tras los cambios de configuración

Las tools no se invocan

Síntoma: Claude Code reconoce que la tool existe pero nunca la invoca.

Soluciones:

Revisa la descripción de la tool; puede ser demasiado vaga para que Claude Code sepa cuándo usarla
Prueba a pedirle a Claude Code explícitamente que use la tool específica
Verifica que el esquema de entrada de la tool coincida con lo que Claude Code espera

Errores de timeout

Síntoma: las llamadas a las tools fallan con errores de timeout.

Soluciones:

Aumenta el timeout en la implementación de tu servidor MCP
Comprueba la conectividad de red con las APIs externas
Para servidores de base de datos, verifica la cadena de conexión y que la base de datos sea accesible

Fallos de autenticación

Síntoma: las tools devuelven errores 401 o 403.

Soluciones:

Verifica que los tokens de API no hayan expirado
Comprueba que los tokens tengan los scopes/permisos requeridos
Para servicios basados en OAuth, asegúrate de que el flujo de refresh token funcione

Troubleshooting MCP server connections checklist

Empezar con SuperBuilder

Si quieres saltarte por completo la configuración manual y empezar a usar tools potenciadas por MCP con Claude Code de inmediato, SuperBuilder es el camino más rápido.

Descarga SuperBuilder desde superbuilder.sh
Abre la app y crea tu primer proyecto
Ve a Configuración y luego a Skills
Activa las skills que quieras (navegador web, generación de imágenes, base de datos)
Inicia una conversación: Claude Code ahora tiene acceso a todas las tools activadas

Sin archivos JSON que editar. Sin paquetes npm que instalar. Sin necesidad de reiniciar.

SuperBuilder también ofrece una interfaz visual para gestionar tus conversaciones, un explorador de archivos integrado, organización de proyectos con Drive y modo de depuración para resolución de problemas complejos, todo construido sobre el mismo motor de Claude Code que ya conoces.

Flujos de trabajo del mundo real: servidores MCP en la práctica

Para concretarlo, aquí tienes tres flujos de trabajo que los desarrolladores usan a diario con Claude Code potenciado por MCP.

Flujo de trabajo 1: investigación de bugs

Un usuario reporta un bug en tu app web. Pegas la descripción del error en Claude Code. Con los servidores MCP activados, Claude Code puede:

Buscar en tus issues de GitHub para comprobar si este bug ya se ha reportado antes (MCP de GitHub)
Abrir la URL de producción y reproducir el problema visualmente (skill de navegador)
Consultar la base de datos de producción en busca de registros afectados (skill de base de datos)
Crear un issue de GitHub detallado con capturas de pantalla y datos (MCP de GitHub)
Publicar una actualización en el canal de Slack del equipo (MCP de Slack)

Sin MCP, tendrías que hacer los pasos del 2 al 5 manualmente, alternando entre pestañas del navegador, clientes de base de datos y Slack. Con MCP, Claude Code gestiona toda la investigación en una sola conversación.

Flujo de trabajo 2: validación de migración de datos

Has escrito una migración de base de datos y necesitas verificar que funciona correctamente. Con el servidor MCP de base de datos conectado, puedes pedirle a Claude Code que:

Inspeccione el esquema actual antes de la migración
Ejecute la migración
Compare el esquema tras la migración para verificar los cambios
Ejecute consultas de validación para garantizar la integridad de los datos
Genere un informe de resumen

Flujo de trabajo 3: pipeline de generación de contenido

Para equipos que generan contenido de marketing o documentación, la combinación de los servidores MCP de navegador, generación de imágenes y filesystem crea un pipeline potente. Claude Code puede investigar un tema navegando por páginas de la competencia, generar recursos visuales con DALL-E, escribir el contenido y guardarlo todo en los directorios de proyecto correctos, todo en una sola sesión.

Resumen

Los servidores MCP son la clave para desbloquear todo el potencial de Claude Code. Te permiten ampliar un agente de programación capaz hasta convertirlo en una herramienta que puede interactuar con prácticamente cualquier servicio o fuente de datos.

Tanto si eliges el enfoque por CLI (editar ~/.claude.json y gestionar procesos de servidor manualmente) como el enfoque de SuperBuilder (activar y desactivar skills en una interfaz visual), el protocolo subyacente es el mismo. Tu elección depende de cuánta sobrecarga de configuración quieras gestionar.

Para los desarrolladores que quieren empezar rápido y centrarse en construir en lugar de configurar, SuperBuilder ofrece la experiencia más fluida: navegación web, generación de imágenes y skills de base de datos integradas funcionan de fábrica con un solo clic.

¿Listo para potenciar Claude Code con MCP? Descarga SuperBuilder y empieza a usar skills hoy.