# 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

```python
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

```python
@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

## 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)

```python
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**: 
  ```python
  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

```bash
# 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)

```python
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):

```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

![Claude detectando el servidor MCP](/evidencias/claude.jpeg)

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

### Funcionalidades disponibles

![Funcionalidades del servidor MCP](/evidencias/funcionalidades.jpeg)

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