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 (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.

Architecture

text

┌───────────────┐     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

Terminal

npm install @paxaver/mcp

Develop locally

bash

# 1. Install dependencies (Node >= 22)
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 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:

Environment	Worker name	Domain
`staging`	`paxaver-mcp-staging`	`mcp.paxaver.dev`
`production`	`paxaver-mcp`	`mcp.paxaver.com`

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.

Terminal

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 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).

Category	Tools
User / account	`get_user_info`
Wallet	`get_wallet_balance`, `get_wallet_status`
Orders & menu	`order_lunch`, `get_orders`, `get_daily_menu`, `get_daily_orders`, `get_monthly_orders`, `create_draft_order`, `finalize_order`, `cancel_order`
Events	`get_upcoming_events`, `create_event`, `update_event`, `cancel_event`, `register_event`, `sign_up_to_volunteer`
Admin / restaurant	`list_school_restaurants`, `create_restaurant`, `list_menu_items`, `create_menu_item`, `update_menu_item`, `set_menu_item_price`, `delete_menu_item`, `set_daily_menu`

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

Document	Topic
docs/architecture.md	System architecture, service binding boundary, regional isolation
docs/authentication.md	JWT validation, JWKS, auth worker delegation, token format
docs/authorization.md	Capability policy table, role gating, defense-in-depth
docs/tools.md	Full tool reference with input schemas and classifications
docs/deployment.md	Wrangler config, environments, secrets, custom domains
docs/security.md	Security model, CORS, CSRF, error sanitization, headers
docs/compatibility.md	MCP protocol version, transports, supported AI clients
docs/migration.md	Migration from the legacy `mcp-server/` in the private monorepo
CHANGELOG.md	Release history
SECURITY.md	Vulnerability reporting policy
CONTRIBUTING.md	Development setup and contribution process

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)

Paxaver MCP README