mcp-exports

Host de descarga compartido y de un solo uso para los servidores MCP de la casa.

https://exports.example.com · puerto del host 8114 · sin inicio de sesión para clientes

MCP server  --POST /put  (service token)-->  mcp-exports  -->  download URL
customer    --GET  /d/{token} (no auth)  -->  mcp-exports  -->  the file, once

Por qué existe

Una herramienta que devuelve una semana de registros de llamadas en línea cuesta ~530 000 tokens; los mismos datos como CSV pesan 1 MB y se generan en 1,6 segundos. Por eso las exportaciones devuelven un enlace. La primera versión servía ese enlace desde el propio servidor MCP, lo que fallaba de tres maneras:

1. Los hosts MCP están detrás de una lista de permisos de IP solo de Anthropic, pero quien descarga un archivo es el navegador de un cliente desde una dirección arbitraria. Un nombre de host separado evita que las dos políticas de acceso se pisen, en lugar de abrir una excepción de ruta en una configuración de proxy que además lleva los ajustes de streaming que MCP necesita.

2. Los contenedores MCP se vuelven a desplegar en cada push, y un almacén en memoria moría con ellos, invalidando enlaces activos a mitad de una conversación.

3. El almacén pertenecía a un solo proceso, así que un segundo worker daba 404 al azar.

Related MCP server: agent-secret

Modelo de seguridad, dicho claro

Una URL de descarga es una capacidad: quien la tenga consigue el archivo, sin inicio de sesión. Misma disyuntiva que las URLs de grabaciones de NetSapiens y los PDF del portal de Odoo que ya repartimos, y es lo que hace que un enlace funcione al hacer clic desde una ventana de chat. No es autenticación, y las debilidades son reales: una URL puede reenviarse, quedar registrada en un proxy o permanecer en una transcripción para siempre.

Así que el diseño se apoya en lo que de verdad ayuda:

La subida está autenticada — un token bearer por servidor, porque publicar archivos en un host público no es algo que se le permita a Internet. El servicio se niega a arrancar con una lista de permisos vacía.

API

POST /put?filename=x.csv&sensitivity=data|financial&customer=Acme%20Movers
     &ttl=3600&max_downloads=1
     Authorization: Bearer <server token>
  -> 201 {download_url, filename, size, expires_in_seconds, expires_at,
          max_downloads, single_use}

GET  /d/{token}   -> 200 the file (then it is gone), or 404
GET  /healthz     -> counters + bytes held

El ttl se limita, no se obedece — pide una semana, recibe MCP_EXPORTS_TTL_MAX, y la respuesta te dice lo que realmente has recibido.

Cómo usarlo desde un servidor MCP

Copia client/export_client.py en el servidor y define MCP_EXPORTS_URL + MCP_EXPORTS_TOKEN. ExportClient.from_env() devuelve None cuando no está configurado, de modo que un servidor puede ofrecer herramientas de exportación solo donde el host esté realmente conectado, en lugar de anunciar una herramienta que siempre falla.

Lanza una excepción en lugar de degradarse a filas en línea: si el host está caído no hay degradación segura, porque devolver las filas es el modo de fallo que las exportaciones existen para evitar.

Despliegue

Portainer → Stacks → Repository, refs/heads/main, puerto 8114. Genera un token por servidor MCP:

python -c "import secrets; print(secrets.token_urlsafe(32))"

NPM: exports.example.com → 10.0.0.10:8114, sin Lista de Acceso (esa es la gracia), Websockets desactivados, timeouts estándar.

Pruebas

python -m pytest tests -q

47 pruebas, sin red. Cubren específicamente las propiedades de seguridad: el uso único borra los bytes de verdad, todas las formas de token inválido son indistinguibles, los nombres de archivo no pueden escapar ni inyectar cabeceras, el TTL financiero es más corto, y el Dockerfile hace chown del punto de montaje del volumen antes de soltar el usuario root — sin lo cual un volumen con nombre llegaría con propietario root y cada subida fallaría con EACCES.