Guía práctica para configurar servidores MCP (Model Context Protocol) con Claude Code: instalación, configuración, modos de transporte, definición de herramientas y cómo conectar modelos de IA con APIs y servicios reales. Ejemplos que puedes copiar y ejecutar hoy.
Si has pasado un rato en Claude Code y te has fijado en la sección de MCP de los ajustes, seguramente te has preguntado qué hace exactamente, lo difícil que es de montar y si merece la pena el esfuerzo. La respuesta corta: sí, merece mucho la pena. MCP (Model Context Protocol) es el mecanismo que permite a Claude salir de su ventana de contexto y llamar a funciones reales, consultar bases de datos reales e interactuar con APIs reales, todo desde dentro de una conversación.
Este artículo recorre todo, desde entender qué es MCP hasta ejecutar tu primer servidor personalizado con Claude Code, con ejemplos de configuración reales que puedes copiar al momento.
MCP es un protocolo abierto desarrollado por Anthropic que estandariza la forma en que los modelos de IA se comunican con herramientas y fuentes de datos externas. En la práctica, es un intercambio estructurado: tu servidor declara qué herramientas ofrece, y Claude las llama con los argumentos adecuados y gestiona los resultados.
Antes de MCP, cada integración era a medida. Escribías prompts de sistema especiales, improvisabas esquemas de llamadas a funciones y esperabas que el modelo siguiera la especificación. MCP reúne todo eso en una única capa predecible.
El protocolo define tres primitivas básicas:
| Primitiva | Descripción |
|---|---|
| Tools | Funciones que el modelo puede llamar (por ejemplo, buscar, obtener o escribir un archivo) |
| Resources | Datos que el modelo puede leer (por ejemplo, archivos o registros de una base de datos) |
| Prompts | Plantillas de prompt reutilizables que expone el servidor |
Estas tres primitivas cubren prácticamente todos los escenarios de integración que te vas a encontrar. Las herramientas gestionan acciones, los recursos gestionan el acceso a datos y los prompts gestionan patrones de interacción reutilizables. El protocolo es independiente del transporte, lo que significa que el mismo código de servidor funciona por stdio para desarrollo local y por HTTP para despliegues en producción.
Los servidores MCP funcionan en uno de dos modos de transporte. Conocer la diferencia te ahorrará horas de depuración.
El cliente (Claude Code) lanza tu servidor como un subproceso y se comunica por stdin/stdout. Es la configuración más sencilla para herramientas locales y flujos de trabajo personales. No necesita puertos, ni red, ni autenticación.
{
"mcpServers": {
"my-tool": {
"command": "node",
"args": ["/absolute/path/to/server/dist/index.js"]
}
}
}
Tu servidor se ejecuta como un proceso HTTP independiente. Claude Code se conecta a él a través de la red. Es la opción adecuada para servidores compartidos por un equipo, despliegues en la nube o cualquier servidor que deba seguir activo entre sesiones.
{
"mcpServers": {
"my-tool": {
"url": "http://localhost:3000/sse"
}
}
}
💡 Empieza con stdio. No requiere configurar nada de red y es mucho más fácil de depurar. Cambia al transporte HTTP solo cuando necesites acceso compartido o un estado persistente del servidor.
Todo servidor MCP empieza igual: instalar el SDK oficial y configurar TypeScript para ESM.
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node
Inicializa TypeScript:
npx tsc --init
Actualiza tsconfig.json para usar módulos ESM:
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./dist",
"strict": true
}
}
Añade los scripts a package.json:
{
"type": "module",
"scripts": {
"build": "tsc",
"dev": "tsx src/index.ts"
}
}
El campo "type": "module" no es opcional. Sin él, Node trata tus archivos como CommonJS y todas las importaciones ESM fallan al arrancar.
Crea src/index.ts y define tu primera herramienta con un esquema Zod tipado:
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-first-server",
version: "1.0.0",
});
server.tool(
"get_weather",
"Get current weather for a city",
{
city: z.string().describe("City name"),
units: z.enum(["celsius", "fahrenheit"]).optional().default("celsius"),
},
async ({ city, units }) => {
const temp = units === "celsius" ? "22°C" : "72°F";
return {
content: [
{
type: "text",
text: `Weather in ${city}: ${temp}, partly cloudy`,
},
],
};
}
);
const transport = new StdioServerTransport();
await server.connect(transport);
Compílalo y comprueba que no da errores:
npx tsc
node dist/index.js
Ya tienes un servidor MCP funcionando. Expone una herramienta con un esquema tipado que Claude valida antes de llamarla.
Abre los ajustes de Claude Code y ve a la sección de MCP. Añade la entrada de tu servidor usando la ruta absoluta a la salida compilada:
{
"mcpServers": {
"my-first-server": {
"command": "node",
"args": ["/absolute/path/to/my-mcp-server/dist/index.js"]
}
}
}
Reinicia Claude Code. Abre una conversación nueva y pregunta: "¿Qué tiempo hace en París?"
Si todo está bien conectado, Claude llamará a get_weather con city: "Paris" y mostrará el resultado en su respuesta. Verás aparecer la llamada a la herramienta en la conversación.
💡 Usa siempre rutas absolutas en tu configuración de MCP. Las rutas relativas fallan sin avisar, según cómo resuelva Claude Code su directorio de trabajo al arrancar.
Los servidores reales necesitan una separación clara entre las definiciones de esquemas, los manejadores y la lógica de servicio. Esta es la estructura de archivos que escala sin volverse difícil de mantener:
src/
index.ts # Entry point and server setup
tools/
definitions.ts # Zod schemas for each tool input
handlers.ts # Business logic per tool
services/
api.ts # External API calls
db.ts # Database access layer
definitions.ts contiene todos los esquemas Zod:
import { z } from "zod";
export const searchInputSchema = {
query: z.string().min(1).describe("Search query text"),
limit: z.number().int().min(1).max(50).optional().default(10),
};
handlers.ts contiene la implementación:
export async function handleSearch(
args: { query: string; limit?: number }
) {
const results = await searchApi(args.query, args.limit ?? 10);
return {
content: [{ type: "text" as const, text: JSON.stringify(results, null, 2) }],
};
}
index.ts conecta todo en una única llamada a server.tool() por herramienta. Esta separación te permite probar los manejadores sin tener un servidor en ejecución y cambiar los esquemas sin tocar la lógica de negocio.
Estos son los errores que hacen tropezar a casi todo el que construye su primer servidor MCP.
1. Faltan las extensiones .js en las importaciones
La resolución de módulos Node16 exige extensiones .js explícitas incluso dentro de los archivos fuente de TypeScript. Si las omites, las importaciones fallan en tiempo de ejecución, y resulta confuso porque el compilador de TypeScript no lo detecta.
// This fails at runtime with ERR_MODULE_NOT_FOUND
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
// This works correctly
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2. Usar console.log() en servidores stdio
En modo stdio, stdout es el canal del protocolo. Cualquier llamada a console.log() escribe texto arbitrario en ese canal y corrompe el flujo de MCP. Usa console.error() para toda la salida de depuración.
3. Falta await en la conexión del servidor
// Wrong: process may exit before connection completes
server.connect(transport);
// Correct: wait for connection handshake
await server.connect(transport);
4. Rutas relativas en la configuración de Claude Code
Claude Code se lanza desde directorios de trabajo distintos. Usa siempre rutas absolutas fijas o resuélvelas al arrancar con import.meta.url.
5. Descripciones de herramientas demasiado genéricas
Claude usa la descripción de la herramienta para decidir cuándo llamarla. Las descripciones vagas como "hace cosas" hacen que la herramienta se llame con demasiada frecuencia o nunca. Sé específico: "Obtiene una pull request de GitHub a partir del propietario, el repositorio y el número de PR".
Cuando tu servidor necesita compartirse entre un equipo o ejecutarse en un entorno en la nube, HTTP con SSE es el transporte adecuado:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import express from "express";
const app = express();
const server = new McpServer({ name: "team-server", version: "1.0.0" });
const transports: Record<string, SSEServerTransport> = {};
app.get("/sse", async (req, res) => {
const transport = new SSEServerTransport("/messages", res);
transports[transport.sessionId] = transport;
await server.connect(transport);
});
app.post("/messages", express.json(), async (req, res) => {
const sessionId = req.query.sessionId as string;
const transport = transports[sessionId];
if (transport) await transport.handlePostMessage(req, res);
});
app.listen(3000, () => console.error("MCP server listening on :3000"));
Cada cliente de Claude Code guarda su propio transporte de sesión, así varios usuarios pueden conectarse a la vez sin interferencias.
Los resources permiten a Claude leer datos estructurados sin llamadas explícitas a herramientas. Son la primitiva adecuada para la configuración, la documentación o el estado en caché que Claude debe conocer sin que tengas que definir una herramienta de obtención específica.
server.resource(
"config://app",
"Application configuration and feature flags",
async (uri) => ({
contents: [
{
uri: uri.toString(),
mimeType: "application/json",
text: JSON.stringify({
version: "2.1.0",
features: { darkMode: true, betaSearch: false },
limits: { maxResults: 50, timeoutMs: 5000 },
}),
},
],
})
);
Claude puede consultar config://app en su contexto y leer estos datos de forma proactiva, lo que reduce el número de llamadas a herramientas necesarias en una conversación.
MCP Inspector es imprescindible durante el desarrollo. Te ofrece una interfaz visual para llamar a tus herramientas directamente, sin pasar por Claude Code:
npx @modelcontextprotocol/inspector node dist/index.js
Abre http://localhost:5173. Verás todas las herramientas registradas, sus esquemas y un formulario para llamar a cada una directamente con los datos que quieras. El JSON de la petición y de la respuesta es visible, lo que facilita muchísimo detectar desajustes de tipos o campos que faltan.
Para servidores HTTP:
npx @modelcontextprotocol/inspector http://localhost:3000/sse
💡 Vigila los desajustes de esquema. Si Claude Code dice que una herramienta está registrada pero nunca la llama, la causa más habitual es un esquema Zod que rechaza los argumentos que proporciona el modelo. El Inspector te permite reproducir el problema sin involucrar a Claude.
Uno de los patrones de mayor valor consiste en construir servidores MCP que orquesten llamadas a varios modelos de IA. Tu servidor pasa a ser la capa de middleware y Claude Code, el coordinador.
Puedes exponer una herramienta que dirija las peticiones a Deepseek R1 para razonamiento profundo, a GPT 5 para escritura creativa o a Llama 4 Scout Instruct para procesar documentos rápidamente. Claude decide qué herramienta llamar según la tarea que tenga entre manos.
server.tool(
"route_to_model",
"Route a task to the most suitable language model for the job",
{
task: z.enum(["reasoning", "creative", "summarize"]),
input: z.string().describe("The text input to process"),
},
async ({ task, input }) => {
const modelMap = {
reasoning: "deepseek-r1",
creative: "gpt-5",
summarize: "llama-4-scout",
};
const result = await callModelApi(modelMap[task], input);
return { content: [{ type: "text", text: result }] };
}
);
Con Claude Opus 4.7 como orquestador y tu servidor MCP como capa de despacho, obtienes un sistema multimodelo que enruta de forma inteligente sin una infraestructura compleja.
Picasso IA ofrece acceso por API a modelos como Claude 4.5 Sonnet, Gemini 2.5 Flash y Claude 4 Sonnet, lo que facilita crear herramientas MCP multimodelo sin gestionar claves de API separadas ni bibliotecas cliente para cada proveedor.
Las herramientas de MCP nunca deberían lanzar excepciones sin controlar. Devuelve contenido de error estructurado para que Claude pueda informar de los fallos con claridad y decidir qué hacer a continuación:
server.tool(
"safe_fetch",
"Fetch content from an external URL",
{ url: z.string().url() },
async ({ url }) => {
try {
const response = await fetch(url);
if (!response.ok) {
return {
content: [
{
type: "text",
text: `Request failed: HTTP ${response.status} from ${url}`,
},
],
isError: true,
};
}
return { content: [{ type: "text", text: await response.text() }] };
} catch (err) {
return {
content: [{ type: "text", text: `Network error: ${String(err)}` }],
isError: true,
};
}
}
);
El flag isError: true indica a Claude que la llamada ha fallado. Claude decidirá entonces si reintenta, usa una alternativa o muestra el error al usuario.
Una vez que tengas lo básico funcionando, se abre un territorio práctico. Estos son los patrones que los equipos están desplegando hoy con MCP:
| Caso de uso | Qué hace |
|---|---|
| Herramienta de base de datos | Claude escribe y ejecuta consultas SQL acotadas de forma segura |
| Explorador del sistema de archivos | Acceso de lectura y escritura a directorios concretos del proyecto |
| Envoltorio de API | Expone Jira, GitHub o Slack como herramientas invocables |
| Pipeline de imágenes | Conecta Claude con APIs de generación de imágenes a partir de texto |
| Sandbox de código | Ejecuta y prueba fragmentos de código en un contenedor aislado |
| Recuperador RAG | Busca en una base de datos vectorial y devuelve los fragmentos relevantes |
El caso del pipeline de imágenes es especialmente potente. Construyes un servidor MCP que recibe un prompt de texto de Claude, llama a un modelo de texto a imagen, sube el resultado a almacenamiento en la nube y devuelve la URL, todo en una única llamada a herramienta que Claude encadena de forma natural en la conversación, sin código de orquestación adicional.
Para los equipos que construyen flujos de trabajo con generación de imágenes, los más de 90 modelos disponibles en plataformas como Picasso IA se pueden integrar como herramientas MCP, dando a Claude acceso directo a modelos de difusión, upscalers y pipelines de edición desde dentro de una conversación.
Si quieres ver lo que es posible con los modelos de IA antes de construir tus propias integraciones MCP, Picasso IA pone más de 90 modelos de texto a imagen y decenas de modelos de lenguaje (LLM) directamente en tu navegador. Ejecuta Claude Opus 4.6, GPT 5, Deepseek R1 o Llama 4 Maverick Instruct sin ninguna configuración.
Es la forma más rápida de probar la salida de un modelo antes de comprometerte con una integración por API. Elige un modelo, envía un prompt y mira exactamente con qué vas a trabajar en tu conjunto de herramientas MCP. Tanto si generas imágenes para un proyecto como si pruebas estructuras de prompt o exploras cómo responden distintos modelos a la misma entrada, la plataforma te da acceso rápido sin la sobrecarga de infraestructura.
Crea una cuenta, elige un modelo y empieza a generar imágenes o texto hoy mismo, sin archivos de configuración.
Elige tu idioma
