Cómo crear tu primer servidor MCP en Python (y probarlo sin una app de IA)

Escribe un pequeño servidor MCP en Python con dos herramientas, pruébalo sin ninguna app de IA, inspecciónalo con MCP Inspector y conéctalo a tu editor o asistente.

Graphic of a small server box connected to a chat bubble and a code editor, for a guide to building an MCP server in Python

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.

Video: The Model Context Protocol (MCP) (Anthropic)

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:

Terminal
curl -LsSf https://astral.sh/uv/install.sh | sh

En Windows, desde PowerShell:

Código
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

Terminal
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:

Terminal
uv run mcp version

Salida esperada:

Código
MCP version 2.3.0

Paso 2: Escribe el servidor

Crea un archivo llamado server.py en la carpeta del proyecto:

Código
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 desde mcp.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.
  • ToolError devuelve 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.
Diagrama con las partes de un archivo mínimo de servidor MCP en Python y lo que hace cada una

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:

Código
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:

Terminal
uv run check.py

Salida esperada:

Código
['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:

Terminal
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:

Terminal
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:

Código
{
  "content": [
    {
      "type": "text",
      "text": "47"
    }
  ],
  "structuredContent": {
    "result": 47
  },
  "isError": false
}

El SDK también puede abrir la interfaz web del Inspector:

Terminal
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:

Terminal
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:

Código
{
  "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.json en un proyecto, o como ~/.cursor/mcp.json para 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:

Código
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.

Diagrama de flujo para crear, probar, inspeccionar y conectar un servidor MCP en Python a una app de IA

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 es MCPServer y se importa con from mcp.server import MCPServer. Actualiza el import o fija mcp<2 para seguir ejecutando código antiguo.
  • TypeError: The @tool decorator was used incorrectly: escribiste @mcp.tool sin 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, sustituye uv por la ruta completa que devuelve which uv (macOS y Linux) o where 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ódulo logging de Python, que escribe en stderr.
  • npm warn deprecated @modelcontextprotocol/inspector@0.15.0: v1 is deprecated, o una llamada a herramienta falla con Field required: tu Node.js es demasiado antiguo para Inspector 2.x. En una prueba con Node 20, npx instaló sin avisar la versión antigua 0.15.0, que ignora --tool-args-json. Revisa node --version y actualiza a una versión compatible.
  • npx not found al ejecutar mcp 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.

Escrito por Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

Acerca de Mindloop Experience

Respuestas

Escribe una respuesta

Más de Mindloop Experience

Ver todo de Mindloop Experience

Puedes aplaudir hasta 50 veces.