← Back to directory
C

Cloudflare Agents

Official
Official Cloudflare SDK for building persistent, stateful AI agents on Durable Objects, with optional MCP server/client support as one of many built-in features.
GitHub source repository ↗
★ 5.4k Stars Category · Dev Tools Very popular
56FMRS · C
Reliability
7/20
Security and permissions
11/20
Maintenance
15/20
Documentation
14/20
Setup experience
9/20

cloudflare/agents is a comprehensive, officially maintained agent SDK from Cloudflare; MCP server/client support is one feature among many rather than the repo's sole purpose. Documentation and examples are extensive, but the project does not accept external PRs and has no standalone MCP install configuration separate from writing code.

Read the FMRS scoring method →

cloudflare/agents is Cloudflare's officially maintained TypeScript SDK for building persistent, stateful AI agents on top of Durable Objects — each agent gets its own state, storage, and lifecycle, hibernating when idle and waking on demand. It is not itself a single MCP server with a fixed tool list; rather it's an application framework that lets developers make their own Agent act as an MCP server (exposing it to MCP clients) or as an MCP client (connecting to other MCP servers), over HTTP, SSE, RPC, and with elicitation support. Beyond MCP, the SDK bundles synced persistent state, type-safe callable methods (RPC via @callable()), sub-agent composition, scheduling, WebSockets, AI chat with resumable streaming, WebMCP, durable workflows with human-in-the-loop approval, email send/receive, a voice pipeline, browser-side agents, Code Mode (LLMs write executable code instead of one tool call at a time), sandboxed code execution, and x402 pay-per-call support. The repo is a pnpm/Nx monorepo containing the core agents package plus companion packages (ai-chat, think, codemode, shell, voice, worker-bundler, hono-agents) and 30+ standalone examples, several of them specifically demonstrating MCP usage (mcp, mcp-client, mcp-server, mcp-worker, webmcp). The project does not accept external pull requests but welcomes bug reports and discussion via GitHub Issues/Discussions.

Tools

The tool list has not been reviewed yet.

Setup

Run npm install agents in an existing Cloudflare Workers project, or scaffold a new one with npm create cloudflare@latest -- --template cloudflare/agents-starter. Declare your Agent class as a Durable Object and configure the matching durable_objects binding plus a SQLite migration (new_sqlite_classes) in wrangler.jsonc, along with an appropriate compatibility_date and the nodejs_compat flag. To expose an Agent as an MCP server or connect it as an MCP client, follow the patterns in the repo's examples/mcp* directories — there is no separate one-step MCP installer or client config file provided.

Fit and risk

Best for

  • TypeScript developers building stateful AI agents on the Cloudflare Workers/Durable Objects platform
  • Teams that want to expose their own agent capabilities as an MCP server
  • Builders needing an integrated stack of scheduling, WebSockets, voice, and workflows for agentic apps

Not for

  • Users looking for a turnkey MCP server with a fixed tool list to drop straight into a Claude Desktop config
  • Teams not deploying to Cloudflare Workers/Durable Objects
  • External contributors hoping to land code via pull request (the repo currently does not accept external PRs)

Required permissions

  • A Cloudflare account with SQLite-backed Durable Objects enabled
  • Workers deployment and binding configuration permissions
  • Additional credentials/bindings depending on features used (e.g. AI model calls, email service)

Risks and side effects

  • MCP server/client behavior is implemented by the developer, so missing authorization checks could expose agent state or callable methods
  • Code Mode and sandboxed execution run LLM-generated code — misconfigured isolation could introduce execution risk
  • Incorrect Durable Object bindings or SQLite migration tags can cause state loss or failed migrations
  • The repo does not accept external PRs, so community-reported issues depend entirely on Cloudflare's own fix timeline

Troubleshooting

  1. Verify the `durable_objects` binding name in `wrangler.jsonc` matches the class name listed under the migration's `new_sqlite_classes`
  2. Check that `compatibility_date` and the `nodejs_compat` flag are set as shown in the README example
  3. Building the repo itself requires Node 24+ and pnpm; run `pnpm run check` to catch type/lint/test issues
  4. Reference the `examples/mcp*` and `examples/webmcp` directories for working MCP integration patterns
  5. Consult the `docs/` and `design/` directories for architecture details and design rationale

Use cases

Spinning up one persistent, hibernating agent instance per user, session, or game room
Wrapping custom agent logic and exposing it as an MCP server
Having an Agent act as an MCP client to call external tools and other MCP servers
Building real-time chat/collaboration frontends (React or vanilla JS) with synced state and callable methods
Implementing durable, multi-step workflows that require human-in-the-loop approval

Supported clients

Supported clients have not been confirmed yet.