Firefox Relay MCP Gateway

Stateless Streamable HTTP MCP gateway for Firefox Relay, built for Cloudflare Workers.

Features

• Stateless remote MCP server for Firefox Relay

• OAuth Authorization Code + PKCE (S256) for MCP clients

• Encrypted Firefox Relay API key envelope inside signed JWT artifacts

• Streamable HTTP MCP endpoint at /mcp

• Random mask list/create/update/disable operations

• Optional custom-domain mask listing when the Relay account supports it

Requirements

• Node.js 20+

• npm

• Cloudflare account with Wrangler authentication

• A Firefox Relay account with an API key

Connector values

MCP Server URL: https://your-worker.example.com/mcp
Authorization server base URL: https://your-worker.example.com
Resource: https://your-worker.example.com/mcp

What it does

• Exposes MCP Streamable HTTP at /mcp

• Acts as its own OAuth Authorization Server for remote MCP clients

• Collects a user-provided Firefox Relay API key during OAuth consent

• Encrypts that API key into signed JWT artifacts and does not store it in a database

• Lets MCP clients list, create, update, and disable Firefox Relay masks

Firefox Relay API key

Users can find the Firefox Relay API key in Firefox Relay under profile icon → Settings.

Supported MCP tools

• relay_list_random_masks

• relay_create_random_mask

• relay_update_random_mask

• relay_disable_random_mask

• relay_list_domain_masks

Install

npm install

Quick start

1. Install dependencies.

2. Set Worker secrets.

3. Configure non-secret vars in wrangler.toml or via deploy-time environment overrides.

4. Run npm run dev for local testing.

5. Run npm test and npm run typecheck.

6. Deploy with npm run deploy.

Configure non-secret Worker vars

Update wrangler.toml or your deployment environment with:

• OAUTH_ISSUER

• MCP_RESOURCE

• MCP_AUDIENCE

• OAUTH_REDIRECT_HTTPS_HOSTS

• RELAY_DEFAULT_BASE_URL

• ACCESS_TOKEN_DEFAULT_TTL_DAYS

• ACCESS_TOKEN_MAX_TTL_DAYS

• AUTH_CODE_TTL_SECONDS

For public release, wrangler.toml intentionally uses placeholder URLs. Set these to your real deployment values before production deploys:

• OAUTH_ISSUER=https://your-worker.example.com

• MCP_RESOURCE=https://your-worker.example.com/mcp

• MCP_AUDIENCE=https://your-worker.example.com/mcp

Set Worker secrets

Generate and pipe each secret directly into Wrangler:

openssl rand -base64 48 | tr -d '\n' | wrangler secret put OAUTH_JWT_SIGNING_KEY_B64
openssl rand -base64 32 | tr -d '\n' | wrangler secret put UPSTREAM_CONFIG_ENC_KEY_B64
openssl rand -base64 48 | tr -d '\n' | wrangler secret put CSRF_SIGNING_KEY_B64

Deploy sequence

If you do not know the final public Worker URL yet, use this order:

1. Bootstrap deploy once to get the real workers.dev URL.

2. Set the three Worker secrets.

3. Redeploy with real OAUTH_ISSUER, MCP_RESOURCE, and MCP_AUDIENCE values.

Run locally

npm run dev

Validate

npm test
npm run typecheck

Deploy

npm run deploy

Public connector values

After deployment, configure remote MCP clients with:

MCP Server URL: https://your-worker.example.com/mcp
Authorization server base URL: https://your-worker.example.com
Resource: https://your-worker.example.com/mcp

OAuth and stateless design summary

• /register issues deterministic public client_id values for allowlisted redirect URIs

• /authorize validates PKCE S256, renders consent, validates the Firefox Relay API key, and issues a short-lived signed auth-code JWT

• /token exchanges the auth code for bearer access and refresh JWTs

• JWTs carry an AES-GCM encrypted Relay config envelope; plaintext credentials are never persisted server-side

• /mcp verifies the access token, decrypts the Relay config, creates a fresh Worker-safe MCP server and transport, and serves the request

Stateless caveats

• Auth codes are not one-time-use across all isolates because no server-side state is stored

• Refresh tokens cannot be globally revoked without a stateful primitive

• Strict global rate limiting requires Durable Objects, KV, or Cloudflare-managed rate limiting

Manual smoke test notes

1. Register a client with an allowlisted redirect URI.

2. Complete /authorize with a Firefox Relay API key.

3. Exchange the returned code at /token.

4. Call /mcp with the returned bearer token.

5. Confirm tools list and successful mask operations.

Privacy and security notes

• The Worker encrypts the Firefox Relay API key into MCP JWT artifacts and does not store it in a database.

• The Worker is designed to avoid logging API keys, bearer tokens, decrypted envelopes, cookies, or CSRF tokens.

• Upstream Relay errors are sanitized before they are returned to MCP clients.

Known limitations

• Auth codes are not globally one-time-use without stateful storage.

• Refresh tokens cannot be globally revoked without stateful storage.

• Strict global rate limiting requires Durable Objects, KV, or a Cloudflare-managed alternative.

• Domain-mask behavior depends on account capabilities and may require Relay premium/custom-domain support.

Project docs

• docs/PRODUCT_REQUIREMENTS.md

• docs/IMPLEMENTATION_PLAN.md

• docs/PROJECT_STATE.md

• docs/DECISIONS.md

• docs/RUNBOOK.md

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT