Paxaver MCP Server

Adaptador orientado a IA sobre la plataforma comunitaria escolar Paxaver. Implementa el Protocolo de Contexto de Modelo (MCP) en Cloudflare Workers con validación JWT RS256, autorización basada en capacidades y transporte HTTP Streamable.

Qué es esto

El servidor MCP de Paxaver permite que los asistentes de IA (ChatGPT, Claude, Perplexity y cualquier cliente compatible con MCP) actúen en nombre de un usuario de Paxaver: consultar un menú de almuerzo, pedir almuerzo, recargar un monedero, registrarse en eventos de recaudación de fondos, donar a una escuela, ser voluntario y — para administradores escolares — gestionar restaurantes, elementos de menú, eventos y pedidos diarios.

Es un adaptador delgado. No contiene lógica de negocio y nunca toca la base de datos, Stripe o el correo electrónico directamente. Cada acción se delega a la API privada del backend de Paxaver a través de un service binding de Cloudflare (misma región, sin salto de red pública). Las únicas responsabilidades del servidor MCP son:

• Manejo del protocolo MCP (JSON-RPC 2.0, HTTP Streamable)

• Validación JWT RS256 mediante JWKS del worker de autenticación centralizado de Paxaver

• Política de capacidades por herramienta y control de roles

• Mapeo de errores sanitizado y seguro para el usuario

La autenticación la gestiona el worker de autenticación de Paxaver (auth.paxaver.com), que actúa como servidor de autorización OAuth 2.0 / OIDC. El servidor MCP valida los JWT RS256 resultantes y los reenvía al backend. El propio servidor MCP no es un servidor de autorización.

Related MCP server: IIITH Mess MCP

Arquitectura

┌───────────────┐     MCP (Streamable HTTP)      ┌──────────────────────┐
│   AI Client   │ ─────────────────────────────▶ │   Paxaver MCP Worker │
│ ChatGPT/Claude│ ◀───────────────────────────── │  (this repo)         │
│  /Perplexity  │     RS256 JWT + JSON-RPC 2.0   │  Hono + jose         │
└───────────────┘                                └──────────┬───────────┘
                                                            │
                                          Cloudflare service binding
                                          (PAXAVER_API, same region)
                                                            │
                                                            ▼
                                                 ┌──────────────────────┐
                                                 │  Paxaver API Worker  │
                                                 │  (private backend)   │
                                                 │  D1 · Stripe · SES   │
                                                 └──────────────────────┘

El worker MCP nunca se vincula a D1, Stripe o SES. El service binding lleva un JWT de corta duración (TTL de 120 s, audiencia paxaver-internal) que el backend confía como llamada interna mientras sigue atribuyendo la acción al usuario autenticado de Paxaver. Consulta docs/architecture.md para obtener el panorama completo.

Inicio rápido

Instalar

npm install @paxaver/mcp

Desarrollar localmente

# 1. Install dependencies (Node >= 22)
npm install

# 2. Configure local secrets
cp .dev.vars.example .dev.vars   # then fill in JWT_SECRET, OAUTH_STATE_SECRET, ...

# 3. Run the worker locally (Miniflare)
npm run dev

# 4. Typecheck, lint, and test
npm run typecheck
npm run lint
npm test

El servidor de desarrollo local se inicia en http://localhost:8787. Los endpoints de descubrimiento se encuentran en /.well-known/; el endpoint MCP es POST /mcp.

Nota: El desarrollo local sin el service binding PAXAVER_API recurre a HTTPS autenticado contra API_BASE_URL (por defecto http://localhost:8787). Para pruebas de integración completas, ejecuta el worker del backend de Paxaver localmente y apunta API_BASE_URL a él.

Despliegue

Dos entornos, cada uno un Worker separado con su propio dominio personalizado:

El worker de producción atiende a usuarios de CA y EE. UU. a través de un único endpoint (mcp.paxaver.com). La región del usuario se resuelve a partir del claim tenant_id del JWT, y el worker enruta al backend regional correcto mediante service bindings (PAXAVER_API_CA, PAXAVER_API_US). La moneda la determina la escuela del usuario, no el endpoint MCP.

npm run deploy:staging   # wrangler deploy --env staging
npm run deploy:prod      # wrangler deploy --env production

Los secretos deben configurarse con wrangler secret put --env production: JWT_SECRET, OAUTH_STATE_SECRET, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, CHATGPT_VERIFY_TOKEN. Consulta docs/deployment.md.

Herramientas

El servidor expone 31 herramientas agrupadas en seis categorías. La visibilidad en tools/list se filtra según los roles del llamante; cada llamada se vuelve a autorizar antes del envío, y el backend vuelve a comprobar el acceso a nivel de datos (defensa en profundidad).

Las herramientas financieras y destructivas están etiquetadas y requieren confirmación del usuario. Referencia completa: docs/tools.md. Política de autorización: docs/authorization.md.

Documentación

Pila tecnológica

• Tiempo de ejecución: Cloudflare Workers (compatibility_date: 2026-08-01, nodejs_compat)

• Framework: Hono v4

• JWT: jose v6 (RS256 mediante JWKS)

• Protocolo: MCP 2025-06-18, HTTP Streamable

• Autenticación: Validación JWT RS256 mediante el worker de autenticación centralizado (auth.paxaver.com)

• Compilación/despliegue: Wrangler v4

• Pruebas: Vitest v2 (pool de Workers + pool de Node)

Licencia

Apache-2.0. Copyright (c) 2026 Smartoire. Consulta LICENSE.