Cree un servidor MCP para Claude Code: una guía práctica y actualizada

CometAPI
AnnaNov 22, 2025
Cree un servidor MCP para Claude Code: una guía práctica y actualizada

El Protocolo de Contexto de Modelo (MCP) es un estándar abierto que permite que modelos como el de Anthropic Claude y herramientas para desarrolladores como Código de Claude Llamar a herramientas externas, fuentes de datos y avisos de forma segura y estándar.

Esta guía lo guiará en la construcción de su propio servidor MCP desde cero, lo que permitirá a Claude Code acceder a funciones personalizadas y así ampliar enormemente su funcionalidad mucho más allá de sus características integradas.

¿Qué es el Protocolo de Contexto Modelo (MCP)?

MCP (Protocolo de Contexto Modelo) es un especificación abierta Diseñado para estandarizar la conexión de los clientes de modelos de lenguaje (como Claude, Claude Code u otras interfaces LLM) a servidores de herramientas y fuentes de datos. Piense en MCP como un "puerto USB-C para LLM": define un esquema de transporte/JSON-RPC y una forma común para que los servidores publiquen tres tipos de capacidades:

  • Recursos — datos similares a archivos o documentos que un cliente puede leer (por ejemplo, una fila de base de datos, un archivo de texto, una carga útil JSON).
  • Herramientas — funciones invocables que el modelo puede solicitar al host que ejecute (con la aprobación del usuario).
  • Mensajes del sistema — plantillas de solicitud reutilizables o flujos de trabajo que el modelo/cliente puede invocar.

MCP admite múltiples transportes (stdio, HTTP, SSE) y proporciona esquemas, SDK y servidores de ejemplo para que no tenga que inventar el formato de la conexión. El protocolo se mantiene públicamente (especificaciones + SDK) y cuenta con tutoriales y una galería de servidores de ejemplo para acelerar su adopción.

¿Cómo está diseñado MCP?

La arquitectura de MCP es intencionalmente simple y modular: las piezas centrales son MCP servidores, MCP clientes e transportes que transportan mensajes enmarcados JSON-RPC entre sí. A continuación, se presentan los componentes principales con los que interactuará al crear un servidor para Claude Code (u otros clientes MCP).

Servidor, cliente y el protocolo

  • Servidor MCP — Un servicio que publica Herramientas, recursos e indicaciones. Las herramientas pueden ejecutar efectos secundarios o recuperar datos; los recursos muestran contenido de solo lectura; las indicaciones son plantillas de indicaciones reutilizables que el cliente puede solicitar al modelo para que las muestre.
  • Cliente MCP (host) — Normalmente forma parte del host LLM (p. ej., Claude Code, un complemento de VS Code o un cliente de navegador). Detecta los servidores disponibles, presenta descripciones de herramientas al modelo y enruta las llamadas iniciadas por el modelo a los servidores.
  • Protocolo — Los mensajes se codifican como JSON-RPC; la especificación define eventos del ciclo de vida, descubrimiento de herramientas, invocación, finalizaciones/muestreos y cómo los resultados estructurados se transportan de regreso al cliente y al modelo.

Patrón de comunicación (qué sucede cuando se utiliza una herramienta)

  1. El cliente envía un mensaje de usuario al modelo.
  2. El modelo analiza el contexto y decide llamar a una herramienta expuesta por MCP (o múltiples herramientas).
  3. El cliente reenvía la llamada de la herramienta al servidor MCP a través del transporte elegido.
  4. El servidor ejecuta la herramienta y devuelve resultados.
  5. El modelo recibe la salida de la herramienta y compone la respuesta final para el usuario.

Primitivas de implementación

  • JSON-RPC Los mensajes siguen el esquema MCP.
  • Definiciones de herramientas se publican en las respuestas de descubrimiento del servidor para que los clientes puedan presentarlos en la interfaz de usuario.
  • Recursos son referenciados por @source:path sintaxis por parte de los clientes (por ejemplo, @postgres:...), permitiendo que los modelos hagan referencia a contenido externo sin incluir grandes cantidades de datos en el mensaje.

¿Por qué integrar Claude Code con servidores MCP?

Claude Code es la oferta de Anthropic enfocada en flujos de trabajo centrados en el código y el desarrollador (integración de editor/IDE, comprensión del código, etc.). Al exponer sus herramientas internas (búsqueda de código fuente, ejecutor de CI, sistema de tickets, registros privados) a través de servidores MCP, Claude Code las puede llamar como herramientas de primera clase Dentro de conversaciones de codificación y flujos de agentes.

La integración de Claude Code con servidores MCP desbloquea capacidades prácticas y relevantes para la producción para un agente de codificación:

1. Deje que el modelo actuar en sistemas reales

Claude Code puede solicitar a un servidor MCP que consulte los rastreadores de incidencias, ejecute consultas a bases de datos, lea documentos extensos o genere solicitudes de cambio (PR) de GitHub, lo que permite la automatización integral desde la sesión de programación. Esto se admite explícitamente en la documentación de Claude Code (por ejemplo, consultar Postgres, Sentry o crear PR).

2. Descargue grandes cantidades de datos y lógica especializada

En lugar de integrar cada fuente de datos en el prompt (que consume tokens), se publican los datos y las herramientas mediante MCP. El modelo llama a la herramienta, obtiene una respuesta estructurada y razona con ella. Esto reduce el uso de tokens y permite a los servidores gestionar tareas pesadas (consultas a bases de datos, lecturas largas de archivos, autenticación).

3. Seguridad y gobernanza

MCP centraliza el control de acceso y la auditoría en la capa de servidor, lo que permite a las organizaciones incluir en la lista blanca servidores aprobados, controlar las herramientas disponibles y limitar la salida. Claude Code también admite la configuración empresarial de MCP y el consentimiento por ámbito.

4. Reutilización y ecosistema

Los servidores MCP son reutilizables entre clientes y equipos. Una vez compilados, muchos clientes Claude/LLM podrán usar los mismos servicios (o intercambiar implementaciones).

¿Qué necesitas antes de empezar?

Requisitos mínimos

  • Una máquina de desarrollo con Python 3.10 + (Usaremos Python en el ejemplo). Alternativamente, los SDK de MCP admiten Node y otros lenguajes.
  • uv (Herramienta de Astral) o un ejecutor equivalente para ejecutar servidores MCP stdio (el tutorial de MCP utiliza uv). Los pasos de instalación se muestran a continuación.
  • Claude Code instalado o acceso al cliente de Claude (de escritorio o CLI) para registrar y probar su servidor; o cualquier cliente compatible con MCP. Claude Code es compatible con HTTP, SSE y servidores stdio locales.
  • Nota de seguridad:Agregue solo servidores MCP confiables a Claude Code en configuraciones de equipo o empresariales: MCP brinda a los servidores acceso a datos confidenciales y existen riesgos de inyección inmediata si un servidor devuelve contenido malicioso.

Cómo instalar y verificar la CLI de Claude Code

Es Guía de instalación y uso de Claude Code.

1) Resumen rápido: métodos de instalación recomendados

Use la opción instalador nativo (recomendado) o Homebrew en macOS/Linux. NPM está disponible si necesita una instalación basada en Node. Windows incluye instaladores de PowerShell/CMD. Fuente: documentación oficial de Claude Code y GitHub.

2) Requisitos previos

  • macOS 10.15+, Ubuntu 20.04+/Debian 10+ o Windows 10+ (se recomienda WSL en Windows).
  • Nodo.js 18+ solo requerido para el método de instalación NPM.

3) Comandos de instalación (seleccione uno)

Nativo (recomendado, sin dependencia de nodo), macOS/Linux/WSL:

curl -fsSL https://claude.ai/install.sh | bash
# optional: install latest explicitly

curl -fsSL https://claude.ai/install.sh | bash -s latest
# or install a specific version

curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex
# or for latest: & (::Create((irm https://claude.ai/install.ps1))) latest

(Éstos son los scripts de instalación nativos oficiales).

NPM (si desea una instalación global basada en nodos):

# requires Node.js 18+

npm install -g @anthropic-ai/claude-code

No use sudo npm install -g — advertir contra instalaciones globales de sudo (problemas de permisos/seguridad). Si encuentra errores de permisos, use nvm o arregle su prefijo global npm en lugar de usar sudo.

4) Verificar que se instaló el binario (verificaciones básicas)

Ejecútelos localmente inmediatamente después de la instalación:

# is the command on PATH?

which claude

# version (or -v)

claude --version
# or

claude -v

# help (sanity check)

claude --help

Esperado: which muestra una ruta (por ejemplo /usr/local/bin/claude or ~/.nvm/.../bin/claude) y claude --version Imprime una cadena similar a Semver. Tanto la documentación como el archivo README muestran claude como punto de entrada CLI principal.

5) Verificar el estado y la configuración de la instalación (comprobaciones recomendadas)

a) claude doctor,Correr:

claude doctor

Este diagnóstico integrado verifica el tipo de instalación, problemas comunes (como problemas de permisos de npm), dependencias como ripgrepy sugiere soluciones. La documentación recomienda explícitamente ejecutar claude doctor después de la instalación

b) Ejecutar una prueba de humo (no interactiva)

Desde el directorio de su proyecto:

cd /path/to/your/project
claude -p "Explain this project in 3 sentences"

Esto usa Imprimir modo (-p) para enviar un solo mensaje y luego salir; útil para CI o verificaciones funcionales rápidas.

c) Verificación de autenticación (asegúrese de que la CLI pueda comunicarse con Anthropic)

Claude Code admite varios flujos de autenticación (OAuth de consola, clave API e integraciones con proveedores). Comprobaciones comunes:

  1. Si se utiliza una clave API (CI/headless/variable de entorno local):
export ANTHROPIC_API_KEY="sk-..."
# then

claude auth status
claude auth whoami    # or `claude auth whoami` / `claude whoami` depending on version

Puedes usar CometAPIClave API de para usar Claude Code. Usar la API de Claude a través de CometAPI le dará un 20% de descuento.

  1. Si utilizó OAuth a través de la consola - correr:
claude auth status
claude auth whoami

Debería ver información de la cuenta/plan o una confirmación de que está autenticado.

Preparación del entorno paso a paso

A continuación se presentan pasos concretos para preparar dos pilas de desarrolladores comunes (TypeScript y Python), seguidos de comprobaciones rápidas para garantizar que todo funcione.

H3 — A. Configuración de TypeScript/Node (ruta más rápida)

  1. Crear proyecto e instalar SDK:
mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk express zod
npm install --save-dev typescript tsx @types/node @types/express
  1. Crea server.ts(Proporcionamos un ejemplo completo en la sección “Cómo construir rápidamente…”).
  2. Ejecutar:
npx -y tsx server.ts
  1. Pruebe localmente con el Inspector de MCP o añadir al Código Claude:
npx @modelcontextprotocol/inspector
# or (for Claude Code)

claude mcp add --transport http my-server http://localhost:3000/mcp

(Los comandos Inspector y Claude le permiten validar el descubrimiento e invocar herramientas).

¿Cómo construir rápidamente un servidor MCP para Claude Code?

lista de verificación rápida

  1. Inicie su servidor (se recomienda HTTP con transmisión): node server.ts or uvicorn server:app.

  2. Desde su máquina de desarrollo, puede:

  • Use Inspector de MCP para validar (npx @modelcontextprotocol/inspector) y confirmar tools/list y resources/list, o
  • Añade el servidor a Claude Code: claude mcp add --transport http <name> http://<host>:<port>/mcp (o siga los flujos de la interfaz de usuario web si su cliente admite MCP remoto).

Si planea utilizar el conector API de mensajes de Anthropic para MCP remoto (sin cliente separado), lea la documentación de Claude: es posible que se requiera un encabezado beta (consulte la documentación para conocer el encabezado exacto y el estado de soporte actual).

A continuación se muestran dos ejemplos de servidor completos pero compactos que puede copiar, ejecutar y conectar a Claude Code (o al Inspector MCP). El ejemplo de TypeScript usa Express y el SDK de TypeScript; el ejemplo de Python muestra un montaje FastAPI.

Nota: El código a continuación sigue los ejemplos públicos del SDK y se ha minimizado intencionalmente para mayor claridad. Para producción, añada autenticación, registro, limitación de velocidad y validación de entrada además de los valores predeterminados del SDK.

Ejemplo 1: TypeScript + Express (HTTP con transmisión continua)

Crea server.ts (completo):

// server.ts
import express from "express";
import * as z from "zod/v4";
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const server = new McpServer({ name: "claude-code-demo", version: "0.1.0" });

// Register a simple tool: add two numbers
server.registerTool(
  "add",
  {
    title: "Add",
    description: "Add two numbers a and b",
    inputSchema: { a: z.number(), b: z.number() },
    outputSchema: { result: z.number() }
  },
  async ({ a, b }) => {
    const output = { result: a + b };
    return {
      content: ,
      structuredContent: output
    };
  }
);

// Register a resource: greet user (dynamic)
server.registerResource(
  "greeting",
  new ResourceTemplate("greeting://{name}", { list: undefined }),
  { title: "Greeting", description: "Return a greeting for the name" },
  async (uri, params) => {
    return {
      contents: 
    };
  }
);

// Express + Streamable HTTP transport
const app = express();
app.use(express.json());

app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({ enableJsonResponse: true });
  // Close transport when connection closes
  res.on("close", () => transport.close());
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

const port = parseInt(process.env.PORT || "3000", 10);
app.listen(port, () => console.log(`MCP server listening: http://localhost:${port}/mcp`));

Ejecutar:

npm install
npx -y tsx server.ts

Luego conéctese en Código Claude (ejemplo):

# Add the remote server to your Claude Code MCP list (local dev)

claude mcp add --transport http my-demo http://localhost:3000/mcp

Este ejemplo es una adaptación del inicio rápido oficial del SDK de TypeScript y demuestra cómo registrar herramientas y recursos y luego exponerlos a través de HTTP Streamable.

Ejemplo 2: Python + FastAPI (FastMCP + HTTP transmisible)

Crea server.py (completo):

# server.py

from fastapi import FastAPI
from mcp.server.fastmcp import FastMCP

app = FastAPI()
mcp = FastMCP("claude-python-demo", stateless_http=True)

# tool: simple sum

@mcp.tool()
def add(a: int, b: int) -> dict:
    """Add two integers"""
    return {"result": a + b}

# resource: simple greeting resource template

@mcp.resource("greeting://{name}")
def greeting(name: str):
    return {"contents": }

# mount the streamable-http MCP endpoint (FastMCP exposes an ASGI app)

app.mount("/mcp", mcp.streamable_http_app())

# optional endpoint to demonstrate other API routes

@app.get("/")
async def root():
    return {"status": "OK"}

Ejecutar:

uvicorn server:app --reload --port 8000

Conéctese con el Inspector:

npx @modelcontextprotocol/inspector
# In Inspector select Streamable HTTP and enter http://localhost:8000/mcp

Los ejemplos del SDK de Python y las utilidades FastMCP facilitan el registro @mcp.tool() y @mcp.resource() funciones decoradas que el LLM puede descubrir y llamar.

¿Cómo llama realmente Claude Code a sus herramientas?

Cuando un LLM decide usar una herramienta, el cliente envía una invocación JSON-RPC al servidor MCP. El servidor ejecuta la herramienta solicitada (por ejemplo, consulta una base de datos, ejecuta pruebas o llama a una API externa) y la devuelve. contenido estructurado y contenido presentableEl cliente (Claude Code) puede entonces incluir la salida estructurada en el contexto del modelo para que este pueda continuar razonando con esos datos fiables, no solo con la salida textual del servidor. El SDK de TypeScript admite el registro. inputSchema y outputSchema (zod) para que los argumentos y las salidas sean validados y tipificados por máquina.

¿Qué herramientas de prueba y depuración debería utilizar?

Inspector de MCP

El elemento Inspector de MCP Es la herramienta visual oficial para desarrolladores que permite probar servidores MCP. Permite conectarse a un servidor (stdio, SSE o HTTP con transmisión), listar herramientas, invocarlas manualmente e inspeccionar el ciclo de vida de los mensajes JSON-RPC, una herramienta invaluable durante el desarrollo. Iníciela a través de npx @modelcontextprotocol/inspector.

Pruebas locales vs. pruebas remotas

  • Local (stdio) — ciclo de iteración rápido para aplicaciones de escritorio y depuración sin conexión.
  • HTTP transmisible — Pruebe con el Inspector o conéctese a Claude Code usando el claude mcp add CLI o el conector MCP de la API de Mensajes para pruebas remotas. Asegúrese de proporcionar los encabezados de autenticación necesarios para su servidor.

Conclusión

MCP es el puente práctico entre los LLM modernos y los sistemas que realmente almacenan los datos y ejecutan las acciones. Para los flujos de trabajo de código, la integración de Claude Code con un servidor MCP proporciona al modelo acceso estructurado y auditable a repositorios, CI, rastreadores de incidencias y herramientas personalizadas, lo que resulta en una automatización más precisa y efectos secundarios más seguros. Con los SDK oficiales en TypeScript y Python, HTTP Streamable para alojamiento remoto y herramientas como MCP Inspector, puede crear un servidor mínimo en minutos e iterar hacia una implementación de producción.

Los desarrolladores pueden acceder Claude Sonnet 4.5 API  y  API de Claude Opus 4.1 etc. a través de CometAPI, la última versión del modelo Se actualiza constantemente con el sitio web oficial. Para empezar, explora las capacidades del modelo en el Playground y consultar el Guía de API Para obtener instrucciones detalladas, consulte la sección "Antes de acceder, asegúrese de haber iniciado sesión en CometAPI y de haber obtenido la clave API". CometAPI Ofrecemos un precio muy inferior al oficial para ayudarte a integrarte.

¿Listo para ir?→ Regístrate en CometAPI hoy !

Si quieres conocer más consejos, guías y novedades sobre IA síguenos en VK, X  y  Discord!

Leer Más

500+ Modelos en Una API

Hasta 20% de Descuento