Skip to content
Cloudflare Docs

McpClient — API reference

Your Agent can connect to external Model Context Protocol (MCP) ↗ servers to access tools, resources, and prompts. The Agent class provides three methods to manage MCP connections:

JavaScript
import { Agent } from "agents";


export class MyAgent extends Agent {
  async onRequest(request) {
    const url = new URL(request.url);


    if (url.pathname === "/connect" && request.method === "POST") {
      const { id, authUrl } = await this.addMcpServer(
        "Weather API",
        "https://weather-mcp.example.com/mcp",
      );


      if (authUrl) {
        return new Response(JSON.stringify({ authUrl }), {
          headers: { "Content-Type": "application/json" },
        });
      }


      return new Response(`Connected: ${id}`, { status: 200 });
    }
  }
}

Connections persist in the Agent's SQL storage, and when an Agent connects to an MCP server, all tools from that server become available automatically.

Agent MCP Client Methods

addMcpServer()

Add a connection to an MCP server and make its tools available to your Agent.

TypeScript
async addMcpServer(
  serverName: string,
  url: string,
  callbackHost?: string,
  agentsPrefix?: string,
  options?: {
    client?: ConstructorParameters<typeof Client>[1];
    transport?: {
      headers?: HeadersInit;
      type?: "sse" | "streamable-http" | "auto";
    };
  }
): Promise<{ id: string; authUrl: string | undefined }>

Parameters

  • serverName (string, required) — Display name for the MCP server
  • url (string, required) — URL of the MCP server endpoint
  • callbackHost (string, optional) — Host for OAuth callback URL. If omitted, automatically derived from the incoming request
  • agentsPrefix (string, optional) — URL prefix for OAuth callback path. Default: "agents"
  • options (object, optional) — Connection configuration:
    • client — MCP client configuration options (passed to @modelcontextprotocol/sdk Client constructor)
    • transport — Transport layer configuration:
      • headers — Custom HTTP headers for authentication
      • type — Transport type: "sse", "streamable-http", or "auto" (tries streamable-http first, falls back to sse)

Returns

A Promise that resolves to an object containing:

  • id (string) — Unique identifier for this server connection
  • authUrl (string | undefined) — OAuth authorization URL if authentication is required, otherwise undefined

Example

JavaScript
export class MyAgent extends Agent {
  async onRequest(request) {
    const { id, authUrl } = await this.addMcpServer(
      "Weather API",
      "https://weather-mcp.example.com/mcp",
    );


    if (authUrl) {
      // User needs to complete OAuth flow
      return new Response(JSON.stringify({ serverId: id, authUrl }), {
        headers: { "Content-Type": "application/json" },
      });
    }


    return new Response("Connected", { status: 200 });
  }
}

If the MCP server requires OAuth authentication, authUrl will be returned for user authentication. Connections persist across requests and the Agent will automatically reconnect if the connection is lost.

Related:

removeMcpServer()

Disconnect from an MCP server and clean up its resources.

TypeScript
async removeMcpServer(id: string): Promise<void>

Parameters

  • id (string, required) — Server connection ID returned from addMcpServer()

Returns

A Promise that resolves when disconnection is complete.

Example

JavaScript
export class MyAgent extends Agent {
  async onRequest(request) {
    const url = new URL(request.url);


    if (url.pathname === "/disconnect" && request.method === "POST") {
      const { serverId } = await request.json();
      await this.removeMcpServer(serverId);


      return new Response("Disconnected", { status: 200 });
    }
  }
}

Disconnects from the MCP server, removes all related resources, and deletes the server record from storage.

getMcpServers()

Get the current state of all MCP server connections.

TypeScript
getMcpServers(): MCPServersState

Parameters

None.

Returns

An MCPServersState object containing:

TypeScript
{
  servers: Record<
    string,
    {
      name: string;
      server_url: string;
      auth_url: string | null;
      state:
        | "authenticating"
        | "connecting"
        | "ready"
        | "discovering"
        | "failed";
      capabilities: ServerCapabilities | null;
      instructions: string | null;
    }
  >;
  tools: Array<Tool & { serverId: string }>;
  prompts: Array<Prompt & { serverId: string }>;
  resources: Array<Resource & { serverId: string }>;
}

Example

JavaScript
export class MyAgent extends Agent {
  async onRequest(request) {
    const url = new URL(request.url);


    if (url.pathname === "/mcp-state") {
      const mcpState = this.getMcpServers();


      return new Response(JSON.stringify(mcpState, null, 2), {
        headers: { "Content-Type": "application/json" },
      });
    }
  }
}

The state field can be: authenticating, connecting, ready, discovering, or failed. Use this method to monitor connection status, list available tools, or build UI for connected servers.

OAuth Configuration

Customize OAuth callback behavior using this.mcp.configureOAuthCallback():

JavaScript
export class MyAgent extends Agent {
  onStart() {
    this.mcp.configureOAuthCallback({
      successRedirect: "/connected",
      errorRedirect: "/auth-failed",
    });
  }
}

You can also provide a customHandler function for full control over the callback response. Refer to the OAuth handling guide for details.

Error Handling

Use error detection utilities to handle connection errors:

JavaScript
import { isUnauthorized, isTransportNotImplemented } from "agents/mcp";


export class MyAgent extends Agent {
  async onRequest(request) {
    try {
      await this.addMcpServer("Server", "https://mcp.example.com/mcp");
    } catch (error) {
      if (isUnauthorized(error)) {
        return new Response("Authentication required", { status: 401 });
      } else if (isTransportNotImplemented(error)) {
        return new Response("Transport not supported", { status: 400 });
      }
      throw error;
    }
  }
}

Next Steps