MCP Client Example

Build an agent that connects to remote MCP servers, handles OAuth authentication, and aggregates tools, prompts, and resources

An Agent that acts as an MCP client - dynamically connects to remote MCP servers, handles OAuth authentication, and aggregates tools, prompts, and resources from all connected servers.

What it demonstrates

• addMcpServer / removeMcpServer - managing MCP server connections from an Agent
• onMcpUpdate - real-time state updates pushed to the React frontend via WebSocket
• OAuth popup flow - configureOAuthCallback with a custom handler that closes the popup after auth
• agentFetch - making HTTP requests to the Agent’s custom endpoints from the client

Server Implementation

src/server.ts

import { Agent, callable, routeAgentRequest } from "agents";

export class MyAgent extends Agent {
  onStart() {
    this.mcp.configureOAuthCallback({
      customHandler: (result) => {
        if (result.authSuccess) {
          return new Response("<script>window.close();</script>", {
            headers: { "content-type": "text/html" },
            status: 200
          });
        }
        const error = result.authError || "Unknown error";
        return new Response(`Authentication Failed: ${error}`, {
          headers: { "content-type": "text/plain" },
          status: 400
        });
      }
    });
  }

  @callable()
  async addServer(name: string, url: string) {
    await this.addMcpServer(name, url, {
      callbackHost: this.env.HOST
    });
  }

  @callable()
  async disconnectServer(serverId: string) {
    await this.removeMcpServer(serverId);
  }
}

export default {
  async fetch(request: Request, env: Env) {
    return (
      (await routeAgentRequest(request, env, { cors: true })) ||
      new Response("Not found", { status: 404 })
    );
  }
} satisfies ExportedHandler<Env>;

Client Implementation

The React frontend uses useAgent with onMcpUpdate to receive real-time server state:

src/client.tsx

import { useAgent } from "agents/react";
import { useState } from "react";
import type { MyAgent } from "./server";

function McpClientApp() {
  const [mcpServers, setMcpServers] = useState<McpServerInfo[]>([]);
  const [connected, setConnected] = useState(false);

  const agent = useAgent<MyAgent>({
    agent: "MyAgent",
    name: sessionId,
    onMcpUpdate: (servers) => {
      // Real-time updates when servers are added/removed/changed
      setMcpServers(servers);
    },
    onOpen: () => setConnected(true),
    onClose: () => setConnected(false)
  });

  const addServer = async (name: string, url: string) => {
    await agent.call("addServer", [name, url]);
  };

  const removeServer = async (serverId: string) => {
    await agent.call("disconnectServer", [serverId]);
  };

  return (
    <div>
      <h1>MCP Servers</h1>
      {mcpServers.map((server) => (
        <div key={server.id}>
          <h2>{server.name}</h2>
          <p>Status: {server.status}</p>
          <h3>Tools</h3>
          <ul>
            {server.tools.map((tool) => (
              <li key={tool.name}>{tool.name}: {tool.description}</li>
            ))}
          </ul>
          <button onClick={() => removeServer(server.id)}>
            Disconnect
          </button>
        </div>
      ))}
      <button onClick={() => addServer("Demo", "http://localhost:5173/mcp")}>
        Add Server
      </button>
    </div>
  );
}

How It Works

1. Agent manages connections

   The Agent manages MCP server connections via the built-in mcp property. Each connection maintains state about available tools, prompts, and resources.

2. OAuth configuration

   configureOAuthCallback sets up the OAuth flow. When an MCP server requires authentication, a popup window opens. After auth completes, the custom handler closes the popup automatically.

3. Real-time updates

   When servers are added, removed, or change state, the Agent broadcasts updates via WebSocket. The client’s onMcpUpdate callback receives the new state.

4. Call server methods

   The client uses agent.call() to invoke callable methods on the Agent, like adding or removing servers.

OAuth Flow

For MCP servers that require authentication:

// Server: configure OAuth callback
this.mcp.configureOAuthCallback({
  customHandler: (result) => {
    if (result.authSuccess) {
      // Close the popup window
      return new Response("<script>window.close();</script>", {
        headers: { "content-type": "text/html" }
      });
    }
    // Show error in popup
    return new Response(`Auth failed: ${result.authError}`, {
      status: 400
    });
  }
});

// Client: add server that requires auth
await agent.call("addServer", [
  "GitHub",
  "https://mcp-server.example.com/mcp"
]);
// If auth is required, a popup automatically opens
// After user authorizes, popup closes and connection completes

MCP Server State

The onMcpUpdate callback receives an array of server info:

type McpServerInfo = {
  id: string;
  name: string;
  url: string;
  status: "connecting" | "connected" | "disconnected" | "error";
  error?: string;
  tools: {
    name: string;
    description: string;
    inputSchema: Record<string, unknown>;
  }[];
  prompts: {
    name: string;
    description: string;
  }[];
  resources: {
    uri: string;
    name: string;
    description: string;
  }[];
};

Using MCP Tools in AI Chat

Combine MCP client with AI chat:

import { AIChatAgent } from "@cloudflare/ai-chat";
import { streamText } from "ai";

export class ChatAgent extends AIChatAgent {
  waitForMcpConnections = true;

  async onChatMessage() {
    // Get tools from all connected MCP servers
    const mcpTools = this.mcp.getAITools();

    const result = streamText({
      model,
      tools: {
        // MCP tools are now available to the LLM
        ...mcpTools,
        // Plus any local tools
        myLocalTool: tool({ ... })
      },
      messages: this.messages
    });

    return result.toUIMessageStreamResponse();
  }
}

Running the Example

1. Install dependencies

   npm install
   
2. Configure environment

   Copy .env.example to .env:

   cp .env.example .env
   

   Set HOST to your callback host (usually http://localhost:5173 for local dev).

3. Start the server

   npm run dev
   
4. Connect to a server

   Open http://localhost:5173, enter an MCP server URL, and click Connect.

   To test with authentication, run the mcp-worker-authenticated example alongside this one.

Testing with Another Example

Run the MCP Server example in another terminal:

cd examples/mcp
npm install && npm run dev

Then in this example, add the server:

• Name: Demo
• URL: http://localhost:5174/mcp (note the different port)

You’ll see the server’s tools and resources appear in the UI.

Related Examples

MCP Server

Build a stateful MCP server

MCP Authenticated

MCP server with OAuth authentication

AI Chat

Use MCP tools in AI chat (includes MCP client)

MCP Guide

In-depth guide to Model Context Protocol