Una Guía para Principiantes sobre cómo Usar FastMCP

El panorama de los Modelos de Lenguaje Grande (LLMs) está evolucionando rápidamente, pasando más allá de la simple generación de texto hacia interacciones complejas con sistemas externos y fuentes de datos. Facilitar esta interacción requiere un enfoque estandarizado, un lenguaje común para que los LLMs soliciten información y activen acciones. Aquí es donde entra el Protocolo de Contexto del Modelo (MCP), diseñado como un estándar universal – a menudo comparado con "el puerto USB-C para la IA" – que permite una comunicación fluida entre los LLMs y los recursos que necesitan.

Mientras que MCP proporciona la especificación, construir servidores y clientes que se adhieran a ella puede implicar una cantidad significativa de código repetitivo y gestión del protocolo. Aquí es donde brilla FastMCP. FastMCP es un marco de alto nivel, Pythonic, diseñado para simplificar drásticamente la creación de servidores y clientes MCP. Maneja las complejidades subyacentes del protocolo, permitiendo a los desarrolladores centrarse en definir las herramientas valiosas, recursos de datos y patrones de interacción que quieren exponer a los LLMs.

💡

¿Quieres una gran herramienta de prueba de API que genere documentación de API hermosa?

¿Quieres una plataforma integrada y todo en uno para que tu equipo de desarrolladores trabaje junto con máxima productividad?

Apidog cumple con todas tus demandas, y reemplaza a Postman a un precio mucho más asequible!

button

¿Qué es el Protocolo de Contexto del Modelo (MCP)?

Antes de profundizar en FastMCP, es esencial entender los conceptos básicos del MCP en sí. MCP define una forma estandarizada para que las aplicaciones LLM (clientes) interactúen con sistemas externos (servidores). Un servidor MCP puede exponer varios componentes clave:

Herramientas: Estas son esencialmente funciones que un LLM puede solicitar al servidor que ejecute. Piénsalas como puntos finales POST en una API tradicional. Realizan acciones, potencialmente interactúan con otros sistemas (bases de datos, APIs, hardware) y devuelven resultados. Por ejemplo, una herramienta podría enviar un correo electrónico, consultar una base de datos o realizar un cálculo.
Recursos: Estos exponen datos que un LLM puede leer o recuperar. Similar a los puntos finales GET, los recursos proporcionan información para enriquecer el contexto del LLM. Esto podría ser cualquier cosa, desde archivos de configuración y perfiles de usuario hasta flujos de datos en tiempo real.
Prompts: Estos son plantillas reutilizables para estructurar interacciones con el LLM. Ayudan a guiar la conversación y asegurar salidas consistentes para tareas específicas.
Contexto: Los servidores pueden proporcionar información contextual, incluyendo instrucciones sobre cómo interactuar mejor con las herramientas y recursos disponibles.

MCP tiene como objetivo crear un ecosistema robusto y seguro donde los LLMs puedan acceder de manera confiable y utilizar capacidades externas.

¿Por qué elegir FastMCP?

Si bien podrías implementar la especificación MCP directamente usando SDKs de bajo nivel, FastMCP ofrece ventajas convincentes, particularmente para desarrolladores de Python:

🚀 Desarrollo Rápido: Su interfaz de alto nivel reduce significativamente la cantidad de código necesario, acelerando el proceso de desarrollo. A menudo, definir una herramienta o recurso es tan simple como decorar una función estándar de Python.
🍀 Simplicidad: FastMCP abstrae los detalles complejos de configuración del servidor, manejo de protocolos, tipos de contenido y gestión de errores, minimizando el código repetitivo.
🐍 Pythonic: Diseñado con las mejores prácticas de Python en mente, se siente natural e intuitivo para desarrolladores familiarizados con el lenguaje, aprovechando características como las sugerencias de tipo y decoradores.
🔍 Completo: FastMCP tiene como objetivo proporcionar una implementación completa de la especificación central de MCP, asegurando compatibilidad y acceso al potencial completo del protocolo.

La versión 1 de FastMCP fue muy exitosa y ahora está integrada en el SDK oficial de MCP para Python. La versión 2 se basa en esta fundación, introduciendo características avanzadas centradas en simplificar las interacciones del servidor, como clientes flexibles, proxy de servidor y patrones de composición.

Cómo instalar FastMCP

Configurar FastMCP en tu entorno de Python es sencillo. El método recomendado utiliza uv, un instalador y resolutor de paquetes de Python rápido.

1. Usando uv (Recomendado):

Si estás gestionando dependencias para un proyecto, agrega FastMCP usando:

uv add fastmcp

Alternativamente, instálalo directamente en tu entorno:

uv pip install fastmcp

2. Usando pip:

Si prefieres usar pip, puedes instalar FastMCP con:

pip install fastmcp

3. Verificando la Instalación:

Después de la instalación, puedes verificar que FastMCP está correctamente instalado y comprobar su versión, junto con la versión del SDK MCP subyacente y los detalles de tu entorno de Python, ejecutando:

fastmcp version

Deberías ver una salida similar a esta:

$ fastmcp version

FastMCP versión:   0.4.2.dev41+ga077727.d20250410
MCP versión:                                1.6.0
Python versión:                            3.12.2
Plataforma:            macOS-15.3.1-arm64-arm-64bit
Ruta raíz de FastMCP:            ~/Developer/fastmcp

4. Instalando para Desarrollo:

Si tienes la intención de contribuir al proyecto FastMCP en sí, querrás configurar un entorno de desarrollo:

git clone https://github.com/jlowin/fastmcp.git
cd fastmcp
uv sync

Esto clona el repositorio, navega al directorio, y usa uv sync para instalar todas las dependencias necesarias, incluyendo herramientas de desarrollo, dentro de un entorno virtual. Luego puedes ejecutar pruebas usando pytest.

Cómo usar FastMCP: Creando tu Primer Servidor

Ahora, vamos a sumergirnos en los aspectos prácticos de usar FastMCP.

1. Creando una Instancia de Servidor Básica:

El núcleo de cualquier aplicación FastMCP es la clase FastMCP. Comienzas creando una instancia de esta clase.

Crea un archivo llamado my_server.py:

# my_server.py
from fastmcp import FastMCP
import asyncio # Necesitaremos esto más tarde para el cliente

# Instanciar el servidor, dándole un nombre
mcp = FastMCP(name="Mi Primer Servidor MCP")

print("Objeto del servidor FastMCP creado.")

El constructor de FastMCP acepta varios argumentos útiles:

name (str, opcional): Un nombre legible por humanos para tu servidor (por defecto "FastMCP"). Útil para identificación en registros o aplicaciones cliente.
instructions (str, opcional): Una descripción que guía a los clientes sobre cómo interactuar con el servidor, explicando su propósito o destacando funcionalidades clave.
lifespan (callable, opcional): Un administrador de contexto asíncrono para manejar la lógica de inicio y apagado del servidor (por ejemplo, inicializando conexiones de base de datos).
tags (set[str], opcional): Etiquetas para categorizar el servidor en sí.
**settings: Puedes pasar argumentos de palabras clave correspondientes a ServerSettings (como port, host, log_level) directamente al constructor para la configuración.

2. Agregando Componentes:

Un servidor vacío no es muy útil. Agreguemos los componentes centrales de MCP.

Agregando una Herramienta: Las herramientas son funciones expuestas al cliente. Usa el decorador @mcp.tool(). FastMCP utiliza sugerencias de tipo de Python para definir los parámetros de entrada esperados y el tipo de retorno para el cliente.

# my_server.py (continuación)
@mcp.tool()
def greet(name: str) -> str:
    """Devuelve un saludo simple."""
    return f"¡Hola, {name}!"

@mcp.tool()
def add(a: int, b: int) -> int:
    """Suma dos números."""
    return a + b

print("Herramientas 'greet' y 'add' agregadas.")

Agregando un Recurso: Los recursos exponen datos a través de una URI. Usa el decorador @mcp.resource(), proporcionando la cadena de la URI.

# my_server.py (continuación)
APP_CONFIG = {"theme": "dark", "version": "1.1", "feature_flags": ["new_dashboard"]}

@mcp.resource("data://config")
def get_config() -> dict:
    """Proporciona la configuración de la aplicación."""
    return APP_CONFIG

print("Recurso 'data://config' agregado.")

Agregando una Plantilla de Recurso: Estas son como recursos dinámicos donde partes de la URI actúan como parámetros.

# my_server.py (continuación)
USER_PROFILES = {
    101: {"name": "Alice", "status": "active"},
    102: {"name": "Bob", "status": "inactive"},
}

@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: int) -> dict:
    """Recupera el perfil de un usuario por su ID."""
    # El {user_id} de la URI se pasa automáticamente como un argumento
    return USER_PROFILES.get(user_id, {"error": "Usuario no encontrado"})

print("Plantilla de recurso 'users://{user_id}/profile' agregada.")

Agregando un Prompt: Los prompts definen patrones de interacción reutilizables.

# my_server.py (continuación)
@mcp.prompt("summarize")
async def summarize_prompt(text: str) -> list[dict]:
    """Genera un prompt para resumir el texto proporcionado."""
    return [
        {"role": "system", "content": "Eres un asistente útil experto en resumir."},
        {"role": "user", "content": f"Por favor, resume el siguiente texto:\n\n{text}"}
    ]

print("Prompt 'summarize' agregado.")

3. Probando el Servidor (En Proceso):

Antes de ejecutar el servidor externamente, puedes probar sus componentes directamente dentro del mismo script de Python usando el Client. Esto es útil para comprobaciones rápidas y pruebas unitarias.

# my_server.py (continuación)
from fastmcp import Client # Importar el cliente

async def test_server_locally():
    print("\n--- Probando el Servidor Localmente ---")
    # Apunta el cliente directamente al objeto del servidor
    client = Client(mcp)

    # Los clientes son asíncronos, así que usa un administrador de contexto asíncrono
    async with client:
        # Llama a la herramienta 'greet'
        greet_result = await client.call_tool("greet", {"name": "Usuario de FastMCP"})
        print(f"resultado de greet: {greet_result}")

        # Llama a la herramienta 'add'
        add_result = await client.call_tool("add", {"a": 5, "b": 7})
        print(f"resultado de add: {add_result}")

        # Lee el recurso 'config'
        config_data = await client.read_resource("data://config")
        print(f"recurso de configuración: {config_data}")

        # Lee un perfil de usuario usando la plantilla
        user_profile = await client.read_resource("users://101/profile")
        print(f"Perfil del Usuario 101: {user_profile}")

        # Obtén la estructura del prompt 'summarize' (no ejecuta la llamada al LLM aquí)
        prompt_messages = await client.get_prompt("summarize", {"text": "Este es un texto."})
        print(f"Estructura del prompt para resumir: {prompt_messages}")

# Ejecuta la función de prueba local
# asyncio.run(test_server_locally())
# Comentado por ahora, nos centraremos en ejecutar el servidor a continuación

Nota el uso de async y await. Los clientes de FastMCP operan de manera asíncrona, requiriendo una función async y usando async with client: para gestionar el ciclo de vida del cliente.

4. Ejecutando el Servidor:

Para hacer que tu servidor MCP sea accesible para clientes externos (como una aplicación LLM), necesitas ejecutarlo. Hay dos formas principales:

Ejecución Estándar de Python (Recomendada para Compatibilidad):
Agrega el siguiente bloque if __name__ == "__main__": a tu archivo my_server.py. Esta es la práctica estándar de Python para hacer que un script sea ejecutable.

# my_server.py (al final del archivo)

if __name__ == "__main__":
    print("\n--- Iniciando el Servidor FastMCP a través de __main__ ---")
    # Esto inicia el servidor, típicamente usando el transporte stdio por defecto
    mcp.run()

Para ejecutar el servidor, ejecuta el script desde tu terminal:

python my_server.py

Este comando inicia el servidor MCP, escuchando conexiones de clientes usando el mecanismo de transporte por defecto stdio (entrada/salida estándar). Este método asegura que tu servidor funcione de manera consistente para varios clientes que esperan ejecutar un script de Python.

Usando la CLI de FastMCP:
FastMCP proporciona una interfaz de línea de comandos para ejecutar servidores, que ofrece más flexibilidad y control, especialmente en lo que respecta a las opciones de transporte.

# Ejecutar el servidor usando stdio (por defecto)
fastmcp run my_server.py:mcp

# Ejecutar el servidor usando Eventos Enviados por el Servidor (SSE) en el puerto 8080
fastmcp run my_server.py:mcp --transport sse --port 8080 --host 0.0.0.0

# Ejecutar con un nivel de registro diferente
fastmcp run my_server.py:mcp --transport sse --log-level DEBUG

Puntos clave sobre la CLI:

my_server.py:mcp: Especifica el archivo (my_server.py) y el objeto del servidor FastMCP dentro de ese archivo (mcp). Si omites :mcp, FastMCP intentará encontrar automáticamente un objeto llamado mcp, app, o server.
El bloque if __name__ == "__main__": no es requerido al usar fastmcp run; la CLI encuentra y ejecuta directamente el objeto del servidor especificado.
--transport: Selecciona el protocolo de comunicación (stdio, sse). SSE es común para interacciones basadas en la web.
--port, --host, --log-level: Configura opciones de transporte y registro.

5. Interactuando con un Servidor en Ejecución (Cliente):

Una vez que tu servidor esté en funcionamiento (ya sea a través de python my_server.py o fastmcp run), puedes crear un script de cliente separado para interactuar con él.

Crea un nuevo archivo, my_client.py:

# my_client.py
from fastmcp import Client
import asyncio

async def interact_with_server():
    print("--- Creando Cliente ---")

    # Opción 1: Conectar a un servidor ejecutado a través de `python my_server.py` (usa stdio)
    # client = Client("my_server.py")

    # Opción 2: Conectar a un servidor ejecutado a través de `fastmcp run ... --transport sse --port 8080`
    client = Client("http://localhost:8080") # Usa la URL/puerto correcto

    print(f"Cliente configurado para conectarse a: {client.target}")

    try:
        async with client:
            print("--- Cliente Conectado ---")
            # Llama a la herramienta 'greet'
            greet_result = await client.call_tool("greet", {"name": "Cliente Remoto"})
            print(f"resultado de greet: {greet_result}")

            # Lee el recurso 'config'
            config_data = await client.read_resource("data://config")
            print(f"recurso de configuración: {config_data}")

            # Lee el perfil del usuario 102
            profile_102 = await client.read_resource("users://102/profile")
            print(f"Perfil del Usuario 102: {profile_102}")

    except Exception as e:
        print(f"Ocurrió un error: {e}")
    finally:
        print("--- Interacción del Cliente Finalizada ---")

if __name__ == "__main__":
    asyncio.run(interact_with_server())

Ejecuta este script de cliente mientras el servidor está en ejecución en otra terminal:

python my_client.py

El cliente se conectará al servidor en ejecución (asegúrate de que el Client(...) objetivo coincida con cómo se está ejecutando el servidor – ruta del archivo para stdio, URL para sse), ejecutará las llamadas a las herramientas y lecturas de recursos, e imprimirá los resultados.

6. Configuración del Servidor (ServerSettings):

Puedes ajustar el comportamiento del servidor usando ServerSettings. Las configuraciones pueden aplicarse en orden de precedencia:

Argumentos de palabras clave durante la inicialización de FastMCP (máxima precedencia).
Variables de entorno (prefijadas con FASTMCP_SERVER_, por ejemplo, FASTMCP_SERVER_PORT=8888).
Valores cargados desde un archivo .env en el directorio de trabajo.
Valores predeterminados (mínima precedencia).

Ejemplo de configuración durante la inicialización:

from fastmcp import FastMCP

mcp_configured = FastMCP(
    name="Servidor Configurado",
    port=8080,  # Establece el puerto SSE predeterminado
    host="127.0.0.1", # Establece el host SSE predeterminado
    log_level="DEBUG", # Establece el nivel de registro
    on_duplicate_tools="warn" # Advierte si se registran herramientas con el mismo nombre (opciones: 'error', 'warn', 'ignore')
)

# Accede a la configuración a través del atributo .settings
print(f"Puerto Configurado: {mcp_configured.settings.port}") # Salida: 8080
print(f"Política de Herramientas Duplicadas: {mcp_configured.settings.on_duplicate_tools}") # Salida: warn

Las opciones clave de configuración incluyen host, port, log_level, y políticas para manejar nombres de componentes duplicados (on_duplicate_tools, on_duplicate_resources, on_duplicate_prompts).

¿Qué más puedes hacer con FastMCP?

FastMCP también admite casos de uso más avanzados:

Composición: Combina múltiples servidores FastMCP. main.mount("sub", sub_server) crea un enlace en vivo, mientras que main.import_server(sub_server) copia componentes. Esto ayuda a la modularidad.
Proxying: Usa FastMCP.from_client(client) para crear una instancia del servidor FastMCP que actúe como un proxy para otro servidor MCP (local o remoto). Esto es útil para puentear transportes (por ejemplo, exponiendo un servidor SSE remoto a través de stdio local) o agregando un frontend unificado.

Conclusión

FastMCP reduce significativamente la barrera de entrada para construir aplicaciones LLM potentes y conscientes del contexto al simplificar la implementación del Protocolo de Contexto del Modelo. Su diseño Pythonic, enfoque en reducir el código repetitivo y conjunto de características integral lo convierten en una excelente opción para los desarrolladores que buscan equipar a los LLMs con herramientas y acceso a datos personalizados de manera segura y eficiente.

Siguiendo los pasos delineados anteriormente – instalando FastMCP, creando una instancia del servidor, agregando herramientas y recursos usando decoradores simples, y ejecutando el servidor – puedes comenzar rápidamente a construir tus propias aplicaciones habilitadas para MCP. Ya sea que estés creando herramientas utilitarias simples o integraciones complejas e intensivas en datos, FastMCP proporciona la base para interacciones LLM robustas y escalables.