mcp-server-creation

MCP 服务创建

Agent Skills™ 的一部分，由 googleadsagent.ai™ 提供

描述

MCP 服务创建是指构建模型上下文协议服务，通过标准化接口向 AI Agent 提供工具、资源和能力。MCP 已成为 AI Agent 工具的通用集成层——借助这一协议，任何兼容的 Agent（Claude Code、Cursor、Codex 等）都能发现并调用服务端工具，无需编写自定义集成代码。在 Cloudflare Workers 上构建生产级 MCP 服务，无需管理基础设施，即可实现全球低延迟的工具访问。

本技能参考了为 googleadsagent.ai™ 上的 Buddy™ Agent 提供支持的生产级 MCP 服务。该服务部署在 Cloudflare Workers 的 workers/buddy-agent/ 目录中，通过 MCP 提供 Google Ads 分析工具、知识库搜索、实体记忆管理和网页搜索功能，供任何兼容 MCP 的客户端使用。该架构可在边缘处理身份验证、速率限制和多租户隔离。

MCP 规范定义了三种核心原语：工具（Agent 可调用的可执行函数）、资源（Agent 可访问的只读数据）和提示词（可复用的提示词模板）。设计良好的 MCP 服务会提供一组精简且高价值的工具，并配有清晰的架构、明确的描述和可靠的错误处理。传输层同时支持 stdio（用于本地开发）和 SSE/HTTP（用于远程部署），并在传输层集成身份验证。

适用场景

• 需要通过标准化协议向 AI Agent 提供自定义工具
• 构建可用于 Claude Code、Cursor 和其他 MCP 客户端的集成
• 将 Agent 工具部署到 Cloudflare Workers，以便通过全球边缘网络访问
• 为组织创建工具市场或共享工具基础设施
• 从专有工具接口迁移到开放的 MCP 标准
• Agent 需要使用依赖服务端密钥或 API 访问权限的工具

工作原理

graph TD
    A[AI Agent / MCP Client] -->|MCP Protocol| B[Transport Layer]
    B -->|stdio| C[Local Development]
    B -->|SSE/HTTP| D[Remote Server]
    D --> E[Cloudflare Worker]
    E --> F[Authentication]
    F --> G[Tool Router]
    G --> H[Tool: search_knowledge]
    G --> I[Tool: analyze_campaign]
    G --> J[Tool: get_metrics]
    H --> K[Knowledge Base]
    I --> L[Google Ads API]
    J --> L
    G --> M[Resource: config]
    G --> N[Resource: schema]

MCP 服务位于 AI Agent 客户端与实际数据源或 API 之间。传输层负责处理协议协商（本地使用 stdio，远程使用 SSE/HTTP）。部署到 Cloudflare Workers 时，系统会先对传入请求进行身份验证（OAuth、API 密钥或 JWT），然后将请求路由到相应的工具处理程序。每个工具处理程序都实现业务逻辑——调用外部 API、查询数据库或执行计算——并返回结构化结果，供 Agent 推理。

实现

基于 Cloudflare Workers 的 MCP 服务：

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

export class BuddyMCPServer extends McpAgent {
  server = new McpServer({
    name: "buddy-agent",
    version: "1.0.0",
  });

  async init() {
    this.server.tool(
      "search_knowledge",
      "Search the Google Ads knowledge base for patterns and best practices matching a query. Use BEFORE making recommendations.",
      { query: z.string(), category: z.enum(["bidding", "targeting", "creative", "budget", "general"]).optional(), maxResults: z.number().default(5) },
      async ({ query, category, maxResults }) => {
        const results = await this.searchKnowledgeBase(query, category, maxResults);
        return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
      }
    );

    this.server.tool(
      "analyze_campaign",
      "Analyze a Google Ads campaign's performance metrics and return structured insights with recommendations.",
      { campaignId: z.string(), dateRange: z.enum(["7d", "30d", "90d"]).default("30d"), metrics: z.array(z.string()).optional() },
      async ({ campaignId, dateRange, metrics }) => {
        const analysis = await this.analyzeCampaign(campaignId, dateRange, metrics);
        return { content: [{ type: "text", text: JSON.stringify(analysis, null, 2) }] };
      }
    );

    this.server.tool(
      "store_entity",
      "Persist an extracted entity (decision, metric, preference) to cross-session memory.",
      { userId: z.string(), entityType: z.enum(["decision", "metric", "preference", "fact"]), content: z.string(), importance: z.number().min(0).max(1).default(0.5) },
      async ({ userId, entityType, content, importance }) => {
        await this.persistEntity(userId, entityType, content, importance);
        return { content: [{ type: "text", text: `Entity stored: [${entityType}] ${content}` }] };
      }
    );
  }

  private async searchKnowledgeBase(query: string, category?: string, limit?: number) {
    const patterns = await this.env.KNOWLEDGE_KV.list({ prefix: category ? `pattern:${category}:` : "pattern:" });
    const results = [];
    for (const key of patterns.keys.slice(0, limit || 5)) {
      const pattern = await this.env.KNOWLEDGE_KV.get(key.name, "json");
      if (pattern && this.isRelevant(query, pattern)) {
        results.push(pattern);
      }
    }
    return results;
  }
}

Wrangler 配置：

// wrangler.jsonc
{
  "name": "buddy-mcp-server",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01",
  "compatibility_flags": ["nodejs_compat"],
  "kv_namespaces": [
    { "binding": "KNOWLEDGE_KV", "id": "your-kv-id" },
    { "binding": "MEMORY_KV", "id": "your-memory-kv-id" }
  ],
  "vars": {
    "ENVIRONMENT": "production"
  },
  "placement": { "mode": "smart" }
}

MCP 客户端配置（Claude Code）：

{
  "mcpServers": {
    "buddy-agent": {
      "type": "sse",
      "url": "https://buddy-mcp.googleadsagent.ai/sse",
      "headers": {
        "Authorization": "Bearer ${BUDDY_API_KEY}"
      }
    }
  }
}

MCP 客户端配置（Cursor）：

{
  "mcpServers": {
    "buddy-agent": {
      "url": "https://buddy-mcp.googleadsagent.ai/sse",
      "headers": {
        "Authorization": "Bearer ${BUDDY_API_KEY}"
      }
    }
  }
}

使用 stdio 传输进行本地开发：

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({ name: "buddy-agent-dev", version: "1.0.0-dev" });

server.tool(
  "search_knowledge",
  "Search the local knowledge base for development and testing.",
  { query: z.string() },
  async ({ query }) => {
    const results = searchLocalKnowledge(query);
    return { content: [{ type: "text", text: JSON.stringify(results) }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

最佳实践

1. 编写说明何时使用工具的描述 — AI Agent 根据描述选择工具；“在提供建议前使用”是模型可以遵循的实用指导。
2. 使用带有描述性枚举的 Zod schemas — 受约束的参数类型可以消除无效输入；枚举尤其擅长引导模型选择参数。
3. 返回结构化 JSON，而非散文 — 结构化结果更便于模型推理，且比叙述性响应消耗更少的令牌。
4. 在传输层实现身份验证 — 切勿在没有身份验证的情况下公开 MCP 服务；应使用 OAuth、JWT 或 API 密钥，并在工具路由前进行验证。
5. 控制工具数量 — 5-10 个设计完善的工具胜过 50 个功能重叠的工具；工具选择更少、更清晰时，模型表现更好。
6. 使用多个 MCP 客户端进行测试 — 不同客户端（如 Claude Code、Cursor 等）的行为可能有所不同；请在每个目标客户端上测试工具调用。
7. 使用 Cloudflare Workers 部署到边缘节点 — 边缘部署可降低地理位置分散的用户的延迟，并提供内置 DDoS 防护。
8. 为 MCP 服务进行版本管理 — 随着工具不断演进，请保持向后兼容，或明确提升版本号，以免破坏现有客户端配置。

平台兼容性

功能	Claude Code	Cursor	Codex	Gemini CLI
MCP 客户端支持	✅ 原生	✅ 原生	⚠️ 有限	⚠️ 有限
stdio 传输	✅ 完整	✅ 完整	⚠️ 自定义	⚠️ 自定义
SSE 传输	✅ 完整	✅ 完整	⚠️ 自定义	⚠️ 自定义
工具发现	✅ 自动	✅ 自动	⚠️ 手动	⚠️ 手动
OAuth 支持	✅ 完整	✅ 完整	⚠️ 自定义	⚠️ 自定义

相关技能

• 多模型路由 - MCP 服务可以将模型路由逻辑集成到工具执行流水线中
• 知识库注入 - 知识搜索工具通过 MCP 暴露，为 Agent 提供可访问的领域专业知识
• 并行 Agent 编排 - MCP 工具支持标准化的工具访问，以便并行调度子 Agent
• 购物广告 - 通过 MCP 集成 Merchant Center，可实现产品 Feed 管理自动化

关键词

mcp-server, model-context-protocol, cloudflare-workers, tool-definitions, resource-handlers, sse-transport, stdio-transport, authentication, edge-deployment, agent-skills

---

© 2026 googleadsagent.ai™ | Agent Skills™ | MIT License