NexWave MCP

NexWave MCP is a small, self-hosted gateway that lets users connect a NexWave or ERPNext site to an MCP client such as Claude or ChatGPT.

The gateway runs on Cloudflare Workers. It uses:

• Frappe's standard OAuth 2 authorization code flow for user sign-in

• Cloudflare's open-source OAuth Provider library for MCP client authorization

• D1 for the site registry and audit events

• KV for short-lived OAuth state, grants, and MCP tokens

• the current stateless MCP handler from the Cloudflare Agents SDK

It does not require a custom Frappe app. It does not use frappe_assistant_core.

Live POC

• Setup page: https://nexwave-mcp.hello-d72.workers.dev/admin

• MCP endpoint: https://nexwave-mcp.hello-d72.workers.dev/mcp

• Connected test site: configured privately in the hosted setup page

The setup page needs the ADMIN_TOKEN Worker secret. A local recovery copy is in the ignored .prod.vars file for this POC. Move it to the team password manager before other people operate the service.

Related MCP server: ERPNext MCP Server

Connect from Codex

Add the hosted MCP server and complete the browser sign-in:

codex mcp add nexwave --url https://nexwave-mcp.hello-d72.workers.dev/mcp
codex mcp login nexwave

Check the saved connection:

codex mcp get nexwave

Codex CLI and the Codex desktop app use the same MCP configuration.

POC scope

The current tools are read-only:

• get_current_user

• list_companies

• list_customers

• list_items

• list_sales_orders

• get_document for an allowlist of common sales and purchase records

Frappe applies the signed-in user's normal permissions to every REST request.

Local setup

Requirements:

• Node.js 20 or newer

• a Cloudflare account for deployment

• a Frappe v15 or NexWave site

Install dependencies and create local storage:

npm install
cp .dev.vars.example .dev.vars
npm run db:local
npm run dev

Open http://localhost:8787/admin.

Create an OAuth Client in Frappe with these settings:

Copy the generated client ID and secret into the NexWave MCP setup page. For a local Frappe bench, use a site URL such as http://demo.localhost:8000.

Cloudflare deployment

Create one KV namespace and one D1 database, then replace the IDs in wrangler.jsonc.

The checked-in configuration currently identifies the HighFlyer POC resources. Replace the account and resource IDs before deploying a fork to another Cloudflare account.

Set two Worker secrets. Do not store these values in source control:

openssl rand -base64 32 | wrangler secret put ADMIN_TOKEN
openssl rand -base64 32 | wrangler secret put CONFIG_ENCRYPTION_KEY

Apply the database migration and deploy:

npm run db:remote
npm run deploy

For a hosted Worker at https://nexwave-mcp.example.workers.dev, set the Frappe OAuth redirect URI to:

https://nexwave-mcp.example.workers.dev/oauth/frappe/callback

Then register the site at /admin. The MCP server URL is:

https://nexwave-mcp.example.workers.dev/mcp

MCP clients can use OAuth discovery and dynamic client registration. The Worker shows a consent page, sends the user to the selected NexWave site, and then returns control to the MCP client.

Security notes

• Site OAuth client secrets are encrypted with AES-256-GCM before D1 storage.

• Upstream tokens and the properties needed to refresh them are encrypted by the OAuth Provider library in KV.

• OAuth approval state expires after ten minutes and is bound to the same browser with an HTTP-only cookie.

• Frappe sign-in uses PKCE S256 as well as the confidential client secret.

• The admin API needs a separate bearer token.

• Site URLs must use HTTPS. HTTP is accepted only for local development hosts.

• The MCP tools do not accept arbitrary Frappe methods or URLs.

This POC stores an audit event for successful and failed sign-ins. It does not yet provide a full audit viewer, write tools, per-tool scope controls, or managed secret rotation.

Checks

npm run check
npm test
wrangler deploy --dry-run