PoC 1 — MCP Echo Server (Tools básicas sobre stdio)

Primera PoC de una serie de 5 para aprender MCP (Model Context Protocol) en profundidad. Server MCP en Python que expone 3 tools simples sobre transporte stdio, pensado para validar el handshake completo initialize → negociación de capabilities → tools/list → tools/call contra Claude Desktop / Claude Code.

Spec completa de la PoC: POC1_MCP_ECHO_SERVER.md.

Tools expuestas

Tool	Input	Output	Propósito didáctico
echo	message: str	el mismo string	Validar ida y vuelta trivial
add	a: float, b: float	la suma	Validar tipado de inputs y coerción
reverse	text: str	el string invertido	Validar manejo de strings no triviales

Implementadas como funciones síncronas y puras (sin efectos secundarios) usando la API moderna FastMCP del SDK mcp (decorador @mcp.tool()).

Instalar dependencias

Con uv (preferido):

uv sync

Con venv + pip:

python -m venv .venv
.venv\Scripts\activate      # Windows
pip install -e .

Registrar el server en Claude Desktop

Editar claude_desktop_config.json (en Windows: %APPDATA%\Claude\claude_desktop_config.json) y agregar:

{
  "mcpServers": {
    "poc1-echo-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\PoC\\MCP\\MPC-PoC-1-EchoServerToolsbasicas",
        "python",
        "server.py"
      ]
    }
  }
}

Si preferís usar el intérprete de un venv en vez de uv, reemplazá command/args por la ruta absoluta al python.exe del venv y ["C:\\PoC\\MCP\\MPC-PoC-1-EchoServerToolsbasicas\\server.py"].

Reiniciar Claude Desktop para que detecte el nuevo server.

Probar cada tool

Frases de ejemplo para gatillar cada tool desde el chat de Claude Desktop:

• echo: "Usá la tool echo para repetir el mensaje 'hola mundo'"
• add: "Sumá 15.5 y 22.3 usando la tool add"
• reverse: "Invertí el string 'MCP' con la tool reverse"

También podés correr el server directo para validar que arranca sin errores:

python server.py

Va a quedar esperando input JSON-RPC por stdin (comportamiento normal); Ctrl+C para salir.

Ver los logs de stderr (debug del handshake)

Todo el logging va a stderr (nunca a stdout, que es el canal del protocolo). Claude Desktop guarda los logs de cada MCP server en:

%APPDATA%\Claude\logs\mcp-server-poc1-echo-server.log

Ahí se ve el initialize, la negociación de capabilities y cada tools/call con sus argumentos, gracias al logging agregado en server.py.

Qué aprendí

• El SDK mcp moderno resuelve casi todo con FastMCP + @mcp.tool(): el schema de inputs se genera solo a partir de los type hints, sin tocar JSON Schema a mano.
• El canal stdout está reservado 100% para JSON-RPC — cualquier print() o log mal dirigido rompe el protocolo; todo el logging tiene que ir a stderr explícitamente.
• El handshake (initialize → tools/list → tools/call) es visible y depurable en los logs de Claude Desktop, lo cual hace mucho más fácil diagnosticar problemas de conexión que "adivinar" desde el lado del cliente.
• Correr el server standalone (python server.py) antes de registrarlo en Claude Desktop ahorra un ciclo completo de debugging: si arranca limpio ahí, el problema de conexión está en la config, no en el código.

Siguiente en la serie

PoC 2 — Resource Provider: exponer Google Sheets como Resources leíbles vía MCP.

<img width="491" height="721" alt="image" src="https://github.com/user-attachments/assets/0a2cdb2b-a7cb-4fcc-932a-687624b7f536" />