Example request: signing outbound requests from a Cloudflare Agent (MCP client transport.fetch)

[joeblew999]

Type: documentation / example request
Area: examples/ (signing side)

Summary

The repo has good coverage of verifying web-bot-auth on the edge (examples/verification-workers, examples/caddy-plugin) and signing from a browser (examples/browser-extension) or a hardcoded Rust request (examples/rust). What’s missing is the case that’s becoming common: a Cloudflare Agent signing its own outbound HTTP requests so they can be verified by an origin the operator controls (e.g. a self-hosted backend behind Caddy/the existing caddy-plugin).

This is non-obvious enough to be worth an example, for two reasons specific to the Agents SDK:

1. Durable Object outbound fetch isn’t interceptable. Cloudflare Agents run on Durable Objects, and outbound fetch() from a DO is not intercepted by Outbound Workers, proxies, or mTLS bindings (see Outbound Workers and Durable Objects workers-sdk#13946). So there is no transparent layer to attach a signature — it has to be signed inline, at the point the request leaves the agent.
2. The correct injection point is the MCP client transport. When the agent reaches the origin via its built-in MCP client (this.mcp), the developer never holds the Request object directly, so signatureHeaders(request, …) can’t be called at a call site. The clean hook is the transport’s custom fetch.

The pattern (verified against types, not yet a built example)

agents (MCPTransportOptions) forwards to the MCP TypeScript SDK’s StreamableHTTPClientTransportOptions, which exposes:

/** Custom fetch implementation used for all network requests. */
fetch?: FetchLike;   // @modelcontextprotocol/sdk/shared/transport

So a signing wrapper can be passed straight through:

import { signatureHeaders } from "web-bot-auth";
import { signerFromJWK } from "web-bot-auth/crypto";
import type { FetchLike } from "@modelcontextprotocol/sdk/shared/transport.js";

function makeSigningFetch(jwk: JsonWebKey): FetchLike {
  return async (url, init = {}) => {
    const req = new Request(url, init);
    const signer = await signerFromJWK(jwk);
    const now = new Date();
    const sig = await signatureHeaders(req, signer, {
      created: now,
      expires: new Date(now.getTime() + 60_000),
    });
    const headers = new Headers(init.headers);
    for (const [k, v] of Object.entries(sig)) headers.set(k, v as string);
    return fetch(url, { ...init, headers });
  };
}

// inside the Agent
await this.mcp.connect("https://origin.example.com/mcp", {
  transport: { fetch: makeSigningFetch(JSON.parse(this.env.SIGNING_JWK)) },
});

The same makeSigningFetch works for a hand-written tool that calls fetch directly, not just the MCP path.

Why it’s useful in the repo

• It closes the loop with the existing verify-side examples: examples/caddy-plugin / examples/verification-workers show the origin verifying; this would show a Cloudflare-native client producing the signatures they verify.
• The DO-outbound and MCP-transport details are easy to get wrong and aren’t discoverable from the current examples.
• It demonstrates web-bot-auth for the agent-to-self-hosted-origin topology (the operator owns both ends, so the directory is just their own public key), which is distinct from the public-crawler framing.

Proposal

Add examples/cloudflare-agents-signing/ (or a docs section) containing:

• A minimal Agent that signs outbound calls via transport.fetch.
• Key generation + how the public JWK maps to a /.well-known/http-message-signatures-directory consumed by the caddy-plugin example.
• A note on the DO-outbound-interception constraint and why signing is inline.

Caveats / open questions

• I’ve verified the transport.fetch hook against agents@0.14.1 and @modelcontextprotocol/sdk@1.29.0 types, but have not built/run the end-to-end example, so the streamable-http vs SSE auto-probe path and the exact covered-component set should be exercised against the live test directory before this is published.
• If maintainers feel the signing side is already represented by browser-extension, the differentiator here is purely the Agents-SDK / MCP-transport specifics — happy to scope it down to a docs snippet rather than a full example if preferred.

Happy to contribute the PR.

[AkshatM]

It sounds more like you need examples for how to generate and attach a request signature to the fetch() API, which, you're right, we do lack.

I disagree Cloudflare Agents specifically needs to be represented in this repository, that we need an example for how to do it to an origin you control, or that we need something for MCP - that is far too specific. Creating request headers is not a unique feature to these domains. It could be argued CF Agents is a "quickstart tool" like the Caddy plugin and doing this would help people setup sooner, but anything using fetch() (like DOs) can just use the TS library and a suitable crypto.subtle.importKey call to get the signer. Again, examples for fetch() will solve all that.

If you can contribute a PR for a Worker signing an outbound request using signatureHeaders (and you can mostly crib the implementation by expanding the functions in this test and using a crypto.subtle.generateKey call if needed), would be appreciated.

[AkshatM]

I don't want to dismiss the MCP connect aspect entirely, but I must confess it doesn't yet fit my brain what you're trying to accomplish or why it is relevant to web-bot-auth :)

MCP already supports its own authorization layer using OAuth. This is documented on Cloudflare as well.

What is web-bot-auth doing for you here that OAuth does not?

If you want to prove your identity with WBA when you add an MCP server to an MCP client, you can just send WBA headers in addMcpServer as custom headers, and use a WBA verifier in front of your MCP to pass the request through. This is technically possible. But, again, why? You can just get an authorization token from Cloudflare Access or something.

The example you have provided of providing a custom transport layer only makes sense to me if you want to send WBA on every request. But you have an OAuth token, so it is a little like asking to have two passwords to the same webpage. It won't add more security the way you're describing.

Please help me understand better.

[thibmeu]

Before actually commenting, I want to say that this issue looks suspiciously AI generated, and there are clear gap that makes it hard to address. I'll reply because part of it is sensible, but that's quite rude on people that you aim to review and address your issues.

Addressing the points you raise in the summary:

1. durable object fetch is not interceptable: if you control the DO, building a proxy that perform signing is straightforward
2. fetch from an agent actually refers to Cloudflare Agents sdk. This is a particular client. That feature request should be in https://github.com/cloudflare/agents, not in this repository. This echos @AkshatM comment.

The issue that I think we should meaningfully address is to have a Cloudflare worker signing example. This would be a nice complement to the browser-extension signing for instance. Is this a blocker to implementers at the moment: to be seen. I've filled #89 to that end.

As for having a client using MCP be identified uniquely with WBA, I have the same question as @AkshatM: what is the goal you are trying to address that OAuth doesn't solve?