# Catálogo Frogames — servidor MCP remoto

Este es el proyecto del vídeo **"Tu servidor MCP fuera del portátil"**, la segunda parte de
[Crea tu primer servidor MCP en Python](https://youtu.be/YFA5nCliGV4).

Es el **estado final**: el mismo servidor del vídeo anterior, pero sobre transporte
**streamable HTTP**, con endpoint de salud y autenticación por token, listo para desplegar en un
VPS. Si buscas la versión sencilla sobre stdio, está en el repositorio del vídeo anterior.

## Qué hay aquí

| Fichero | Qué es |
|---|---|
| `servidor.py` | El servidor: 1 tool (`buscar_curso`), 2 resources, `/salud` y middleware de token |
| `cursos.json` | Catálogo real de cursos de Frogames |
| `pyproject.toml` | Proyecto `uv` con `mcp[cli]` (que ya trae uvicorn) |
| `despliegue/catalogo-mcp.service` | Unidad de systemd para que el proceso no se muera nunca |
| `despliegue/nginx-catalogo.conf` | Proxy inverso de Nginx, con las líneas que necesita el streaming |

## Probarlo en local

```bash
uv sync
CATALOGO_TOKEN=$(openssl rand -hex 32) uv run python servidor.py
```

El servidor queda escuchando en `http://127.0.0.1:8000/mcp` (y `/salud` para comprobar que está
vivo). Variables de entorno disponibles: `CATALOGO_TOKEN`, `CATALOGO_HOST`, `CATALOGO_PORT`.

> ⚠️ **Sin `CATALOGO_TOKEN`, el servidor rechaza todas las peticiones con 401.** Es intencionado:
> es mejor que no arranque útil a que arranque abierto.

## Conectarlo desde Claude Code

```bash
claude mcp add --transport http catalogo http://127.0.0.1:8000/mcp \
  --header "Authorization: Bearer TU_TOKEN"
```

Y en producción, con tu dominio:

```bash
claude mcp add --transport http catalogo https://TU_DOMINIO/mcp \
  --header "Authorization: Bearer TU_TOKEN"
```

## Desplegarlo en un VPS

Los pasos completos están en el vídeo. Resumen:

1. Usuario sin privilegios (nunca root), `uv` instalado, `git clone` + `uv sync`.
2. `despliegue/catalogo-mcp.service` → `/etc/systemd/system/`, sustituyendo `<usuario>` y
   `<token>`. `daemon-reload`, `enable`, `start`.
3. Registro DNS de tipo A apuntando al VPS.
4. `despliegue/nginx-catalogo.conf` → `/etc/nginx/sites-available/`, sustituyendo `<dominio>`.
   Enlace simbólico a `sites-enabled`, `nginx -t`, `reload`.
5. `certbot --nginx -d <dominio>` para el HTTPS.
6. Firewall: solo SSH y Nginx. El puerto 8000 **no** se abre — el proceso escucha en `127.0.0.1`.

## Sobre la autenticación

El middleware de este repo es un token estático (`Authorization: Bearer …`). Es lo mínimo
razonable para exponer un servidor MCP en internet y es lo que se enseña en el vídeo.

El SDK de MCP soporta además OAuth 2.1 como servidor de recursos, vía los parámetros `auth` y
`token_verifier` de `MCPServer`. Si vas a dar acceso a terceros de verdad, ese es el camino.

---

Curso completo de Ingeniería de Agentes de IA:
<https://cursos.frogamesformacion.com/courses/agentes-ia>