Cómo crear un servidor MCP: herramientas, transporte y la primera llamada
Un servidor MCP es un programa que responde a tools/list con una lista de herramientas y a tools/call ejecutando una. Con el SDK de Python son doce líneas. Todo lo que sigue se ejecutó hoy, 20 de noviembre de 2026, sobre mcp 2.3.0 contra la revisión 2026-07-28 del protocolo, con la salida en crudo.
Qué tiene que responder un servidor MCP
Tres cosas, y solo la primera es obligatoria.
Un servidor declara capacidades (tools, resources, prompts), responde a tools/list con un conjunto determinista de definiciones de herramientas, y responde a tools/call ejecutando una y devolviendo contenido. Las resources y los prompts son opcionales. Casi todos los servidores que merece la pena escribir son un saco de herramientas y nada más.
La definición de una herramienta necesita un name, una description y un inputSchema que sea un objeto JSON Schema válido. title, outputSchema y annotations son opcionales. La especificación de herramientas dice que los nombres deberían tener de 1 a 128 caracteres entre letras, dígitos, guion bajo, guion y punto, y ser únicos dentro del servidor. Para una herramienta sin argumentos, el esquema recomendado es {"type": "object", "additionalProperties": false}, nunca null.
Crear un servidor MCP con el SDK de Python de MCP
Instala el SDK y su extra de CLI:
pip install "mcp[cli]" # or: uv add "mcp[cli]"
Eso es mcp 2.3.0, publicado en PyPI el 2 de octubre de 2026. El punto de entrada es MCPServer, que sustituyó al antiguo nombre FastMCP:
from mcp.server import MCPServer
mcp = MCPServer("word-count", version="1.0.0")
@mcp.tool()
def count_words(text: str) -> int:
"""Count the words in a block of text."""
return len(text.split())
if __name__ == "__main__":
mcp.run()
Pasan tres cosas sin que las escribas. La docstring se convierte en la description de la herramienta, lo único que lee el modelo para decidir si la llama, así que escríbela para el modelo y no para tus compañeros. Las anotaciones de tipo se convierten en el inputSchema. Y la anotación de retorno se convierte en un outputSchema, de modo que el resultado llega en JSON estructurado, no solo en texto.
Pruébalo antes de conectar ningún cliente:
mcp dev server.py
Eso abre el MCP Inspector, que lista las herramientas y te deja llamarlas a mano. Es la forma más rápida de descubrir que un nombre de argumento que creías evidente no lo es.
stdio o Streamable HTTP
mcp.run() usa stdio por defecto. La revisión 2026-07-28 define exactamente dos transportes estándar, y la elección va de quién lanza el proceso, no de funcionalidades: la semántica del protocolo es idéntica en todos los transportes.
| stdio | Streamable HTTP | |
|---|---|---|
| Quién lo lanza | el cliente, como subproceso | tú, como servicio |
| Encuadre de mensajes | JSON-RPC delimitado por saltos de línea en stdin y stdout | un POST HTTP por mensaje |
| Llega a otras personas | no | sí |
| Autenticación | hereda el proceso local | OAuth o una clave de API |
| Cancelación | notifications/cancelled |
el cliente cierra el flujo |
| Ideal para | una herramienta en tu propia máquina | cualquier cosa que usen otras personas |
Una regla que todo el mundo rompe el primer día: en stdio, stdout es del protocolo. Un print() perdido corrompe el flujo. Manda los logs a stderr.
Cambia de transporte con un solo argumento:
mcp.run(transport="streamable-http")
INFO StreamableHTTP session manager started
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
El endpoint es /mcp, así que http://127.0.0.1:8000/mcp.
La primera llamada del cliente, de verdad
Apunta el cliente del propio SDK al servidor stdio:
import asyncio, sys
from mcp import Client, StdioServerParameters
async def main():
params = StdioServerParameters(command=sys.executable, args=["server.py"])
async with Client(params) as client:
print("protocol:", client.protocol_version)
tools = await client.list_tools()
for t in tools.tools:
print("tool:", t.name, "|", t.description)
res = await client.call_tool("count_words", {"text": "one two three four"})
print("content:", res.content)
print("structured:", res.structured_content)
asyncio.run(main())
Lo que imprimió:
protocol: 2026-07-28
tool: count_words | Count the words in a block of text.
content: [TextContent(type='text', text='4', annotations=None, meta=None)]
structured: {'result': 4}
Fíjate en las dos grafías. El formato del cable va en camelCase (inputSchema, structuredContent, isError); los objetos de Python van en snake_case (input_schema, structured_content, is_error). Leer t.inputSchema lanza un AttributeError, y ahí perdí mis cinco primeros minutos.
Por HTTP, curl necesita cuatro cabeceras, y fallarlas es toda la sesión de depuración:
curl -s -X POST http://127.0.0.1:8000/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2026-07-28' \
-H 'mcp-method: tools/list' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{
"io.modelcontextprotocol/protocolVersion":"2026-07-28",
"io.modelcontextprotocol/clientCapabilities":{}}}}'
{"jsonrpc":"2.0","id":1,"result":{"cacheScope":"private","resultType":"complete",
"tools":[{"description":"Count the words in a block of text.",
"inputSchema":{"type":"object","properties":{"text":{"title":"Text","type":"string"}},
"required":["text"],"title":"count_wordsArguments"},"name":"count_words",
"outputSchema":{"properties":{"result":{"title":"Result","type":"integer"}},
"required":["result"],"type":"object"}}],"ttlMs":0}}
Dos errores con los que vas a chocar en ese orden. Quita _meta y te sale -32602: params._meta must be an object carrying the required 'io.modelcontextprotocol/protocolVersion' and 'io.modelcontextprotocol/clientCapabilities' envelope keys. Deja _meta pero olvida la cabecera y te sale -32020: mcp-method header does not match the request body's method. Un tools/call necesita una tercera, mcp-name, que lleva el nombre de la herramienta, o vuelve el mismo -32020.
Con todas, la llamada devuelve las dos formas:
{"id":2,"result":{"content":[{"text":"4","type":"text"}],"isError":false,
"resultType":"complete","structuredContent":{"result":4}}}
Qué cambió la revisión 2026-07-28
Si vas siguiendo un tutorial escrito para 2025-06-18 o 2025-11-25, tres cosas han cambiado de sitio.
Ya no hay apretón de manos initialize. Cada petición declara su propia versión de protocolo y las capacidades del cliente en params._meta, y el servidor acepta o rechaza cada petición de forma independiente. Streamable HTTP copia esos valores en cabeceras para que un proxy pueda enrutar sin leer el cuerpo, y el cuerpo sigue siendo la fuente de verdad.
El descubrimiento es una sola llamada opcional. server/discover devuelve de golpe las versiones soportadas, las capacidades y la identidad:
{"id":3,"result":{"capabilities":{"prompts":{"listChanged":true},
"resources":{"listChanged":true,"subscribe":true},"tools":{"listChanged":true}},
"supportedVersions":["2026-07-28"]}}
Y ya no hay sesión de protocolo. Un servidor no puede guardar estado por conexión, así que todo lo que abarque varias llamadas tiene que ser un identificador explícito que devuelves desde una herramienta y aceptas como argumento en la siguiente. Manda una petición a la antigua a este servidor y cae al camino con sesión, que responde Bad Request: Missing session ID. Esa es la compatibilidad hacia atrás funcionando, no un bug. Lo que implica para el despliegue está en el hosting de un servidor MCP.
El camino de error que le enseña al modelo
La especificación parte los errores en dos. Una petición mal formada o un método desconocido es un error JSON-RPC. Un fallo que el modelo podría arreglar reintentando de otra forma es un resultado de herramienta con isError: true, porque los clientes se los devuelven al modelo y este puede corregirse solo.
El SDK lo hace casi bien por su cuenta. Una herramienta desconocida devuelve un resultado, no un error de protocolo:
{"id":4,"result":{"content":[{"text":"Unknown tool: nope","type":"text"}],"isError":true}}
Pero lanza una excepción dentro de una herramienta y el mensaje se traga:
raise ValueError("text is empty, pass at least one word")
is_error: True
content: Error executing tool count_words
El modelo ya sabe que la llamada falló y nada sobre el porqué, así que reintenta con los mismos argumentos. Si quieres que el modelo se corrija, devuelve la explicación en el texto de la propia herramienta en vez de lanzar una excepción. Ese único hábito vale más que todo el trabajo de esquemas.
Antes de dejar que un agente se acerque
Un servidor que funciona en tu portátil no es un servidor que le entregas a otra persona. Faltan dos piezas, y cada una tiene su página aquí: la autenticación, tratada en OAuth para un servidor MCP, y la decisión de hosting. La especificación es clara con el resto: valida cada entrada, limita la tasa de invocaciones, y no marques nunca un secreto con x-mcp-header, porque el valor de una cabecera es visible para todos los intermediarios del camino.
También merece la pena preguntarte si deberías escribir el servidor. Para algo como publicar en redes, lo difícil no es MCP, son ocho API de plataformas, ocho flujos de OAuth y el refresco de tokens: por eso PlugKit mantiene un servidor MCP alojado en https://api.plugkit.co/mcp en lugar de repartir una plantilla, a 49 $ al mes por 5 cuentas conectadas, cancelas cuando quieras, o 97 $ al mes por 30, tras siete días gratis con una tarjeta al registrarte y nada cobrado antes del día 7. Verificado el 20 de noviembre de 2026. Escribe el tuyo cuando las herramientas son tuyas: tu base de datos, tu API interna, tu sistema de build. MCP o API REST para tu agente es la decisión un nivel por encima, y el servidor MCP de Instagram es a lo que se parece el resultado final desde el cliente.
Preguntas frecuentes
¿En qué lenguaje debería escribir un servidor MCP?
En el que ya vivan tus herramientas. La lista oficial de SDK tiene diez: TypeScript, Python, C#, Go, Rust y Ruby en el tier 1, Java en el tier 2, Swift, PHP y Kotlin en el tier 3, donde el tier dice lo completo y lo mantenido que está. Todos hablan el mismo JSON-RPC. El servidor es una capa fina sobre código que ya tienes, así que reescribir ese código en otro lenguaje es el error caro.
¿Necesito Streamable HTTP o me basta stdio?
stdio basta cuando el único usuario eres tú en esta máquina: el cliente lanza tu script como subproceso y no se expone nada. En cuanto lo necesita una segunda persona o un agente alojado, necesitas Streamable HTTP, una URL y autenticación.
¿Cómo pruebo un servidor MCP sin cliente?
mcp dev server.py abre el MCP Inspector, que lista tus herramientas y las llama con los argumentos que escribes. Después, curl contra el endpoint HTTP muestra el JSON exacto que manda un cliente real, y así cazas un esquema que el modelo va a leer mal.
¿Por qué mi herramienta funciona en el Inspector pero no en el agente?
Normalmente la descripción. El modelo elige herramientas leyendo description y los títulos de los argumentos, y una docstring tipo «se encarga de la cosa» no le da nada a lo que agarrarse. Reescribe la docstring como una instrucción, di qué devuelve la herramienta y nombra los argumentos como los adivinaría quien llama.
¿Cuántas herramientas debería exponer un servidor MCP?
Menos de las que te apetece. Cada definición ocupa el contexto del modelo en cada turno, así que cien herramientas cuestan tokens reales y confusión real entre casi duplicados. Agrupa por tarea, devuelve contenido estructurado para que una herramienta responda a varias preguntas, y separa en varios servidores antes de partir un servidor en cien nombres.
Un solo plug para cada plataforma que toca tu agente
49 $ al mes por 5 cuentas conectadas, cancela cuando quieras. Todas las funciones en todos los planes.
Consigue tu clave de API →