连接到 MCP server

最近审阅: 6 个月前

你的 Agent 可以连接到外部 Model Context Protocol (MCP) ↗ server,使用其中的工具来扩展自身能力。本教程将带你创建一个 Agent,连接到 MCP server 并使用其中一个工具。

你将构建什么

一个具备以下端点的 Agent:

连接到一个 MCP server
列出已连接 server 中可用的工具
获取连接状态

前置条件

一个可供连接的 MCP server(也可以使用本教程中的公开示例)。

1. 创建一个基础 Agent

使用 hello-world 模板创建一个新的 Agent 项目: npm yarn pnpm

npm create cloudflare@latest -- my-mcp-client --template=cloudflare/ai/demos/hello-world

yarn create cloudflare my-mcp-client --template=cloudflare/ai/demos/hello-world

pnpm create cloudflare@latest my-mcp-client --template=cloudflare/ai/demos/hello-world

进入项目目录: Terminal window

cd my-mcp-client

你的 Agent 已经就绪!模板在 src/index.ts 中提供了一个最小的 Agent:

JavaScript
TypeScript JavaScript

import { Agent, routeAgentRequest } from "agents";
export class HelloAgent extends Agent {
  async onRequest(request) {
    return new Response("Hello, Agent!", { status: 200 });
  }
}
export default {
  async fetch(request, env) {
    return (
      (await routeAgentRequest(request, env, { cors: true })) ||
      new Response("Not found", { status: 404 })
    );
  },
};

Explain Code TypeScript

import { Agent, routeAgentRequest } from "agents";
type Env = {
  HelloAgent: DurableObjectNamespace<HelloAgent>;
};
export class HelloAgent extends Agent<Env> {
  async onRequest(request: Request): Promise<Response> {
    return new Response("Hello, Agent!", { status: 200 });
  }
}
export default {
  async fetch(request: Request, env: Env) {
    return (
      (await routeAgentRequest(request, env, { cors: true })) ||
      new Response("Not found", { status: 404 })
    );
  },
} satisfies ExportedHandler<Env>;

Explain Code

2. 添加 MCP 连接端点

添加一个用于连接 MCP server 的端点。更新 src/index.ts 中的 Agent 类:
- JavaScript
- TypeScript JavaScript

export class HelloAgent extends Agent {
  async onRequest(request) {
    const url = new URL(request.url);
    // Connect to an MCP server
    if (url.pathname.endsWith("add-mcp") && request.method === "POST") {
      const { serverUrl, name } = await request.json();
      const { id, authUrl } = await this.addMcpServer(name, serverUrl);
      if (authUrl) {
        // OAuth required - return auth URL
        return new Response(JSON.stringify({ serverId: id, authUrl }), {
          headers: { "Content-Type": "application/json" },
        });
      }
      return new Response(
        JSON.stringify({ serverId: id, status: "connected" }),
        { headers: { "Content-Type": "application/json" } },
      );
    }
    return new Response("Not found", { status: 404 });
  }
}

Explain Code TypeScript

export class HelloAgent extends Agent<Env> {
  async onRequest(request: Request): Promise<Response> {
    const url = new URL(request.url);
    // Connect to an MCP server
    if (url.pathname.endsWith("add-mcp") && request.method === "POST") {
      const { serverUrl, name } = (await request.json()) as {
        serverUrl: string;
        name: string;
      };
      const { id, authUrl } = await this.addMcpServer(name, serverUrl);
      if (authUrl) {
        // OAuth required - return auth URL
        return new Response(
          JSON.stringify({ serverId: id, authUrl }),
          { headers: { "Content-Type": "application/json" } },
        );
      }
      return new Response(
        JSON.stringify({ serverId: id, status: "connected" }),
        { headers: { "Content-Type": "application/json" } },
      );
    }
    return new Response("Not found", { status: 404 });
  }
}

Explain Code

addMcpServer() 方法用于连接到 MCP server。如果该 server 需要 OAuth 认证,它会返回一个 authUrl,用户必须访问该地址完成授权。

3. 测试连接

启动开发服务器: Terminal window

npm start

在新终端里,连接到一个 MCP server(使用一个公开示例): Terminal window

curl -X POST http://localhost:8788/agents/hello-agent/default/add-mcp \
  -H "Content-Type: application/json" \
  -d '{
    "serverUrl": "https://docs.mcp.cloudflare.com/mcp",
    "name": "Example Server"
  }'

你应该会看到包含 server ID 的响应:

{
  "serverId": "example-server-id",
  "status": "connected"
}

4. 列出可用工具

添加一个端点,查看已连接 server 提供了哪些工具:
- JavaScript
- TypeScript JavaScript

export class HelloAgent extends Agent {
  async onRequest(request) {
    const url = new URL(request.url);
    // ... previous add-mcp endpoint ...
    // List MCP state (servers, tools, etc)
    if (url.pathname.endsWith("mcp-state") && request.method === "GET") {
      const mcpState = this.getMcpServers();
      return Response.json(mcpState);
    }
    return new Response("Not found", { status: 404 });
  }
}

Explain Code TypeScript

export class HelloAgent extends Agent<Env> {
  async onRequest(request: Request): Promise<Response> {
    const url = new URL(request.url);
    // ... previous add-mcp endpoint ...
    // List MCP state (servers, tools, etc)
    if (url.pathname.endsWith("mcp-state") && request.method === "GET") {
      const mcpState = this.getMcpServers();
      return Response.json(mcpState);
    }
    return new Response("Not found", { status: 404 });
  }
}

Explain Code 2. 测试一下: Terminal window

curl http://localhost:8788/agents/hello-agent/default/mcp-state

你将看到所有已连接的 server、它们的连接状态以及可用工具:

{
  "servers": {
    "example-server-id": {
      "name": "Example Server",
      "state": "ready",
      "server_url": "https://docs.mcp.cloudflare.com/mcp",
      ...
    }
  },
  "tools": [
    {
      "name": "add",
      "description": "Add two numbers",
      "serverId": "example-server-id",
      ...
    }
  ]
}

Explain Code

总结

你创建了一个 Agent,它可以:

动态连接到外部 MCP server
在需要时处理 OAuth 认证流程
列出已连接 server 中所有可用工具
监控连接状态

连接信息持久化保存在 Agent 的 SQL 存储中,因此跨请求依然有效。

后续步骤

处理 OAuth 流程配置 OAuth 回调与错误处理。

MCP Client API MCP 客户端的完整 API 文档。

Keyboard shortcuts

从零构建 Cloudflare Agent