Tutorial: Creando un servidor FastMCP para Claude

Este tutorial te guiará paso a paso para crear un servidor MCP (Model Context Protocol) utilizando FastMCP y conectarlo con Claude, permitiendo que el modelo acceda a herramientas y funcionalidades personalizadas.

1. Entendiendo los componentes básicos de FastMCP

Creación del servidor

mcp = FastMCP(
    name="ServerTest",
    instructions="Este es un servidor de test"
)

Este código crea una instancia de servidor FastMCP con:

• name: El nombre del servidor ("ServerTest") que se mostrará a los clientes

• instructions: Una descripción que explica el propósito del servidor, ayudando a los clientes (como Claude) a entender cómo interactuar con él

El servidor actúa como contenedor principal para todas las herramientas, recursos y prompts que definas.

Definición de herramientas con @mcp.tool

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

El decorador @mcp.tool() registra una función como una herramienta que Claude puede invocar:

• Nombre: Por defecto usa el nombre de la función ("add")

• Descripción: Utiliza la docstring ("Suma dos números")

• Parámetros: Define los argumentos requeridos con sus tipos (a: int, b: int)

• Tipo de retorno: Especifica el tipo de valor devuelto (-> int)

Las anotaciones de tipo son importantes porque:

• Ayudan a Claude a entender qué datos debe proporcionar

• Permiten a FastMCP validar los datos de entrada

• Generan automáticamente documentación para las herramientas

Related MCP server: MCP Calculator

2. Transporte STDIO vs HTTP

¿Qué es STDIO?

STDIO (Standard Input/Output) es un transporte que utiliza la entrada y salida estándar del sistema para la comunicación:

• Ventajas: Simple, no requiere configuración de red, ideal para herramientas locales

• Uso ideal: Integración con Claude y otros clientes que gestionan el ciclo de vida del servidor

• Configuración: mcp.run() sin parámetros (es el transporte predeterminado)

if __name__ == "__main__":
    mcp.run()  # Usa STDIO por defecto

HTTP (para referencia)

HTTP permite exponer el servidor a través de una interfaz web:

• Ventajas: Accesible a través de la red, adecuado para microservicios

• Configuración:

  mcp.run(transport="http", host="127.0.0.1", port=9000)

3. Proyecto paso a paso: Servidor FastMCP para Claude

Paso 1: Crear un entorno virtual e instalar FastMCP

# Crear un entorno virtual
python -m venv venv

# Activar el entorno virtual
# En Windows:
venv\Scripts\activate
# En macOS/Linux:
source venv/bin/activate

# Instalar FastMCP
pip install fastmcp

Paso 2: Crear un archivo de servidor (app.py)

from fastmcp import FastMCP

# Crear una instancia del servidor
mcp = FastMCP(
    name="MiAsistente",
    instructions="Este servidor proporciona herramientas matemáticas y utilidades"
)

# Herramienta para sumar números
@mcp.tool()
def sumar(a: int, b: int) -> int:
    """Suma dos números enteros"""
    return a + b

# Herramienta para multiplicar números
@mcp.tool()
def multiplicar(a: float, b: float) -> float:
    """Multiplica dos números"""
    return a * b

# Herramienta para convertir temperaturas
@mcp.tool()
def celsius_a_fahrenheit(celsius: float) -> float:
    """Convierte temperatura de Celsius a Fahrenheit"""
    return (celsius * 9/5) + 32

# Configuración para ejecutar el servidor
if __name__ == "__main__":
    mcp.run()  # Usa STDIO por defecto

Paso 3: Configurar Claude para usar tu servidor

1. Crea un archivo de configuración MCP (mcp_config.json):

{
  "mcpServers": {
    "miasistente": {
      "command": "python",
      "args": [
        "ruta/completa/a/tu/app.py"
      ]
    }
  }
}

Reemplaza "ruta/completa/a/tu/app.py" con la ruta real a tu archivo app.py, por ejemplo: "C:/Users/usuario/proyectos/miasistente/app.py"

2. Comparte esta configuración con Claude para que pueda utilizar tus herramientas.

Paso 4: Probar el servidor

Una vez configurado, puedes pedirle a Claude que utilice las herramientas:

• "Utiliza la herramienta sumar para calcular 23 + 45"

• "Convierte 25 grados Celsius a Fahrenheit usando la herramienta celsius_a_fahrenheit"

Claude podrá ejecutar estas funciones y devolverte los resultados calculados por tu servidor.

Solución de problemas comunes

• Error "No module named 'fastmcp'": Asegúrate de instalar FastMCP en el entorno Python que estás utilizando.

• Problemas de conexión: Verifica que las rutas en la configuración MCP sean correctas y absolutas.

• Errores en tiempo de ejecución: Añade manejo de excepciones en tus herramientas para proporcionar mensajes de error útiles.

Evidencias de la integración con Claude

Reconocimiento del servidor por Claude

En esta imagen se puede ver cómo Claude detecta correctamente el servidor FastMCP y puede interactuar con él.

Funcionalidades disponibles

Esta imagen muestra las funcionalidades que Claude puede leer y utilizar desde nuestro servidor FastMCP, permitiéndole invocar las herramientas que hemos definido.