esa MCP Worker

A vendor-neutral Remote MCP server for esa on Cloudflare Workers. It exposes read, write, context, audit, admin, optional transcription, and optional GitHub implementation tools to MCP clients.

What it provides

• /mcp-fast: a small read-only catalog for normal context lookup

• /mcp: the complete catalog for writes, maintenance, transcription, and GitHub sync

• OAuth with PKCE, Dynamic Client Registration, and single-use authorization codes

• bounded reads, section patches, bulk operations, caching, and concurrent requests

• an admin page for access, audit, connections, and context-observer management

Related MCP server: basecamp-mcp

Requirements

• Node.js 24.11 or later

• pnpm 10.11.1

• a Cloudflare account

• an esa access token

Setup

1. Install dependencies.

   pnpm install --frozen-lockfile
   pnpm verify

2. Create a Workers KV namespace and a D1 database in Cloudflare. Replace the two placeholder IDs in wrangler.jsonc with the IDs from your account.

   pnpm exec wrangler kv namespace create MCP_CONFIG
   pnpm exec wrangler d1 create esa-mcp-worker-oauth-codes
   pnpm exec wrangler d1 migrations apply esa-mcp-worker-oauth-codes --remote

3. In Cloudflare Workers & Pages > Settings > Variables and Secrets, add the values shown in .dev.vars.example. At minimum, configure:

   ESA_DEFAULT_TEAM
   ESA_CONTEXT_ENTRY_POST_NUMBER
   MCP_ADMIN_USERNAME
   MCP_OAUTH_ALLOWED_REDIRECT_HOSTS
   MCP_BEARER_TOKEN             secret
   MCP_OAUTH_PASSCODE           secret
   MCP_ADMIN_PASSWORD           secret

   Use long random values for all three secrets. GitHub implementation sync is optional. The OpenAI API key for transcription is entered during OAuth and is not a deployment variable.

4. Deploy.

   pnpm run deploy

For Cloudflare Workers Builds, use:

Build command:                 pnpm verify
Deploy command:                pnpm run deploy
Non-production deploy command: pnpm run deploy:preview

Connect an MCP client

Use one endpoint at a time to keep the tool catalog small:

Read-only: https://YOUR-WORKER.workers.dev/mcp-fast
Full:      https://YOUR-WORKER.workers.dev/mcp
Admin:     https://YOUR-WORKER.workers.dev/admin

Prefer Dynamic Client Registration. For a manual OAuth client, use token endpoint authentication method none, PKCE S256, and these endpoints:

Authorization: https://YOUR-WORKER.workers.dev/oauth/authorize
Token:         https://YOUR-WORKER.workers.dev/oauth/token
Registration:  https://YOUR-WORKER.workers.dev/oauth/register

Scopes are esa:read for /mcp-fast and esa:read esa:write for /mcp. Reconnect a client after the public tool catalog changes.

Security

Do not commit .dev.vars, .env, real Cloudflare resource IDs, tokens, or private keys. The Worker encrypts esa and optional OpenAI credentials into the signed OAuth access token and does not store their plaintext in KV. Write tools also require confirm_write: true.

See SECURITY.md for vulnerability reporting and docs/reference.md for tools, configuration, errors, performance, and the optional GitHub workflow.

License

MIT Copyright (c) 2026 Ierllow