Paxaver MCP Server

Paxaver MCP Server

AI-facing adapter over the Paxaver school community platform. Implements the Model Context Protocol (MCP) on Cloudflare Workers with RS256 JWT validation, capability-first authorization, and Streamable HTTP transport.

---

What this is

The Paxaver MCP server lets AI assistants (ChatGPT, Claude, Perplexity, and any MCP-compatible client) act on behalf of a Paxaver user: check a lunch menu, order lunch, register for fundraising events, volunteer, and — for school administrators — manage restaurants, menu items, events, and daily orders.

It is a thin adapter. It contains no business logic and never touches the database, Stripe, or email directly. Every action is delegated to the private Paxaver backend API over a Cloudflare service binding (same region, no public network hop). The MCP server's only responsibilities are:

• MCP protocol handling (JSON-RPC 2.0, Streamable HTTP)
• RS256 JWT validation via JWKS from the centralized Paxaver auth worker
• Per-tool capability policy and role gating
• Sanitized, user-safe error mapping

Authentication is handled by the Paxaver auth worker (paxaver.com/auth), which serves as the OAuth 2.0 / OIDC authorization server. The MCP server validates the resulting RS256 JWTs and forwards them to the backend. The MCP server itself is not an authorization server.

---

Architecture

┌───────────────┐     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   │
                                                 └──────────────────────┘

The MCP worker never binds D1, Stripe, or SES. The service binding carries a short-lived JWT (120s TTL, audience paxaver-internal) that the backend trusts as an internal call while still attributing the action to the authenticated Paxaver user. See docs/architecture.md for the full picture.

---

Quick start

Install

npm install @paxaver/mcp

Develop locally

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

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

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

The local dev server starts on http://localhost:8787. Discovery endpoints live under /.well-known/; the MCP endpoint is POST /mcp.

Note: Local development without the PAXAVER_API_* service bindings falls back to authenticated HTTPS against API_BASE_URL_CA, API_BASE_URL_US, and API_BASE_URL_MX (default http://localhost:8787). For full integration testing, run the Paxaver backend worker locally; the defaults already point at it.

---

Deployment

Two environments, each a separate Worker with its own custom domain:

The production worker serves both CA and US users through a single endpoint (mcp.paxaver.com). User region is resolved from the JWT tenant_id claim, and the worker routes to the correct regional backend via service bindings (PAXAVER_API_CA, PAXAVER_API_US). Currency is determined by the user's school, not by the MCP endpoint.

Docker

The Dockerfile runs the worker locally via wrangler dev, proxying the production backends over HTTPS:

docker build -t paxaver-mcp .
docker run -p 8787:8787 paxaver-mcp
# MCP endpoint: http://localhost:8787/mcp

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

The worker requires no secrets. See docs/deployment.md.

---

Tools

The server exposes 26 tools grouped into five categories. Visibility in tools/list is filtered by the caller's roles; every call is re-authorized before dispatch, and the backend re-checks data-level access (defense-in-depth).

Ordering is draft → review → payment: create_lunch_order_draft, adjust with update_lunch_order_draft, then pay_lunch_order_draft.

Compatibility: pre-2.5 tool names (get_menu, register_event, create_menu_item, …) still work — they resolve to the canonical tools — but are no longer advertised. order_lunch also remains callable for existing integrations. See docs/tools.md for the full legacy-name mapping.

Financial and destructive tools are labeled and require user confirmation. Full reference: docs/tools.md. Authorization policy: docs/authorization.md.

Privacy

No personal contact information (email, phone, address) is collected or returned through MCP tools. The get_my_context tool returns only the user's name, school, students, and roles. Student data is limited to IDs, names, and school slugs. Allergies, notes, birthday, and other PII are not exposed in read responses. The MCP server does not log user data.

---

Documentation

---

Tech stack

• Runtime: Cloudflare Workers (compatibility_date: 2026-09-15)
• Framework: Hono v4
• JWT: jose v6 (RS256 via JWKS)
• Protocol: MCP 2025-06-18, Streamable HTTP
• Auth: RS256 JWT validation via centralized auth worker (paxaver.com/auth)
• Build/deploy: Wrangler v4
• Test: Vitest v2 (Workers pool + Node pool)

---

License

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