Cómo crear un servidor MCP: tutorial paso a paso en Python y TypeScript (2026)

Puedes crear un servidor MCP que Claude llame de verdad en unos 15 minutos. Lo cronometramos en Node 20 y Python 3.11: una herramienta add funcional, corriendo sobre stdio y reconocida por Claude Desktop, tardó 14 minutos la primera vez y menos de 5 una vez que conoces la estructura. Este tutorial construye el mismo servidor dos veces, una en Python con FastMCP 2.x y otra en TypeScript con @modelcontextprotocol/sdk 1.x, para que elijas tu stack y copies código real. Si primero quieres la arquitectura y la teoría del protocolo, nuestra guía del Model Context Protocol la cubre; aquí solo construimos.

Servidor MCP, inicio rápido: qué vas a construir

Un servidor MCP es un programa pequeño que expone herramientas, datos y plantillas de prompt a clientes de IA como Claude, Cursor o VS Code mediante el Model Context Protocol. Escribes el servidor una vez y cualquier cliente compatible con MCP puede llamarlo. En este tutorial construyes un servidor con dos herramientas (una calculadora add y un ayudante fetch_url), lo ejecutas localmente sobre stdio, lo pruebas y lo conectas a un cliente real.

Esto es todo lo que necesitas antes de empezar.

Ambas vías producen un servidor con comportamiento idéntico. Elige el lenguaje con el que tu equipo ya trabaja. Si no tienes preferencia, empieza con Python, porque FastMCP hace que el primer servidor sea más corto.

¿Qué expone realmente un servidor MCP?

Antes de escribir código, conviene saber qué tres cosas puede ofrecer un servidor. Un servidor MCP expone tools (funciones que el modelo puede llamar, como "consultar la base de datos"), resources (datos de solo lectura que el modelo puede cargar, como un archivo o un registro) y prompts (plantillas de prompt reutilizables). La mayoría de los servidores que construyas serán intensivos en herramientas; los resources y prompts son opcionales.

Servidor MCP, definido: un proceso que habla el Model Context Protocol y anuncia una lista de herramientas, resources y prompts que un cliente de IA puede descubrir e invocar en tiempo de ejecución.

El cliente (Claude Desktop, por ejemplo) actúa como host. Inicia tu servidor o se conecta a él, pregunta "¿qué herramientas tienes?" y luego las llama cuando el modelo decide que una herramienta es útil. Nunca llamas al modelo desde dentro del servidor. El flujo va en la otra dirección.

Esa dirección importa. Tu servidor es un proveedor pasivo. Espera a que el cliente se conecte, responde a la solicitud de descubrimiento y ejecuta la herramienta que se llame. Mantén este modelo mental y el resto de este tutorial encaja solo.

Cómo crear un servidor MCP en Python (paso a paso)

Python es la vía más rápida a un servidor en marcha, porque FastMCP gestiona la fontanería del protocolo y convierte funciones simples en herramientas con un decorador. Todo lo de abajo usa el SDK de Python oficial. Estos son los cuatro pasos.

Paso 1: configurar el proyecto. Usa uv, que ya es el estándar para proyectos MCP en Python:

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

Si prefieres pip: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

Paso 2: escribir el servidor. Crea server.py:

from mcp.server.fastmcp import FastMCP
import httpx

# Name shows up in the client's tool list
mcp = FastMCP("demo-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers and return the sum."""
    return a + b

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Fetch a URL and return the first 2000 characters of the body."""
    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.get(url)
        return resp.text[:2000]

if __name__ == "__main__":
    mcp.run()  # defaults to stdio transport

Dos cosas a notar. El docstring se convierte en la descripción de la herramienta que el modelo lee, así que escríbelo como una instrucción. Y las anotaciones de tipo (a: int) se convierten automáticamente en el esquema de entrada, de modo que FastMCP genera el esquema JSON por ti.

Paso 3: ejecutarlo. mcp.run() arranca el servidor sobre stdio, el transporte que los clientes lanzan localmente. No lo ejecutas directamente durante el desarrollo; el cliente lo lanza. Para una prueba rápida usa el runner de desarrollo:

uv run mcp dev server.py

Paso 4: devolver una salida limpia. Una trampa que conviene señalar ya: devuelve una cadena o un valor tipado, no un dict anidado esperando que se renderice. Volveremos a esto en la sección de producción, pero en resumen, los tipos de retorno ambiguos pueden truncarse en silencio en algunos clientes.

Este es un servidor MCP de Python completo. Dos herramientas, llamadas de red reales, esquema automático. A continuación, lo mismo en TypeScript.

Cómo crear un servidor MCP en TypeScript (paso a paso)

La vía TypeScript usa el SDK de TypeScript oficial directamente y zod para validar la entrada. Es un poco más verbosa que FastMCP, pero los tipos son excelentes y se despliega limpiamente en hosts de Node.

Paso 1: configurar el proyecto.

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

Paso 2: escribir el servidor. Crea server.ts:

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

server.tool(
  "add",
  "Add two numbers and return the sum.",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

server.tool(
  "fetch_url",
  "Fetch a URL and return the first 2000 characters.",
  { url: z.string().url() },
  async ({ url }) => {
    const resp = await fetch(url);
    const body = await resp.text();
    return { content: [{ type: "text", text: body.slice(0, 2000) }] };
  },
);

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

Paso 3: ejecutarlo. Durante el desarrollo: npx tsx server.ts. Para producción, compila con tsc y ejecuta el .js generado con Node. Fíjate en la forma de retorno: cada herramienta devuelve { content: [{ type: "text", text: ... }] }. Ese array content explícito es el equivalente en TypeScript de la regla "devuelve una cadena limpia" de Python. El SDK quiere bloques de contenido tipados, no objetos en bruto.

Paso 4: validar la entrada con zod. El esquema z.string().url() rechaza entradas inválidas antes de que se ejecute tu handler, que es justo lo que quieres cuando un modelo genera los argumentos.

Las mismas dos herramientas, el mismo comportamiento, TypeScript idiomático. Decidamos ahora cómo deben llegar los clientes a tu servidor.

stdio vs Streamable HTTP: ¿qué transporte usar?

Los servidores MCP hablan por uno de dos transportes. stdio ejecuta el servidor como un subproceso local que el cliente lanza y con el que se comunica por entrada/salida estándar. Streamable HTTP ejecuta el servidor como un servicio de red al que los clientes se conectan por HTTP. Elige según dónde deba vivir el servidor.

La regla práctica: construye y prueba sobre stdio, cambia a Streamable HTTP solo cuando más de una persona o máquina necesite el servidor. La mayoría de los servidores nunca necesitan salir de stdio. Las llamadas mcp.run() y StdioServerTransport() de arriba ya son stdio, así que estás listo para el desarrollo.

Cómo probar tu servidor MCP con el Inspector

Antes de integrar tu servidor en Claude, pruébalo de forma aislada con el MCP Inspector. Es una interfaz de navegador que se conecta a tu servidor, lista sus herramientas y te deja llamarlas a mano. Ejecútalo contra tu servidor:

# Python
npx @modelcontextprotocol/inspector uv run server.py
# TypeScript
npx @modelcontextprotocol/inspector npx tsx server.ts

El Inspector abre una página local donde ves tus herramientas add y fetch_url, lanzas una llamada de prueba y lees la respuesta en bruto. Este es el mejor hábito para el desarrollo MCP. Si el esquema de una herramienta está mal formado o un valor de retorno es incorrecto, lo ves aquí en segundos en lugar de mirar un fallo silencioso dentro de Claude. Así detectamos un esquema de entrada erróneo que de otro modo nos habría costado una ronda completa de depuración por el cliente. Prueba primero en el Inspector, siempre.

Cómo conectar tu servidor MCP a Claude Desktop, Claude Code y Cursor

Una vez que el Inspector esté contento, apunta un cliente real a tu servidor. Cada cliente lee un archivo de configuración que le indica cómo lanzar tu servidor sobre stdio.

Claude Desktop. Edita claude_desktop_config.json (en macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "demo-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-demo", "run", "server.py"]
    }
  }
}

Reinicia Claude Desktop y tus herramientas aparecen bajo el icono de conectores.

Claude Code. Añade el servidor con un comando desde tu proyecto: claude mcp add demo-server -- uv run server.py. Claude Code lo guarda en la configuración del proyecto y lo carga al arrancar. Si además usas hooks para programar Claude Code, nuestra guía de hooks de Claude Code combina bien con herramientas MCP propias.

Cursor. Añade el mismo bloque mcpServers a .cursor/mcp.json en la raíz del proyecto. La forma coincide con la de Claude Desktop. Para un ejemplo real de un servidor MCP corriendo dentro de Claude Code, mira cómo conectamos Higgsfield en Claude Code.

Usa rutas absolutas en cada configuración. Las rutas relativas son la razón más común de que un servidor no arranque.

Desplegar un servidor MCP en producción (auth y hosting)

Cuando tu servidor deba compartirse, pásalo de stdio a Streamable HTTP y añade tres cosas: autenticación, manejo de errores y un host.

• Autenticación. Los servidores MCP remotos deben usar OAuth 2.1 según la especificación de autorización de MCP. Para herramientas internas, una comprobación de token bearer en el endpoint HTTP es el mínimo pragmático. Nunca publiques un servidor de herramientas público y sin autenticar, porque una herramienta que ejecuta SQL o golpea API internas es una superficie de ataque activa.
• Manejo de errores. Envuelve los cuerpos de las herramientas con try/except (o try/catch) y devuelve un mensaje de error tipado en vez de lanzar. El modelo gestiona "la consulta falló, aquí está el motivo" mucho mejor que una conexión cortada.
• Hosting. Cualquier plataforma que ejecute un proceso Node o Python de larga vida sirve: un VPS pequeño, Fly.io, Railway o un contenedor en tu propia infraestructura. Mantén el proceso caliente, porque los arranques en frío añaden latencia a la primera llamada de herramienta.
• Concurrencia y coste. Si tus herramientas llaman a un LLM o a una API de pago aguas abajo, pon un gateway delante. Nuestro repaso de herramientas de gateway LLM cubre el rate-limiting y el fallback, y las herramientas de context engineering ayudan a evitar que la salida de herramientas sature la ventana de contexto del modelo.

Para Python, cambia la llamada run a mcp.run(transport="streamable-http"); para TypeScript, sustituye StdioServerTransport por el StreamableHTTPServerTransport del SDK. Las definiciones de herramientas no cambian en absoluto. Ese es el sentido de la abstracción de transporte.

Lo que aprendimos al desplegar servidores MCP en producción

En Techsy hemos construido servidores MCP para uso interno, y algunas lecciones solo aparecen cuando el tráfico real las golpea. Esto es lo que medimos y dónde nos pillaron.

El primer servidor que desplegamos fue una herramienta de consulta de Postgres de solo lectura, construida con FastMCP 2.x sobre el SDK de Python mcp 1.x, luego reescrita en @modelcontextprotocol/sdk 1.x para comparar. En un stack de 2026 (Node 20, Python 3.11), las llamadas de herramienta locales por stdio añadían unos 8 a 12 ms de sobrecarga de transporte por llamada. Al mover ese mismo servidor a Streamable HTTP en un VPS, el coste por llamada subió a 40 a 70 ms, casi todo ida y vuelta de red en lugar de coste de protocolo. El arranque en frío de FastMCP fue de unos 300 ms para el proceso, por eso mantenemos el proceso de producción caliente.

La trampa que nos costó unas dos horas: una herramienta que devolvía un dict de Python en bruto se renderizaba bien en el Inspector pero volvía truncada dentro de Claude Desktop. Envolver el valor de retorno como una cadena de texto tipada lo arregló al instante. Por eso este tutorial devuelve cadenas y bloques de texto content en todas partes en lugar de objetos anidados. El otro hábito que rindió de inmediato fue pasar cada servidor por npx @modelcontextprotocol/inspector antes de tocar una configuración de cliente, lo que sacó a la luz un esquema de entrada mal formado en la reescritura de TypeScript que de otro modo habría fallado en silencio en Cursor.

Si estás eligiendo qué herramientas integrar en servidores para empezar, nuestra lista de los mejores servidores MCP en 2026 es un buen banco de ideas.

Cómo aborda Techsy el desarrollo de MCP

En Techsy construimos servidores MCP como parte de los sistemas de agentes de IA que entregamos a clientes, conectando agentes a bases de datos internas, CRM y API mediante una capa de herramientas tipada. Nuestro enfoque es empezar estrecho (una herramienta bien probada sobre stdio), validarla en el Inspector y luego promoverla a un servicio HTTP autenticado solo cuando más de un agente la necesita. Combinamos servidores propios con el Claude Agent SDK cuando la lógica del agente se vuelve compleja.

Esta es la versión honesta: la mayoría de los equipos sobreconstruyen su primer servidor. Rara vez necesitas HTTP, OAuth y una docena de herramientas el primer día. Si quieres un segundo par de ojos sobre una integración MCP, pide una consulta gratuita y te diremos si es un trabajo de stdio con una sola herramienta o algo que realmente necesita infraestructura.

Preguntas frecuentes

¿Debo crear mi servidor MCP en Python o en TypeScript?

Usa el lenguaje con el que tu equipo ya trabaja. Python con FastMCP es la vía más corta a un primer servidor funcional, porque un decorador convierte una función en herramienta. TypeScript con el SDK oficial es algo más verboso pero te da tipos excelentes y se despliega limpiamente en hosts de Node. Ambos producen servidores que se comportan igual para el cliente.

¿Necesito un framework como FastMCP para crear un servidor MCP?

No, pero ayuda. FastMCP viene dentro del SDK de Python mcp oficial y elimina la mayor parte del boilerplate del protocolo. Puedes usar la API Server de más bajo nivel para un control fino, pero para casi cualquier servidor FastMCP (Python) o McpServer (TypeScript) es la herramienta adecuada y mucho menos código.

¿Cómo depuro un servidor MCP que no funciona?

Pásalo primero por el MCP Inspector: npx @modelcontextprotocol/inspector seguido de tu comando de ejecución. El Inspector lista tus herramientas y te deja llamarlas directamente, así que puedes confirmar que el servidor funciona antes de culpar al cliente. Si el Inspector está bien pero el cliente no, comprueba que tu configuración usa rutas absolutas y que reiniciaste el cliente.

¿FastMCP es parte oficial de MCP?

Sí. FastMCP viene incluido con el SDK de Python oficial del Model Context Protocol como interfaz de servidor de alto nivel. El decorador @mcp.tool() que usas es la forma recomendada de crear servidores de Python, no un complemento de terceros.

¿Cuál es la diferencia entre un servidor MCP local y uno remoto?

Un servidor local corre en tu máquina sobre stdio, lanzado por el cliente como subproceso, ideal para herramientas personales y desarrollo. Un servidor remoto corre como servicio web sobre Streamable HTTP y es accesible para varios clientes, lo que requiere autenticación OAuth 2.1. Construye primero en local, pasa a remoto solo cuando compartas.

¿En qué lenguajes puedo crear un servidor MCP?

El Model Context Protocol tiene SDK oficiales para Python, TypeScript, Java, Kotlin y C#, con SDK de la comunidad en otros lenguajes. Como MCP es un protocolo de cable, cualquier lenguaje capaz de leer y escribir JSON-RPC sobre stdio o HTTP puede implementar un servidor, pero los SDK oficiales te ahorran ese trabajo.

¿Un servidor MCP funciona con ChatGPT y Gemini, o solo con Claude?

MCP es un estándar abierto adoptado en todo el ecosistema de IA agéntica, incluidos ChatGPT, Gemini, Cursor y VS Code Copilot. Un único servidor que construyes funciona con cualquier cliente compatible. No escribes una integración separada por modelo, que es todo el sentido del protocolo.

¿Cuánto se tarda en crear un servidor MCP funcional?

Un primer servidor con una o dos herramientas sobre stdio tarda unos 15 minutos una vez instalado tu entorno de ejecución. Medimos 14 minutos para un principiante en Node 20 y menos de 5 minutos para una construcción repetida. La autenticación, el transporte HTTP y el hosting de producción son lo que lleva tiempo real, no el servidor en sí.