[mattzcarey]

Stacked on #297. /mcp?forge=true serves direct tools whose code forge generates from openapi.forge.json, as an opt-in preview. ?codemode=false and Code Mode are unchanged.

The generator is a new --target mcp in forge, on the long-lived forge-mcp branch of mattzcarey/forge. It writes TypeScript for @modelcontextprotocol/server, which is committed here in src/generated/forge-mcp/. A workflow regenerates it every six hours and opens a PR when it changes, and merging that PR deploys. The generated tools run in their own Worker, so the main Worker's startup is unchanged.

flowchart LR
  release["Forge release<br/>openapi.forge.json"] --> action["forge-tools.yml (every 6h)<br/>forge --target mcp"]
  pin["forge.json<br/>pinned forge commit"] --> action
  action -->|code changed| pr["bot/forge-tools PR<br/>(agent-think)"]
  pr -->|merge| deploy["Workers Builds"]
  client["MCP client<br/>/mcp?forge=true"] --> main["cloudflare-api-mcp<br/>auth, token, refusals"]
  main -->|"FORGE_TOOLS RPC<br/>list() · plan()"| svc["cloudflare-api-mcp-forge-tools<br/>generated tools, no secrets"]
  main -->|"planned request + token"| api["api.cloudflare.com"]

Loading

Each generated tool is plain code:

{
  name: "d1_list",
  inputSchema: { type: "object", properties: { account_id: …, name: …, page: … }, … },
  annotations: { readOnlyHint: true, … },
  method: "GET",
  path: "/accounts/{account_id}/d1/database",
  extensions: { "x-api-token-group": ["D1 Read", "D1 Write"] },
  request: (args) => ({
    path: `/accounts/${pathParam(args, "account_id")}/d1/database`,
    query: [["name", args["name"], true], ["page", args["page"], true], …],
  }),
},

• Generated code (src/generated/forge-mcp/, never edited by hand, skipped by oxfmt and oxlint):

  • each group's tools.ts
  • schemas.ts files with model schemas shared by every tool that uses them
  • index.ts exporting every tool
  • a README.md listing the 27 methods without a tool and why
  • forge's small runtime in _/

• Forge tools service (src/forge-tools/worker.ts, wrangler.forge-tools.jsonc): a separate Worker that holds the generated tools and applies the Cloudflare rules (optional account_id, the accounts/zones enum on merged paths). It has no secrets, no outbound requests and no route. Its two RPC methods:

  • list(): the tools as tools/list sends them
  • plan(name, args, { baseUrl, sessionAccountId }): the request a call makes (src/forge-tools/plan.ts)

• Main Worker (src/tools/forge-tools.ts): serves docs and whoami itself. It sends each planned request with the session's token, which never leaves it, and explains refusals and steps up scopes like the existing direct tools. It parses +json responses as JSON, as fix: preserve successful JSON responses without a REST envelope #251 does for execute.

• Why a second Worker: workerd compiles every module a Worker uploads at startup, so bundling the tools into the main Worker cost every isolate, Code Mode included. Measured with wrangler check startup, in startup CPU:

  	upload (gzip)	startup
  main Worker, before this PR	2.0 MB (0.39 MB)	~41 ms
  tools bundled, static import	10.7 MB (1.17 MB)	~98 ms
  tools bundled, lazy import	12.2 MB (1.25 MB)	~68 ms
  tools as a separate uploaded module	2.0 + 8.6 MB	~78 ms
  main Worker, this PR	2.0 MB (0.38 MB)	~40 ms
  forge tools service (only ?forge=true)	8.5 MB (0.76 MB)	~53 ms

  The RPC hop adds about 20–40 ms to tools/list.

• CI (.github/workflows/forge-tools.yml): builds forge at the commit in forge.json and regenerates. When the code changes, it runs the type check and tests, then force-pushes bot/forge-tools and opens or updates the PR.

  • With AGENT_THINK_APP_ID and AGENT_THINK_PRIVATE_KEY set, it acts as the agent-think GitHub App (team-apps), so CI runs on the PR as usual.
  • Without them it falls back to GITHUB_TOKEN, whose PRs don't start CI.

  Bump forge.json to change the generator.

This drops the vendored forge-mcp tarball, the @cloudflare/forge and jco dev dependencies, the WebAssembly plugin and the R2 artifact. The lockfile is unchanged from #297.

Important

The main Worker binds to the service, and a Worker whose service binding target doesn't exist fails to deploy. Deploy cloudflare-api-mcp-forge-tools (and -staging) before this merges: npm run deploy:forge-tools:prod and npm run deploy:forge-tools. Workers Builds also needs a second build for the new Worker, with deploy command npx wrangler deploy -c wrangler.forge-tools.jsonc --env production.

Note

Tool names are forge's, matching the cf CLI (zones_list, d1_list, zero_trust_access_applications_list). That's why this is a separate opt-in rather than a change to ?codemode=false.

Tests ran, and they call the real service over its binding: Vitest builds it and runs it as an auxiliary Worker. One full run had 3 failures I couldn't reproduce in the next five runs, so watch CI for a flaky test.

I also ran npm run dev (both Workers) with my OAuth token and the MCP TS client:

• tools/list returned 3,055 tools in 128–152 ms
• accounts_list, zones_list, d1_list and the merged Access tool returned live data
• d1_list without account_id asked which account to use