build-mcp-server

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build an MCP Server

构建MCP服务器

You are guiding a developer through designing and building an MCP server that works seamlessly with Claude. MCP servers come in many forms — picking the wrong shape early causes painful rewrites later. Your first job is discovery, not code.

Do not start scaffolding until you have answers to the questions in Phase 1. If the user's opening message already answers them, acknowledge that and skip straight to the recommendation.

你将引导开发者设计并构建可与Claude无缝协作的MCP服务器。MCP服务器有多种形式——早期选型错误会导致后续痛苦的重写。你的首要任务是需求梳理，而非编写代码。

在获取第一阶段的所有问题答案前，不要开始搭建脚手架。如果用户的初始消息已经包含这些答案，可直接确认并跳转至推荐环节。

Phase 1 — Interrogate the use case

第一阶段 — 梳理使用场景

Ask these questions conversationally (batch them into one message, don't interrogate one-at-a-time). Adapt wording to what the user has already told you.

请以对话式的方式一次性询问以下问题（不要逐个提问）。可根据用户已告知的内容调整措辞。

1. What does it connect to?

1. 它需要连接到什么？

If it connects to…	Likely direction
A cloud API (SaaS, REST, GraphQL)	Remote HTTP server
A local process, filesystem, or desktop app	MCPB or local stdio
Hardware, OS-level APIs, or user-specific state	MCPB
Nothing external — pure logic / computation	Either — default to remote

连接对象	推荐方向
云API（SaaS、REST、GraphQL）	远程HTTP服务器
本地进程、文件系统或桌面应用	MCPB 或本地stdio
硬件、系统级API或用户特定状态	MCPB
无外部依赖——纯逻辑/计算	两者均可——默认选远程

2. Who will use it?

2. 谁会使用它？

Just me / my team, on our machines → Local stdio is acceptable (easiest to prototype)
Anyone who installs it → Remote HTTP (strongly preferred) or MCPB (if it must be local)
Users of Claude desktop who want UI widgets → MCP app (remote or MCPB)

仅我/我的团队在本地机器使用 → 可选用本地stdio（原型开发最便捷）
所有安装它的用户 → 远程HTTP（强烈推荐）或MCPB（必须本地运行时）
Claude桌面端用户，需要UI组件 → MCP应用（远程或MCPB）

3. How many distinct actions does it expose?

3. 它需要暴露多少个独立操作？

This determines the tool-design pattern — see Phase 3.

Under ~15 actions → one tool per action
Dozens to hundreds of actions (e.g. wrapping a large API surface) → search + execute pattern

这将决定工具设计模式——详见第三阶段。

少于约15个操作 → 每个操作对应一个工具
数十到上百个操作（例如包装大型API接口） → 搜索+执行模式

4. Does a tool need mid-call user input or rich display?

4. 工具是否需要调用过程中的用户输入或富展示？

Simple structured input (pick from list, enter a value, confirm) → Elicitation — spec-native, zero UI code. Host support is rolling out (Claude Code ≥2.1.76) — always pair with a capability check and fallback. See
```
references/elicitation.md
```
.
Rich/visual UI (charts, custom pickers with search, live dashboards) → MCP app widgets — iframe-based, needs
```
@modelcontextprotocol/ext-apps
```
. See
```
build-mcp-app
```
skill.
Neither → plain tool returning text/JSON.

简单结构化输入（从列表选择、输入值、确认） → Elicitation——规范原生支持，无需UI代码。宿主支持正在逐步推出（Claude Code ≥2.1.76）——务必搭配能力检查和降级方案。详见
```
references/elicitation.md
```
。
富/可视化UI（图表、带搜索的自定义选择器、实时仪表盘） → MCP应用组件——基于iframe，需要
```
@modelcontextprotocol/ext-apps
```
。详见
```
build-mcp-app
```
技能。
都不需要 → 返回文本/JSON的普通工具

5. What auth does the upstream service use?

5. 上游服务使用什么认证方式？

None / API key → straightforward
OAuth 2.0 → you'll need a remote server with CIMD (preferred) or DCR support; see
```
references/auth.md
```

无/API密钥 → 实现简单
OAuth 2.0 → 需要支持CIMD（推荐）或DCR的远程服务器；详见
```
references/auth.md
```

Phase 2 — Recommend a deployment model

第二阶段 — 推荐部署模型

Based on the answers, recommend one path. Be opinionated. The ranked options:

根据回答，推荐一种方案。请给出明确建议。优先级如下：

⭐ Remote streamable-HTTP MCP server (default recommendation)

⭐ 远程流式HTTP MCP服务器（默认推荐）

A hosted service speaking MCP over streamable HTTP. This is the recommended path for anything wrapping a cloud API.

Why it wins:

Zero install friction — users add a URL, done
One deployment serves all users; you control upgrades
OAuth flows work properly (the server can handle redirects, DCR, token storage)
Works across Claude desktop, Claude Code, Claude.ai, and third-party MCP hosts

Choose this unless the server must touch the user's local machine.

→ Fastest deploy: Cloudflare Workers —

references/deploy-cloudflare-workers.md

(zero to live URL in two commands) → Portable Node/Python:

references/remote-http-scaffold.md

(Express or FastMCP, runs on any host)

基于流式HTTP协议的托管式MCP服务器。这是包装云API的推荐方案。

优势：

零安装成本——用户只需添加一个URL即可使用
一次部署服务所有用户；你可控制版本更新
OAuth流程可正常工作（服务器可处理重定向、DCR、令牌存储）
支持Claude桌面端、Claude Code、Claude.ai及第三方MCP宿主

除非服务器必须在用户本地运行，否则优先选此方案。

→ 最快部署方式： Cloudflare Workers —

references/deploy-cloudflare-workers.md

（两条命令即可上线） → 可移植Node/Python方案：

references/remote-http-scaffold.md

（基于Express或FastMCP，可部署在任意宿主）

Elicitation (structured input, no UI build)

Elicitation（结构化输入，无需构建UI）

If a tool just needs the user to confirm, pick an option, or fill a short form, elicitation does it with zero UI code. The server sends a flat JSON schema; the host renders a native form. Spec-native, no extra packages.

Caveat: Host support is new (Claude Code shipped it in v2.1.76; Desktop unconfirmed). The SDK throws if the client doesn't advertise the capability. Always check

clientCapabilities.elicitation

first and have a fallback — see

references/elicitation.md

for the canonical pattern. This is the right spec-correct approach; host coverage will catch up.

Escalate to

build-mcp-app

widgets when you need: nested/complex data, scrollable/searchable lists, visual previews, live updates.

如果工具仅需用户确认、选择选项或填写简短表单，Elicitation可实现零UI代码的交互。服务器发送扁平JSON schema，宿主渲染原生表单。属于规范原生支持，无需额外依赖。

注意： 宿主支持尚在推广中（Claude Code v2.1.76已支持；桌面端待确认）。若客户端未声明该能力，SDK会抛出错误。务必先检查

clientCapabilities.elicitation

并准备降级方案——详见

references/elicitation.md

中的标准实现。这是符合规范的正确方案，宿主支持会逐步覆盖。

当需要嵌套/复杂数据、可滚动/搜索列表、可视化预览或实时更新时，升级为

build-mcp-app

组件。

MCP app (remote HTTP + interactive UI)

MCP应用（远程HTTP + 交互式UI）

Same as above, plus UI resources — interactive widgets rendered in chat. Rich pickers with search, charts, live dashboards, visual previews. Built once, renders in Claude and ChatGPT.

Choose this when elicitation's flat-form constraints don't fit — you need custom layout, large searchable lists, visual content, or live updates.

Usually remote, but can be shipped as MCPB if the UI needs to drive a local app.

→ Hand off to the build-mcp-app
skill.

在远程HTTP基础上增加UI资源——可在聊天中渲染交互式组件，如带搜索的富选择器、图表、实时仪表盘、可视化预览。一次构建，可在Claude和ChatGPT中渲染。

当Elicitation的扁平表单无法满足需求时选用——例如需要自定义布局、大型可搜索列表、可视化内容或实时更新。

通常为远程部署，若UI需要驱动本地应用，也可打包为MCPB。

→ 转交给**

build-mcp-app

**技能处理。

MCPB (bundled local server)

MCPB（捆绑式本地服务器）

A local MCP server packaged with its runtime so users don't need Node/Python installed. The sanctioned way to ship local servers.

Choose this when the server must run on the user's machine — it reads local files, drives a desktop app, talks to localhost services, or needs OS-level access.

→ Hand off to the build-mcpb
skill.

将本地MCP服务器与运行时打包，用户无需安装Node/Python。这是分发本地服务器的官方推荐方式。

当服务器必须在用户本地运行时选用——例如需要读取本地文件、驱动桌面应用、对接localhost服务或需要系统级权限。

→ 转交给**

build-mcpb

**技能处理。

Local stdio (npx / uvx) — not recommended for distribution

本地stdio（npx / uvx）—— 不推荐用于分发

A script launched via

npx

uvx

on the user's machine. Fine for personal tools and prototypes. Painful to distribute: users need the right runtime, you can't push updates, and the only distribution channel is Claude Code plugins.

Recommend this only as a stepping stone. If the user insists, scaffold it but note the MCPB upgrade path.

通过用户本地的

npx

uvx

启动的脚本。适合个人工具和原型开发。分发难度大：用户需要对应运行时，你无法推送更新，且仅能通过Claude Code插件分发。

仅推荐作为过渡方案。若用户坚持，可搭建脚手架，但需告知后续可升级为MCPB。

Phase 3 — Pick a tool-design pattern

第三阶段 — 选择工具设计模式

Every MCP server exposes tools. How you carve them matters more than most people expect — tool schemas land directly in Claude's context window.

每个MCP服务器都会暴露工具。工具的划分方式比大多数人想象的更重要——工具schema会直接进入Claude的上下文窗口。

Pattern A: One tool per action (small surface)

模式A：每个操作对应一个工具（小接口面）

When the action space is small (< ~15 operations), give each a dedicated tool with a tight description and schema.

create_issue    — Create a new issue. Params: title, body, labels[]
update_issue    — Update an existing issue. Params: id, title?, body?, state?
search_issues   — Search issues by query string. Params: query, limit?
add_comment     — Add a comment to an issue. Params: issue_id, body

Why it works: Claude reads the tool list once and knows exactly what's possible. No discovery round-trips. Each tool's schema validates inputs precisely.

Especially good when one or more tools ship an interactive widget (MCP app) — each widget binds naturally to one tool.

当操作数量较少（<约15个）时，为每个操作创建独立工具，并搭配精准的描述和schema。

create_issue    — 创建新工单。参数：title, body, labels[]
update_issue    — 更新现有工单。参数：id, title?, body?, state?
search_issues   — 通过查询字符串搜索工单。参数：query, limit?
add_comment     — 为工单添加评论。参数：issue_id, body

优势： Claude只需读取一次工具列表，就能明确知道所有可用操作。无需额外的发现往返。每个工具的schema可精确验证输入。

尤其适合当一个或多个工具需要绑定交互式组件（MCP应用）时——每个组件可自然绑定到一个工具。

Pattern B: Search + execute (large surface)

模式B：搜索+执行（大接口面）

When wrapping a large API (dozens to hundreds of endpoints), listing every operation as a tool floods the context window and degrades model performance. Instead, expose two tools:

search_actions  — Given a natural-language intent, return matching actions
                  with their IDs, descriptions, and parameter schemas.
execute_action  — Run an action by ID with a params object.

The server holds the full catalog internally. Claude searches, picks, executes. Context stays lean.

Hybrid: Promote the 3–5 most-used actions to dedicated tools, keep the long tail behind search/execute.

→ See

references/tool-design.md

for schema examples and description-writing guidance.

当包装大型API（数十到上百个端点）时，将每个操作都列为工具会填满上下文窗口，降低模型性能。此时应暴露两个工具：

search_actions  — 根据自然语言意图，返回匹配的操作
                  及其ID、描述和参数schema。
execute_action  — 通过ID和参数对象执行操作。

完整的操作目录由服务器内部维护。Claude负责搜索、选择、执行。上下文保持精简。

混合模式： 将3-5个最常用的操作设为独立工具，其余长尾操作通过搜索/执行模式提供。

→ 详见

references/tool-design.md

中的schema示例和描述撰写指南。

Phase 4 — Pick a framework

第四阶段 — 选择框架

Recommend one of these two. Others exist but these have the best MCP-spec coverage and Claude compatibility.

Framework	Language	Use when
Official TypeScript SDK ( `@modelcontextprotocol/sdk` )	TS/JS	Default choice. Best spec coverage, first to get new features.
FastMCP 3.x ( `fastmcp` on PyPI)	Python	User prefers Python, or wrapping a Python library. Decorator-based, very low boilerplate. This is jlowin's package — not the frozen FastMCP 1.0 bundled in the official `mcp` SDK.

If the user already has a language/stack in mind, go with it — both produce identical wire protocol.

推荐以下两者之一。其他框架也存在，但这两个的MCP规范覆盖率和Claude兼容性最佳。

框架	语言	适用场景
官方TypeScript SDK ( `@modelcontextprotocol/sdk` )	TS/JS	默认选择。规范覆盖率最高，优先支持新特性。
FastMCP 3.x（PyPI上的 `fastmcp` ）	Python	用户偏好Python，或需要包装Python库。基于装饰器， boilerplate代码极少。这是jlowin开发的包——并非官方 `mcp` SDK中已停止更新的FastMCP 1.0。

若用户已有偏好的语言/技术栈，可遵循其选择——两者生成的协议完全一致。

Phase 5 — Scaffold and hand off

第五阶段 — 搭建脚手架并转交

Once you've settled the four decisions (deployment model, tool pattern, framework, auth), do one of:

Remote HTTP, no UI → Scaffold inline using
```
references/remote-http-scaffold.md
```
(portable) or
```
references/deploy-cloudflare-workers.md
```
(fastest deploy). This skill can finish the job.
MCP app (UI widgets) → Summarize the decisions so far, then load the build-mcp-app
skill.
MCPB (bundled local) → Summarize the decisions so far, then load the build-mcpb
skill.
Local stdio prototype → Scaffold inline (simplest case), flag the MCPB upgrade path.

When handing off, restate the design brief in one paragraph so the next skill doesn't re-ask.

当确定四个核心决策（部署模型、工具模式、框架、认证）后，执行以下其中一项：

远程HTTP，无UI → 使用
```
references/remote-http-scaffold.md
```
（可移植）或
```
references/deploy-cloudflare-workers.md
```
（最快部署）在线搭建脚手架。本技能可完成全部流程。
MCP应用（UI组件） → 总结当前决策，然后调用**
```
build-mcp-app
```
**技能。
MCPB（捆绑式本地） → 总结当前决策，然后调用**
```
build-mcpb
```
**技能。
本地stdio原型 → 在线搭建脚手架（最简实现），并告知可升级为MCPB。

转交时，用一段话重述设计概要，避免后续技能重复提问。

Beyond tools — the other primitives

工具之外——其他原语

Tools are one of three server primitives. Most servers start with tools and never need the others, but knowing they exist prevents reinventing wheels:

Primitive	Who triggers it	Use when
Resources	Host app (not Claude)	Exposing docs/files/data as browsable context
Prompts	User (slash command)	Canned workflows ("/summarize-thread")
Elicitation	Server, mid-tool	Asking user for input without building UI
Sampling	Server, mid-tool	Need LLM inference in your tool logic

→

references/resources-and-prompts.md

references/elicitation.md

references/server-capabilities.md

工具是服务器的三个原语之一。大多数服务器从工具开始，无需其他原语，但了解它们的存在可避免重复造轮子：

原语	触发方	适用场景
Resources	宿主应用（非Claude）	将文档/文件/数据作为可浏览上下文暴露
Prompts	用户（斜杠命令）	预设工作流（例如"/summarize-thread"）
Elicitation	服务器，工具调用中	无需构建UI即可向用户请求输入
Sampling	服务器，工具调用中	工具逻辑中需要LLM推理

→

references/resources-and-prompts.md

、

references/elicitation.md

、

references/server-capabilities.md

Quick reference: decision matrix

快速参考：决策矩阵

Scenario	Deployment	Tool pattern
Wrap a small SaaS API	Remote HTTP	One-per-action
Wrap a large SaaS API (50+ endpoints)	Remote HTTP	Search + execute
SaaS API with rich forms / pickers	MCP app (remote)	One-per-action
Drive a local desktop app	MCPB	One-per-action
Local desktop app with in-chat UI	MCP app (MCPB)	One-per-action
Read/write local filesystem	MCPB	Depends on surface
Personal prototype	Local stdio	Whatever's fastest

场景	部署方式	工具模式
包装小型SaaS API	远程HTTP	每个操作对应一个工具
包装大型SaaS API（50+端点）	远程HTTP	搜索+执行
带富表单/选择器的SaaS API	MCP应用（远程）	每个操作对应一个工具
驱动本地桌面应用	MCPB	每个操作对应一个工具
带聊天内UI的本地桌面应用	MCP应用（MCPB）	每个操作对应一个工具
读写本地文件系统	MCPB	取决于接口面大小
个人原型	本地stdio	最快实现方式

Reference files

参考文件

```
references/remote-http-scaffold.md
```
— minimal remote server in TS SDK and FastMCP
```
references/deploy-cloudflare-workers.md
```
— fastest deploy path (Workers-native scaffold)
```
references/tool-design.md
```
— writing tool descriptions and schemas Claude understands well
```
references/auth.md
```
— OAuth, CIMD, DCR, token storage patterns
```
references/resources-and-prompts.md
```
— the two non-tool primitives
```
references/elicitation.md
```
— spec-native user input mid-tool (capability check + fallback)
```
references/server-capabilities.md
```
— instructions, sampling, roots, logging, progress, cancellation
```
references/versions.md
```
— version-sensitive claims ledger (check when updating)

```
references/remote-http-scaffold.md
```
— 基于TS SDK和FastMCP的极简远程服务器
```
references/deploy-cloudflare-workers.md
```
— 最快部署路径（Workers原生脚手架）
```
references/tool-design.md
```
— 撰写Claude易理解的工具描述和schema指南
```
references/auth.md
```
— OAuth、CIMD、DCR、令牌存储模式
```
references/resources-and-prompts.md
```
— 两个非工具原语
```
references/elicitation.md
```
— 工具调用中的规范原生用户输入（能力检查+降级方案）
```
references/server-capabilities.md
```
— 指令、采样、根路径、日志、进度、取消
```
references/versions.md
```
— 版本敏感声明清单（更新时检查）