Crea tu primer MCP Server funcional: una tool simple que devuelve "¡Hola, mundo!" y conéctalo a Claude Desktop.
En este módulo, vamos a crear el MCP Server más simple posible: una única tool que recibe un nombre y devuelve un saludo. El objetivo no es impresionar por su complejidad, sino entender cada línea de código y el flujo completo, desde el código Python hasta que Claude usa la tool. Si entiendes completamente el Hello World, construir servers complejos será solo cuestión de agregar más tools.
O Hello World MCP es un servidor con una única herramienta: hello(nome: str) que devuelve f"Olá, {nome}!". Es el equivalente al "Hello World" de cualquier lenguaje de programación: el programa funcional más pequeño posible. La diferencia es que, en lugar de imprimir en la terminal, esta función será llamada por una IA a través del protocolo MCP. El modelo decide cuándo llamar, pasa los parámetros y recibe el resultado.
Resiste la tentación de agregar features adicionales a Hello World. El objetivo aquí es claridad total, funcionalidad. Cuando entiendas cada línea de este server mínimo, podrás construir cualquier cosa. Piensa en esto como aprender a caminar antes de correr: una base sólida ahora te ahorrará horas de depuración después.
Vamos a usar el uv para crear y configurar el proyecto. uv se encarga de todo: inicializa el proyecto con pyproject.toml, crea el entorno virtual e instala las dependencias. En tres comandos, tendrás un proyecto Python listo para recibir el código del server.
La creación del proyecto usa tres comandos: uv init hello-mcp — crea el directorio con pyproject.toml; cd hello-mcp — entra en el directorio; y uv add fastmcp — agrega FastMCP como dependencia. Después, crea el archivo server.py donde estará el código del server. En menos de 30 segundos, tendrás un proyecto de Python completo y configurado.
Ejecuta uv init hello-mcp — crea el directorio del proyecto con pyproject.toml, .python-version y una estructura inicial.
Entra al directorio con cd hello-mcp — todos los comandos siguientes deben ejecutarse desde el proyecto.
Ejecuta uv add fastmcp — instala FastMCP y todas sus dependencias en el entorno virtual del proyecto.
Crea el archivo server.py en el directorio raíz del proyecto; aquí es donde escribiremos el código del MCP Server.
Si ya tienes el uv instalado, puede hacerlo todo en una línea: uv init hello-mcp && cd hello-mcp && uv add fastmcp. uv es extremadamente rápido: la instalación de FastMCP y todas sus dependencias tarda solo unos segundos, mucho menos que con el pip tradicional.
Ahora viene la parte más satisfactoria: escribir el código del server. Son solo 10 líneas, pero cada una tiene un propósito preciso. No copies y pegues sin entender; lee cada línea y comprende qué hace. Este es el código que convierte una función común de Python en una capacidad a la que puede acceder cualquier IA compatible con MCP.
El código completo del Hello World MCP Server:
Estas ~10 líneas conforman un MCP Server completo y funcional. FastMCP se encarga de todo el protocolo por debajo: JSON-RPC, transporte, negociación de capabilities y serialización. Tú solo tienes que preocuparte por la lógica de tu tool.
Sin FastMCP, implementar el mismo server usando el protocolo MCP de bajo nivel exigiría más de 150 líneas de código — incluido el análisis de JSON-RPC, la gestión del transporte stdio, la negociación de capabilities, la serialización de schemas y el manejo de errores del protocolo. FastMCP lo reduce a ~10 líneas, una reducción de más del 90% en el código necesario. Esa es la ventaja de usar un framework bien diseñado.
Con el código listo, es hora de conectar el server a Claude Desktop. Esto se hace editando el archivo de configuración de Claude y agregando una entrada para tu server. Claude Desktop usará el uv para iniciar el server automáticamente cuando sea necesario.
Agrega al archivo claude_desktop_config.json de Claude Desktop:
Reemplaza /caminho/completo/hello-mcp por la ruta absoluta real de tu proyecto. Después, reinicia Claude Desktop para que detecte el nuevo server.
La ruta en el --directory debe ser absoluto — las rutas relativas no funcionan. Usa la ruta completa, como /home/usuario/projetos/hello-mcp en Linux/Mac o C:\\Users\\usuario\\projetos\\hello-mcp en Windows. Una ruta incorrecta es la causa número 1 de que «el server no aparezca en Claude»: ¡revísala con cuidado!
Con el server configurado y Claude Desktop reiniciado, llega el momento mágico: probar si todo funciona. Abre una nueva conversación en Claude y pídele que use la tool. Si todo está correcto, Claude identificará la tool automáticamente, la llamará con los parámetros adecuados y mostrará el resultado. Así funciona MCP de principio a fin.
Para probar, abre Claude Desktop y escribe algo como "Saluda a María". Claude debe: (1) reconocer que tiene una tool hello disponible; (2) decidir usarla para atender la solicitud; (3) llamar a la herramienta con nome="Maria"; (4) recibir el resultado "Olá, Maria!"; e (5) presentar el resultado en la conversación. Si eso ocurre, ¡felicidades! Tu primer MCP Server está funcionando.
Si la tool no aparece en Claude Desktop, revisa: (1) la ruta en config.json es correcta y absoluta; (2) uv está instalado y accesible; (3) Claude Desktop se reinició; (4) el archivo server.py no tiene errores de sintaxis. Puedes probar el server manualmente con uv run server.py en la terminal: si aparece un error, el problema está en el código.
Abre Claude Desktop e inicia una conversación nueva.
Comprueba si aparece el ícono de herramientas (martillo): indica que hay MCP Servers conectados.
Escribe «Di hola a María» y envía el mensaje.
Claude te pedirá permiso para usar la tool "hello"; haz clic en "Allow" para autorizarla.
Comprueba que el resultado muestre "¡Hola, Maria!" — ¡tu MCP Server está funcionando!
Ahora que el server funciona, volvamos al código y analicemos cada línea en detalle. Entender el «porqué» de cada elemento es lo que marca la diferencia entre copiar código y comprenderlo. Cada línea del Hello World cumple una función precisa en el funcionamiento del MCP Server, y ninguna es superflua.
from fastmcp import FastMCP — incorpora el framework al código. Sin esto, Python no sabe qué es FastMCP.
mcp = FastMCP("hello-mcp") — crea el objeto server. El nombre identifica el server en el client.
@mcp.tool() — registra la función como una tool MCP. Sin el decorator, es solo una función normal de Python.
def hello(nome: str) -> str — la lógica de la tool. El nombre de la función se convierte en el nombre de la tool.
nome: str e -> str — definen el schema de la tool. El modelo sabe que debe enviar una cadena y recibirá una cadena.
"""Diz olá para a pessoa informada.""" — se convierte en la descripción de la tool que el modelo lee para decidir cuándo usarla.
Cada elemento del código tiene una correspondencia directa en el protocolo MCP: el nombre de la función se convierte en el campo name de la tool; los type hints se convierten en el inputSchema (JSON Schema); la docstring se convierte en el campo description; e o retorno se convierte en el content de la respuesta. FastMCP hace esta traducción automáticamente: escribes Python idiomático y el framework genera el protocolo MCP correcto.
Prueba cambiar algunas cosas y observa qué pasa: cambia la docstring y observa cómo Claude describe la tool; agrega un segundo parámetro y observa cómo Claude te pide la información adicional; cambia el nombre de la función y observa cómo aparece el nuevo nombre en Claude. Esta experimentación activa es la mejor forma de entender cómo se conecta cada parte del código con el comportamiento del MCP Server.
hello que devuelve un saludo personalizado.
uv init e uv add fastmcp — configuración completa en segundos.
claude_desktop_config.json con ruta absoluta obligatoria.
Siguiente Módulo: 3.3 — Entendiendo los decoradores y los esquemas