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, top up a wallet, register for fundraising events, donate to a school, 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 (auth.paxaver.com), 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.

Related MCP server: IIITH Mess MCP

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

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 binding falls back to authenticated HTTPS against API_BASE_URL (default http://localhost:8787). For full integration testing, run the Paxaver backend worker locally and point API_BASE_URL 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.

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

Secrets must be set with wrangler secret put --env production: JWT_SECRET, OAUTH_STATE_SECRET, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, CHATGPT_VERIFY_TOKEN. See docs/deployment.md.

Tools

The server exposes 31 tools grouped into six 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).

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

Documentation

Tech stack

• Runtime: Cloudflare Workers (compatibility_date: 2026-08-01, nodejs_compat)

• Framework: Hono v4

• JWT: jose v6 (RS256 via JWKS)

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

• Auth: RS256 JWT validation via centralized auth worker (auth.paxaver.com)

• Build/deploy: Wrangler v4

• Test: Vitest v2 (Workers pool + Node pool)

License

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