跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

连接到 MCP 服务器

最后更新 查看 MarkdownAgent 设置

你的 Agent 可以连接到外部 Model Context Protocol (MCP) ↗ 服务器，访问其 tool 并扩展 Agent 能力。本教程将创建一个连接到 MCP 服务器并使用其 tool 之一的 Agent。

你将构建什么

一个具备以下端点的 Agent：

  • 连接到 MCP 服务器
  • 列出已连接服务器上的可用 tool
  • 获取连接状态

前提条件

要连接的 MCP 服务器（或使用本教程中的公开示例）。

1. 创建基础 Agent

  1. 使用 hello-world 模板创建新的 Agent 项目：

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

  2. 进入项目目录：

    cd my-mcp-client

    Agent 已就绪！模板在 src/index.ts 中包含一个最小 Agent：

    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 })
		);
	},
};
    src/index.tsts
    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>;

2. 添加 MCP 连接端点

  1. 添加连接到 MCP 服务器的端点。在 src/index.ts 中更新 Agent 类：

    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 });
	}
}
    src/index.tsts
    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 });
	}
}

addMcpServer() 方法连接到 MCP 服务器。若服务器需要 OAuth 认证，会返回 authUrl，用户需访问该 URL 完成授权。

3. 测试连接

  1. 启动开发服务器：

    npm start

  2. 在新终端中连接到 MCP 服务器（使用公开示例）：

    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"
	}'

    应看到包含服务器 ID 的响应：

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

4. 列出可用 tool

  1. 添加端点以查看已连接服务器上的可用 tool：

    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 });
	}
}
    src/index.tsts
    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 });
	}
}

  2. 测试：

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

    将看到所有已连接服务器、其连接状态及可用 tool：

    {
	"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",
			...
		}
	]
}

摘要

你创建了一个可以：

  • 动态连接到外部 MCP 服务器
  • 在需要时处理 OAuth 认证流程
  • 列出所有已连接服务器的可用 tool
  • 监控连接状态

连接持久化在 Agent 的 SQL 存储 中，因此在多次请求间保持活跃。

后续步骤

这篇文档对您有帮助吗？