La mayoría de las guías sobre Model Context Protocol (MCP) te enseñan a instalar un servidor que escribió otra persona. Esta te enseña a crear tu propio servidor MCP en Python: un servidor pequeño con dos herramientas que cualquier app de IA compatible con MCP puede llamar. Lo vas a construir, lo probarás sin ninguna app de IA, lo inspeccionarás con el MCP Inspector oficial y después lo conectarás a un editor o asistente.
Puntos clave
- El SDK oficial de MCP para Python 2.x renombró la clase del servidor a MCPServer, así que muchos tutoriales antiguos ya no funcionan tal como están escritos.
- Decorar una función con @mcp.tool() la convierte en una herramienta; su nombre, descripción y esquema de entrada salen de tu código.
- Prueba el servidor en memoria con la clase Client del SDK y luego por stdio con el MCP Inspector oficial.
- Conéctalo a Cursor, VS Code o Claude Desktop dándole a la app un comando de arranque con uv y una ruta absoluta.
A fecha de 15 de noviembre de 2026, el SDK oficial de Python va por la versión 2.3.0 (publicada el 2 de octubre de 2026) y MCP Inspector por la 2.15.0 (publicada el 12 de noviembre de 2026). El SDK 2.x renombró la clase principal del servidor, así que muchos tutoriales antiguos ya no funcionan tal como están escritos. Los comandos del proyecto, de las pruebas y del Inspector que verás a continuación se ejecutaron con esas versiones.
Qué es un servidor MCP
MCP es un estándar de código abierto para conectar aplicaciones de IA con sistemas externos. Para seguir esta guía basta con tres términos de la documentación del SDK:
- Un host es la app de IA con la que hablas, como un asistente de chat o un editor de código.
- Un cliente vive dentro del host y habla MCP.
- Un servidor es lo que tú construyes. Puede ofrecer herramientas (funciones que llama el modelo), recursos (datos que carga la app) y prompts (plantillas que elige el usuario).
Esta guía se centra en las herramientas. Las dos que vas a escribir, un contador de palabras y una calculadora de fechas, hacen un trabajo exacto que resuelve mejor el código que la estimación de un modelo.
Lo que necesitas
- uv, el gestor de proyectos de Python que usa el tutorial oficial de MCP. Si no tienes una versión adecuada de Python, la descarga por ti. El SDK necesita Python 3.10 o posterior.
- Node.js, solo para el Inspector del paso 4. Inspector 2.15.0 requiere Node
^22.23.4 || ^24.22.1 || >=26.12.1. - Una app compatible con MCP para el paso 5 (opcional).
Instala uv en macOS o Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
En Windows, desde PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Después reinicia la terminal para que encuentre el comando uv.
En cifras
2.3.0versión del SDK de Python usada
2.15.0versión de MCP Inspector usada
3.10versión mínima de Python
Paso 1: Crea el proyecto
uv init --bare handy-tools
cd handy-tools
uv add "mcp[cli]"
--bare crea solo un pyproject.toml, que es todo lo que necesita este proyecto. El extra cli añade la herramienta de línea de comandos mcp. Comprueba la instalación:
uv run mcp version
Salida esperada:
MCP version 2.3.0
Paso 2: Escribe el servidor
Crea un archivo llamado server.py en la carpeta del proyecto:
from datetime import date
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
mcp = MCPServer("Handy Tools")
@mcp.tool()
def count_words(text: str) -> int:
"""Count the words in a piece of text."""
return len(text.split())
@mcp.tool()
def days_between(start: str, end: str) -> int:
"""Count the days from one date to another. Dates use YYYY-MM-DD format."""
try:
first = date.fromisoformat(start)
second = date.fromisoformat(end)
except ValueError:
raise ToolError("Dates must look like 2026-11-15 (YYYY-MM-DD).")
return (second - first).days
if __name__ == "__main__":
mcp.run()
Qué hace cada parte:
MCPServer("Handy Tools")crea el servidor. En el SDK 2.x se importa desdemcp.server.@mcp.tool()convierte una función en una herramienta. El SDK toma el nombre de la herramienta del nombre de la función, su descripción del docstring y su esquema de entrada de las anotaciones de tipo. No escribes nada de JSON.ToolErrordevuelve al modelo un mensaje legible para que pueda corregir sus argumentos y volver a intentarlo.mcp.run()sin argumentos arranca el servidor por stdio: el host lanza tu archivo como subproceso y se comunica con él a través de stdin y stdout.

Paso 3: Pruébalo desde Python
El SDK incluye una clase Client que puede conectarse a tu objeto servidor en memoria, sin subproceso, sin puerto y sin IA. Crea check.py junto a server.py:
import asyncio
from mcp import Client
from server import mcp
async def main() -> None:
async with Client(mcp) as client:
tools = await client.list_tools()
print([tool.name for tool in tools.tools])
result = await client.call_tool("count_words", {"text": "the quick brown fox"})
print(result.structured_content)
result = await client.call_tool("days_between", {"start": "2026-11-15", "end": "2027-01-01"})
print(result.structured_content)
result = await client.call_tool("days_between", {"start": "tomorrow", "end": "2027-01-01"})
print(result.is_error, result.content[0].text)
asyncio.run(main())
Ejecútalo:
uv run check.py
Salida esperada:
['count_words', 'days_between']
{'result': 4}
{'result': 47}
True Error executing tool days_between: Dates must look like 2026-11-15 (YYYY-MM-DD).
También verás una línea de log INFO sobre la llamada fallida: es el servidor registrando el ToolError. Fíjate en que la fecha incorrecta no lanzó una excepción en el cliente: una llamada a herramienta que falla vuelve como un resultado normal con is_error en True.
¿Sabías que…?
Una llamada a herramienta que falla no lanza una excepción en el cliente. Vuelve como un resultado normal con is_error en True y lleva el mensaje del ToolError.
Paso 4: Inspecciónalo con MCP Inspector
MCP Inspector es la herramienta de pruebas del propio proyecto MCP. Su modo CLI lanza tu servidor igual que lo haría un host real e imprime lo que recibe. Desde la carpeta del proyecto:
npx @modelcontextprotocol/inspector --cli uv run server.py --method tools/list
La primera vez te pedirá permiso para descargar el paquete. Después deberías ver un JSON que enumera count_words y days_between, cada una con el esquema de entrada que el SDK generó a partir de tus anotaciones de tipo.
Ahora llama a una herramienta:
npx @modelcontextprotocol/inspector --cli uv run server.py \
--method tools/call --tool-name days_between \
--tool-args-json '{"start":"2026-11-15","end":"2027-01-01"}'
Salida esperada:
{
"content": [
{
"type": "text",
"text": "47"
}
],
"structuredContent": {
"result": 47
},
"isError": false
}
El SDK también puede abrir la interfaz web del Inspector:
uv run mcp dev server.py
Imprime una dirección local como http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=... y la abre en tu navegador. En la pantalla Servers, activa el interruptor de conexión junto a tu servidor, abre Tools (herramientas), elige count_words, escribe un texto y haz clic en Execute Tool (ejecutar herramienta). Cuando termines, pulsa Ctrl+C en la terminal.
Paso 5: Conéctalo a una app de IA
Conectarlo a un host significa decirle qué comando arranca tu servidor. En este proyecto, ese comando es:
uv --directory /ABSOLUTE/PATH/TO/handy-tools run server.py
Ejecuta pwd dentro de la carpeta del proyecto para obtener la ruta real. Prueba primero el comando tú mismo. No imprime nada y no termina, y eso es lo correcto: el servidor está esperando a que un host le hable. Pulsa Ctrl+C para detenerlo.
Muchas apps aceptan el mismo bloque JSON para ese comando:
{
"mcpServers": {
"handy-tools": {
"command": "uv",
"args": ["--directory", "/ABSOLUTE/PATH/TO/handy-tools", "run", "server.py"]
}
}
}
Dónde va depende de la app:
- Cursor: guárdalo como
.cursor/mcp.jsonen un proyecto, o como~/.cursor/mcp.jsonpara usarlo en todas partes, según la documentación de MCP de Cursor. Esa documentación también menciona un campo"type": "stdio"para servidores locales, aunque sus propios ejemplos lo omiten. - VS Code: ejecuta MCP: Add Server desde la paleta de comandos, elige Command (stdio) e introduce el comando de arranque, según la documentación de VS Code.
- Claude Desktop: ejecuta
uv run mcp install server.py, que escribe la entrada por ti. Es el único host que el SDK configura automáticamente.
Reinicia la app y pregúntale algo como:
Use the days_between tool: how many days from 2026-11-15 to 2027-01-01?
La respuesta debería ser 47. Ten en cuenta que las herramientas se ejecutan en tu computadora con los permisos de tu cuenta, así que expón solo acciones que no te importe que un modelo active. Si quieres ver un ejemplo de un servidor más grande y ya listo, consulta nuestra guía de Chrome DevTools MCP.

Errores comunes y cómo solucionarlos
ModuleNotFoundError: No module named 'mcp.server.fastmcp': el código se escribió para el SDK 1.x. En la 2.x la clase esMCPServery se importa confrom mcp.server import MCPServer. Actualiza el import o fijamcp<2para seguir ejecutando código antiguo.TypeError: The @tool decorator was used incorrectly: escribiste@mcp.toolsin paréntesis. Usa@mcp.tool().- La app no muestra tu servidor: la causa habitual es una ruta relativa. Usa la ruta absoluta al proyecto y, si la app no encuentra
uv, sustituyeuvpor la ruta completa que devuelvewhich uv(macOS y Linux) owhere uv(Windows). Cierra la app por completo y vuelve a abrirla después de editar su configuración. - La conexión se cae o la lista de herramientas está vacía: por stdio, stdout transporta el propio protocolo. Un
print()suelto puede corromperlo. Usa el módulologgingde Python, que escribe en stderr. npm warn deprecated @modelcontextprotocol/inspector@0.15.0: v1 is deprecated, o una llamada a herramienta falla conField required: tu Node.js es demasiado antiguo para Inspector 2.x. En una prueba con Node 20,npxinstaló sin avisar la versión antigua 0.15.0, que ignora--tool-args-json. Revisanode --versiony actualiza a una versión compatible.npx not foundal ejecutarmcp dev: el Inspector es una app de Node.js. Instala Node.js primero.Error executing tool <name>sin ningún mensaje: la herramienta falló con una excepción que no tenías prevista. El traceback está en el log del servidor, no en el resultado.
¿Sabías que…?
Por stdio, stdout transporta el propio protocolo, así que un print() suelto en tu servidor puede corromper la conexión. El módulo logging de Python, en cambio, escribe en stderr.
En resumen
Un servidor MCP que funciona es un archivo de Python con unas cuantas funciones decoradas. Escribe la herramienta, compruébala en memoria con Client(mcp), confírmala por stdio con el Inspector y luego dale a cualquier host el comando de arranque. A partir de aquí puedes añadir recursos y prompts, o servir el mismo código por HTTP con mcp.run(transport="streamable-http"). Si tu agente necesita más instrucciones escritas que funciones nuevas, nuestra guía de agent skills en Claude Code cubre esa parte.
Preguntas frecuentes
¿Qué diferencia hay entre un host, un cliente y un servidor MCP?
El host es la app de IA con la que hablas, como un asistente de chat o un editor de código. El cliente vive dentro del host y habla MCP. El servidor es lo que tú construyes, y puede ofrecer herramientas, recursos y prompts.
¿Por qué me aparece No module named mcp.server.fastmcp?
Ese código se escribió para el SDK 1.x. En la 2.x la clase es MCPServer y se importa con from mcp.server import MCPServer. Actualiza el import o fija mcp<2 para seguir ejecutando código antiguo.
¿Puedo probar un servidor MCP sin una app de IA?
Sí. La clase Client del SDK se conecta a tu objeto servidor en memoria, sin subproceso, puerto ni IA. Después, el modo CLI de MCP Inspector lanza el servidor por stdio igual que lo haría un host real.
¿Qué versión de Node.js necesita MCP Inspector?
Inspector 2.15.0 requiere Node ^22.23.4, ^24.22.1 o >=26.12.1. Con un Node más antiguo, npx puede instalar sin avisar la versión antigua 0.15.0, que ignora –tool-args-json.
Quiz rápido
En el SDK 2.x, ¿qué clase crea un servidor MCP?
- FastMCP
- ToolError
- MCPServer
El SDK 2.x renombró la clase principal del servidor a MCPServer, que se importa desde mcp.server.
¿Qué puede hacer un print() suelto en un servidor MCP por stdio?
- Corromper el flujo del protocolo
- Nada, la salida se ignora
- Reiniciar el servidor
Por stdio, stdout transporta el propio protocolo, así que cualquier salida extra puede corromperlo.
¿De dónde saca el SDK el esquema de entrada de una herramienta?
- De un archivo JSON que escribes tú
- De las anotaciones de tipo de la función
- Del archivo de configuración del host
El SDK lee el esquema de entrada de las anotaciones de tipo, así que no escribes nada de JSON.
Fuentes
Enlaces revisados por última vez el 15 de noviembre de 2026.
- Build an MCP server (official tutorial)
- What is the Model Context Protocol?
- MCP Python SDK README, v2.3.0
- Python SDK: First steps
- Python SDK: Connect to a real host
- Python SDK: Testing
- Python SDK: Running your server
- Python SDK: Handling errors
- Python SDK: Troubleshooting
- mcp on PyPI
- MCP Inspector README, 2.15.0
- Inspector: smoke-testing an MCP server from the shell
- Installing uv
- uv: creating projects
- Cursor: Model Context Protocol
- VS Code: add and manage MCP servers





Escribe una respuesta