Descubre cómo FastMCP usa decorators de Python y schemas JSON para registrar tools y validar parámetros automáticamente.
Los decorators son una de las características más elegantes de Python. Al usar la sintaxis @, puedes modificar el comportamiento de una función sin cambiar su código. FastMCP aprovecha esta característica para convertir funciones comunes de Python en tools MCP, sin necesidad de archivos de configuración, registros manuales ni código boilerplate. Solo tienes que agregar el decorator y la magia ocurre.
Un decorator en Python es una función que recibe otra función como argumento y devuelve una versión modificada de esta. La sintaxis @decorator es solo un atajo para funcao = decorator(funcao). En el caso de FastMCP, el decorator @mcp.tool() hace tres cosas: (1) registra la función en la lista de tools del server; (2) extrae metadatos (nombre, parámetros, descripción) usando introspección de Python; y (3) mantiene intacta la función original — sigue funcionando normalmente como cualquier función de Python.
Piensa en un decorator como un insignia que marca la función como «disponible para la IA». Así como un producto en el estante de una tienda necesita una etiqueta de precio para venderse, una función de Python necesita el decorator @mcp.tool() para que sea visible como tool de MCP. Sin la etiqueta, la función existe, pero nadie fuera del código sabe que está ahí. Con la etiqueta, aparece en el catálogo de tools que el modelo puede usar.
El decorator @mcp.tool() es el componente más importante de FastMCP. Hace el trabajo pesado de conectar tu código de Python al protocolo MCP y extrae automáticamente todo lo que el cliente necesita saber sobre la tool: nombre, descripción y schema de parámetros. Veamos exactamente qué extrae y cómo.
El decorator @mcp.tool() extrae automáticamente tres datos esenciales de la función: Nombre — obtenido directamente del nombre de la función de Python (ej.: def buscar_clima se convierte en la tool buscar_clima); Descripción — extraída del docstring de la función, que el modelo lee para entender cuándo y cómo usar la tool; y Parámetros — extraídos de los type hints, convertidos automáticamente en JSON Schema para la validación. Todo esto ocurre sin ninguna configuración manual.
El enfoque de "convención sobre configuración" de FastMCP está inspirado en frameworks como Ruby on Rails y FastAPI. Los estudios sobre productividad de desarrolladores muestran que eliminar código boilerplate puede aumentar la velocidad de desarrollo hasta en un 40%. En el caso de FastMCP, la misma tool que requeriría ~30 líneas de configuración manual (nombre, schema JSON, handler) se define en apenas 3-5 líneas de Python idiomático con el decorator.
Los type hints de Python son la base del sistema de schemas de FastMCP. Cada tipo de Python se convierte automáticamente en un tipo equivalente de JSON Schema, que el modelo de IA usa para saber exactamente qué parámetros enviar al llamar a la tool. Cuanto más precisos sean los type hints, más preciso será el modelo al usar la tool.
FastMCP convierte automáticamente los type hints de Python en JSON Schema:
El modelo usa este esquema para validar los parámetros antes de enviar, lo que garantiza que la tool siempre reciba datos en el formato correcto.
Siempre usa type hints lo más específico posible. En lugar de list, usa list[str]. En lugar de dict, usa dict[str, int]. Cuanta más información tenga el schema, más correctamente completará el modelo los parámetros. Un parámetro marcado como Optional[str] = None indica al modelo que puede omitir este campo cuando no sea relevante.
Lo que devuelve la tool es tan importante como lo que recibe. FastMCP admite varios tipos de retorno y se encarga de la serialización automáticamente. Las cadenas se devuelven directamente, los diccionarios y las listas se convierten en JSON y los tipos complejos se procesan de forma transparente. Entender los tipos de retorno te ayuda a crear tools que comuniquen los resultados con claridad al modelo.
Las tools MCP pueden devolver diferentes tipos de datos: str — el más común, devuelve texto simple que el modelo puede usar directamente; dict — para datos estructurados, serializado automáticamente en JSON; list — para colecciones de elementos, también serializado en JSON. FastMCP convierte cualquiera de estos tipos al formato de respuesta MCP correcto. En la mayoría de los casos, devolver una str con la información formateada es la opción más simple y eficaz.
La función de Python devuelve un valor (str, dict, list u otro tipo compatible).
FastMCP detecta el tipo del valor devuelto y lo convierte al formato de contenido MCP (TextContent para strings, JSON para dicts/lists).
El resultado se encapsula en una respuesta JSON-RPC y se envía de vuelta al client, que se lo reenvía al modelo.
Las docstrings de tus funciones no son solo una buena práctica de programación: en el contexto de MCP, son la interfaz entre el modelo de IA y la tool. El modelo lee la descripción para decidir cuándo usar la tool y cómo completarla. Una descripción deficiente hará que el modelo use la tool en el momento equivocado o con parámetros incorrectos. Una buena descripción hará que la tool se use a la perfección.
A docstring de la función se convierte en el campo description de la tool en el protocolo MCP. El modelo de IA lee esta descripción para tomar tres decisiones: (1) Cuándo usar — "¿esta tool es relevante para lo que pidió el usuario?"; (2) Cómo usarlo — «¿qué parámetros debo pasar?»; y (3) Qué esperar: "¿qué tipo de resultado devuelve esta tool?". Cuanto más clara, específica e informativa sea la descripción, mejor usará el modelo la tool. Las descripciones vagas llevan a un uso impreciso.
Escribe docstrings como si le explicaras la tool a un colega que nunca ha visto tu código. Sé específico sobre lo que hace la tool, menciona cuándo debe usarse, y describe qué significa cada parámetro. Por ejemplo: en vez de «Busca datos», escribe «Busca el pronóstico del tiempo actual para una ciudad brasileña. Devuelve la temperatura, la humedad y las condiciones climáticas».
Construir tools MCP que funcionen es fácil. Construir tools que funcionen bien exige prestar atención a las buenas prácticas. Los nombres claros, los type hints completos, las docstrings descriptivas y el uso inteligente de defaults y Optional impactan directamente en la calidad de la experiencia del usuario final con la IA. Estas son las prácticas que distinguen las tools de aficionados de las profesionales.
Las buenas prácticas para las tools MCP incluyen: Nombres claros — usa verbos descriptivos como buscar_clima, criar_tarefa, enviar_email; Type hints completos — marca todos los parámetros y el valor de retorno con tipos precisos; Docstrings descriptivos — explica qué hace la tool, cuándo usarla y qué significa cada parámetro; Valores predeterminados inteligentes — usa valores predeterminados cuando un parámetro suele tener un valor más común; y Optional — usa Optional[tipo] para los campos que no son obligatorios, lo que permite que el modelo los omita cuando no sean relevantes.
Nunca confíes en que el modelo enviará parámetros correctos — valida siempre las entradas dentro de la función. Aunque JSON Schema ayuda, el modelo puede enviar valores inesperados (cadenas vacías, números fuera del rango, etc.). Usa validaciones simples al inicio de la función y devuelve mensajes de error claros cuando los datos no sean válidos. Una tool que falla con un mensaje útil es mucho mejor que una que se bloquea sin avisar.
@mcp.tool() extrae automáticamente: nombre (de la función), descripción (de la docstring) y parámetros (de las anotaciones de tipo).
Siguiente Módulo: 3.4 — Servidor de calculadora