McpAgent — API Reference

When you build MCP Servers on Cloudflare, you extend the McpAgent class ↗, from the Agents SDK, like this:

JavaScript

import { McpAgent } from "agents/mcp";
import { DurableMCP } from "@cloudflare/model-context-protocol";

export class MyMCP extends McpAgent {
  server = new McpServer({ name: "Demo", version: "1.0.0" });

  async init() {
    this.server.tool(
      "add",
      { a: z.number(), b: z.number() },
      async ({ a, b }) => ({
        content: [{ type: "text", text: String(a + b) }],
      }),
    );
  }
}

TypeScript

import { McpAgent } from "agents/mcp";
import { DurableMCP } from "@cloudflare/model-context-protocol";

export class MyMCP extends McpAgent {
  server = new McpServer({ name: "Demo", version: "1.0.0" });

  async init() {
    this.server.tool(
      "add",
      { a: z.number(), b: z.number() },
      async ({ a, b }) => ({
        content: [{ type: "text", text: String(a + b) }],
      }),
    );
  }
}

This means that each instance of your MCP server has its own durable state, backed by a Durable Object, with its own SQL database.

Your MCP server doesn't necessarily have to be an Agent. You can build MCP servers that are stateless, and just add tools to your MCP server using the @modelcontextprotocol/typescript-sdk package.

But if you want your MCP server to:

• remember previous tool calls, and responses it provided
• provide a game to the MCP client, remembering the state of the game board, previous moves, and the score
• cache the state of a previous external API call, so that subsequent tool calls can reuse it
• do anything that an Agent can do, but allow MCP clients to communicate with it

You can use the following APIs in order to do so.

State synchronization APIs

The McpAgent class makes the following subset of methods from the Agents SDK available:

• state
• initialState
• setState
• onStateUpdate
• sql

State resets after the session ends

Currently, each client session is backed by an instance of the McpAgent class. This is handled automatically for you, as shown in the getting started guide. This means that when the same client reconnects, they will start a new session, and the state will be reset.

For example, the following code implements an MCP server that remembers a counter value, and updates the counter when the add tool is called:

JavaScript

import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export class MyMCP extends McpAgent {
  server = new McpServer({
    name: "Demo",
    version: "1.0.0",
  });

  initialState = {
    counter: 1,
  };

  async init() {
    this.server.resource(`counter`, `mcp://resource/counter`, (uri) => {
      return {
        contents: [{ uri: uri.href, text: String(this.state.counter) }],
      };
    });

    this.server.tool(
      "add",
      "Add to the counter, stored in the MCP",
      { a: z.number() },
      async ({ a }) => {
        this.setState({ ...this.state, counter: this.state.counter + a });

        return {
          content: [
            {
              type: "text",
              text: String(`Added ${a}, total is now ${this.state.counter}`),
            },
          ],
        };
      },
    );
  }

  onStateUpdate(state) {
    console.log({ stateUpdate: state });
  }
}

TypeScript

import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

type State = { counter: number };

export class MyMCP extends McpAgent<Env, State, {}> {
  server = new McpServer({
    name: "Demo",
    version: "1.0.0",
  });

  initialState: State = {
    counter: 1,
  };

  async init() {
    this.server.resource(`counter`, `mcp://resource/counter`, (uri) => {
      return {
        contents: [{ uri: uri.href, text: String(this.state.counter) }],
      };
    });

    this.server.tool(
      "add",
      "Add to the counter, stored in the MCP",
      { a: z.number() },
      async ({ a }) => {
        this.setState({ ...this.state, counter: this.state.counter + a });

        return {
          content: [
            {
              type: "text",
              text: String(`Added ${a}, total is now ${this.state.counter}`),
            },
          ],
        };
      },
    );
  }

  onStateUpdate(state: State) {
    console.log({ stateUpdate: state });
  }
}

Not yet supported APIs

The following APIs from the Agents SDK are not yet available on McpAgent:

• WebSocket APIs (onMessage, onError, onClose, onConnect)
• Scheduling APIs this.schedule