MCP Server

MCP Server

Agent 和 Client 决定该采取什么行动，但真正让这些行动得以实现的，是 MCP Server。

Server 是各项能力的唯一真实来源——包括可执行的 tools、可读取的 resources、可提供的 prompts，以及像 sampling、elicitation 这样的结构化交互。

一旦 Server 把这些能力开放出来，任何标准的 MCP Client 都可以发现并使用它们。

mcp-use 提供了一个轻量级框架，可以用声明式的方式定义这些能力，让开发者更容易构建出能与 MCP agent 顺畅集成的 Server。

注意：本节所有示例均使用 TypeScript。

接下来的内容将带你了解如何使用 mcp-use 来创建、运行、测试并部署 MCP Server。

1）项目生成器：create-mcp-use-app

mcp-use 内置了一个项目生成器，你可以用下面这些命令来创建一个新的 Server 项目：

运行之后，就会创建出一个开箱即用的 Server，其中包含：

• 一个 TypeScript 入口文件
• 示例 tools、prompts 和 resources
• 配置文件
• 对 MCP Inspector 的内置支持

这为构建 MCP Server 提供了一个便捷的起点。

2）开放 MCP 能力

前面我们已经介绍过支撑该协议的 6 个核心 MCP primitive。

借助 mcp-use，MCP Server 可以通过简短的声明式定义，把它们一一开放出来——tools、resources、prompts、sampling、elicitation 以及 notifications。

这样一来，Server 的能力接口就能保持简单、易于描述，并且能在能力协商（capability negotiation）过程中被 Agent 自动发现。

下面是一些简单的示例，帮助你理解每一项能力。

Tools

Tools 代表 Agent 可以执行的操作，是 MCP Server 开放功能的主要方式——从 API 调用、计算，到工作流中的各个步骤，都可以是一个 Tool。

在 mcp-use 中，Tools 是通过一段简单的声明式定义注册到 Server 上的。

每个 Tool 都包含一个名称、一组输入参数，以及一个向 Client 返回内容的回调函数。下面是一个最简单的 Tool 示例：

这个示例定义了一个完整的 MCP Server，其中只有一个 Tool：get_weather，它会返回一段基本的天气信息。

任何兼容 MCP 的 Client，都可以在能力协商过程中自动发现并调用这个 Tool。

Resources

Resources 通过一个稳定的 URI，开放诸如文件或生成文本之类的只读内容。

Client 可以在会话期间的任意时刻获取这些内容。

Prompts

Prompts 定义了可复用的指令模板，Agent 可以调用它们来生成结构化的消息。

有了它们，你的 Server 就能为常见任务提供格式统一、写得规范的 prompt。

Sampling

Sampling 让你的 Server 可以在工作流执行过程中，请求 Client 一端的模型生成文本。

当 Server 需要模型做出决策、进行总结，或者在多个选项中做选择时，这项能力就很有用。

Elicitation

Elicitation 会向用户请求结构化的输入，比如选择某个选项，或者输入一段文字。

这让那些需要 Server 向用户澄清问题或征求选择的交互式工作流成为可能。

Notifications

Notifications 让你的 Server 可以向 Client 推送异步更新，比如进度或状态的变化。

它们非常适合用在长时间运行或多步骤的操作中。

这些 primitive 合在一起，覆盖了 MCP 的完整能力面：操作执行、结构化的上下文检索、用户交互，以及异步消息传递。

任何 MCP Client 都会在能力协商过程中自动发现这些能力，这意味着你的 Server 无需额外配置，就能立刻被各种 Agent 使用。

3）MCP Inspector

当你以开发模式（npm run dev）启动 Server 时，mcp-use 会自动启动 MCP Inspector——一个基于网页的可视化面板，用于检查和调试 MCP Server。

通过 Inspector，你可以：

• 以交互方式浏览并测试 tools
• 探索 resources，并查看其内容
• 预览 prompts，并校验参数
• 实时查看 sampling 和 notification 事件
• 监控 Client 与 Server 之间的全部 JSON-RPC 通信

在把 Server 接入某个 Agent 之前，这是验证其各项能力最快的方式。

4）MCP-UI

MCP-UI 是一个面向 MCP Server 的 UI 框架，让 Server 可以开放一些简单的 UI 组件（widget），这些组件会显示在兼容的 Client 内部。

有了这些 widget，你的 Server 不需要一整套完整的应用，也能呈现状态信息、预览内容，或者其他快速的可视化输出。

在 mcp-use 中，你可以通过一个小巧、专注的 API 来定义这些 widget。

这是一个简单的示例：

Widget 适用于诸如以下这些场景：

• Server 健康状态指示器
• Resource 预览
• 最近一次 Tool 调用的结果
• 调试或自省（introspection）输出

它们是可选的，但在构建或测试 MCP Server 时，能够显著提升开发体验。

5）Apps SDK

Apps SDK 是 OpenAI 推出的一套框架，用于构建可以直接显示在 ChatGPT 或其他兼容 Apps SDK 的 Client 内部的交互式 UI widget。

这些 widget 是用 React 编写的，让 Tool 可以返回卡片、预览，或者小型应用这样的界面，而不只是纯文本。

MCP Server 可以把这些 widget 作为一项能力开放出来，用很小的开销实现更丰富的工作流。

mcp-use 简化了这一整个流程。

你不需要手动注册 widget、编写 HTML 模板、配置 CSP、打包各种资源，只需要把一个带有 widgetMetadata 导出的 React 组件放进 resources/ 目录即可。mcp-use 会：

• 在 Server 启动时扫描该目录

• 提取组件的元数据

• 把该 widget 注册为一个 resource（如果 widget 定义了输入，还会同时注册为一个 tool）

• 为 Apps SDK 将其打包

• 应用所需的 CSP 配置

• 提供 useWidget 这个 hook，用于访问 props、output、theme 和 state

下面是一个最简单的 Apps SDK widget 示例。

它定义了元数据（这样 Server 才能把这个 widget 作为一项能力开放出来），以及一个 React 组件（Client 会把它渲染在 ChatGPT 内部）。

6）内网穿透（Tunneling）

在开发阶段，MCP Server 通常运行在本地机器上。而当 ChatGPT、Claude，或者某个移动端 Agent 这样的外部 MCP Client 需要连接进来时，就需要一个公网 URL。

mcp-use 提供了一个用于内网穿透的命令，可以把你本地的 MCP Server，通过一个临时的、安全的公网端点暴露出去：

这样就会创建出一个公网 URL（例如 https://example.local.mcp-use.run/mcp），把请求转发到你本地的 /mcp 路由上。

如果你使用的是内置的开发运行器（development runner），也可以直接启用内网穿透，

而不必单独运行一条命令：

这样会自动启动你本地的 Server，并为它创建一条隧道。

你也可以使用 ngrok 这类其他内网穿透工具，只要把公网 URL 映射到 /mcp 端点即可：

内网穿透可以让你：

• 用真实的 MCP Client 进行测试
• 在远程环境中协同工作
• 把正在运行的 Server 分享给团队成员
• 在部署之前验证各项集成

7）部署 MCP Server

只要是能运行 Node.js 的地方，MCP Server 就能运行。一旦部署完成，任何 MCP Client 都可以连接到你的 Server，并通过标准的 MCP 协商流程，自动发现它的 tools、resources、prompts 及其他能力。

你可以把 Server 部署到多种环境中：

• 本地机器
• 云端虚拟机
• Docker 容器
• Serverless 平台
• 边缘运行时（edge runtime）
• mcp-use Cloud

无论选择哪种平台，流程都是一样的：构建你的项目，并把 /mcp 端点公开暴露出去。

只要这个端点是可访问的，Agent 就能立刻检测到新的 tool 或能力，无需额外配置。

为了让流程尽可能简单，mcp-use 还内置了一个托管部署平台：只需一条命令，就能构建并托管你的 MCP Server。

部署完成后，你会得到：

• 一个公网 MCP 端点

• 一个用于实时测试的 Inspector 链接

如果你的项目托管在 GitHub 上，CLI 会自动检测到这一点，并可以直接基于你最新的提交进行部署。

部署完成之后，你的 Client 端不需要重新配置。

无论你是更新了某个 tool、修改了某个 prompt，还是新增了 UI widget，Agent 都会在下一次能力协商时自动获取这些变化。

这让迭代变得非常简单：更新 → 部署 → 能力立即生效。