--- title: Self Hosted Cloudflare description: "Run Executor as a single Cloudflare Worker in your own account, with Cloudflare Access for auth and D1 for storage." --- Executor runs as a single Cloudflare Worker. Authentication is handled entirely by [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/) (there is no separate app login), storage is [D1](https://developers.cloudflare.com/d1/), tool code runs in QuickJS inside the Worker, and the web console, API, and MCP endpoint are all served from that one Worker. It is single-tenant: every Access-verified user belongs to the one configured org, and you manage members and credentials in Cloudflare Access rather than in the app. ## Prerequisites - A Cloudflare account with Workers and Zero Trust (Access) enabled. - The [Executor repo](https://github.com/RhysSullivan/executor) checked out, with dependencies installed (`bun install`). ## Deploy From `apps/host-cloudflare`: ```bash bunx wrangler login bun run deploy:setup ``` `deploy:setup` is idempotent: it creates or reuses the `executor` D1 database, writes its id into `wrangler.jsonc`, generates and uploads the `EXECUTOR_SECRET_KEY` secret, and deploys the Worker. It then prints the one remaining manual step. ## Put it behind Cloudflare Access Until the Worker is behind an Access application, every API and MCP route returns `401`. In the Zero Trust dashboard: 1. Go to **Access → Applications → Add an application → Self-hosted**. 2. Set the application domain to `executor-cloudflare..workers.dev`. 3. Add an Access policy (for example, emails ending in `@yourcompany.com`). 4. Copy the application **Audience (AUD)** tag, then redeploy with your Access settings: ```bash bunx wrangler deploy \ --var ACCESS_AUD: \ --var ACCESS_TEAM_DOMAIN:.cloudflareaccess.com ``` You can also set `ACCESS_AUD` and `ACCESS_TEAM_DOMAIN` in `wrangler.jsonc` and redeploy. Now visiting the Worker prompts a Cloudflare Access login, and the Worker validates the issued JWT on every request. ## Connect an agent The Worker serves a streamable-HTTP MCP endpoint at `/mcp`, gated by Access like the rest of the surfaces. Point your client at `https://executor-cloudflare..workers.dev/mcp`. Because Access sits in front of the Worker, an MCP client that reaches `/mcp` without a valid Access credential is served Cloudflare's HTML login page instead of the endpoint. The streamable-HTTP client rejects that with `Streamable HTTP error: Unexpected content type: text/html`: that is the Access login page, not a Worker response. A browser passes Access via an interactive login, but an MCP client cannot follow that redirect, so it has to authenticate another way. Choose the path that matches your client. ### For interactive clients: Managed OAuth (recommended) Cloudflare Access can run the MCP OAuth flow on the Worker's behalf, so a client like Claude authenticates with a normal login popup and no manual headers. The Worker keeps doing exactly what it already does (validate the `Cf-Access-Jwt-Assertion`); no code or redeploy is needed. 1. Open the self-hosted Access application gating the Worker (the one from the previous section). 2. Enable **Managed OAuth** in the application's settings (the option that lets non-browser clients authenticate over OAuth). With it on, Access answers an unauthenticated `/mcp` request with an OAuth `401` challenge and serves the OAuth discovery, authorize, and token endpoints itself, instead of the HTML login page. Keep the Access application scoped to the whole Worker hostname (as set in the previous section), not a single path like `/mcp`: the discovery probes clients send to `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource` then land on Access too, which answers them rather than letting them fall through to the Worker's SPA fallback (which the Worker itself does not serve, so a path-scoped application would return HTML or `404` there). 3. Point your client at the `/mcp` URL with no extra configuration. On connect it discovers the OAuth endpoints, opens a browser popup to log in through Access, and Cloudflare injects the validated JWT into every subsequent request. ```bash npx add-mcp https://executor-cloudflare..workers.dev/mcp \ --transport http --name executor ``` This is the same flow Cloudflare documents in [Secure MCP servers with Access](https://developers.cloudflare.com/cloudflare-one/access-controls/ai-controls/secure-mcp-servers/). If a client still won't start the OAuth flow after you enable Managed OAuth (it classifies `/mcp` as not an MCP endpoint, or you still hit the `Unexpected content type: text/html` error), its probe isn't consuming Access's `401` challenge. Fall back to the service-token path below: it authenticates with request headers and needs no client-side OAuth discovery, so it works regardless of how the client handles the challenge. ### For headless clients: service token When no human is present to complete the OAuth popup (CI, a background agent), authenticate machine-to-machine with an Access service token instead. 1. In the Zero Trust dashboard, go to **Access → Service Auth → Service Tokens → Create Service Token**. Copy the **Client ID** and **Client Secret** (the secret is shown once). 2. On the Access application gating the Worker, add a policy with **Action: Service Auth** that includes that service token (Include → Service Token → your token). The `Service Auth` action lets the token through without an interactive IdP login. 3. Configure your MCP client to send the token on every request as the `CF-Access-Client-Id` and `CF-Access-Client-Secret` headers. Access exchanges them for the `Cf-Access-Jwt-Assertion` JWT (carrying the token's `common_name`) that the Worker validates, exactly like a human login. With [`add-mcp`](https://www.npmjs.com/package/add-mcp), which writes the config for whichever agents it detects: ```bash npx add-mcp https://executor-cloudflare..workers.dev/mcp \ --transport http --name executor \ --header "CF-Access-Client-Id: .access" \ --header "CF-Access-Client-Secret: " ``` For an `mcpServers` config block: ```json { "executor": { "type": "http", "url": "https://executor-cloudflare..workers.dev/mcp", "headers": { "CF-Access-Client-Id": ".access", "CF-Access-Client-Secret": "" } } } ``` Once connected, see [MCP Proxy](/mcp-proxy) for how the endpoint exposes your integrations.