> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enconvo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 构建 MCP 服务器

> 编写一个小型本地 MCP 服务器，连接到 Enconvo，并为你的智能体提供其中的工具。

本页面向希望为 Enconvo 智能体打造专属工具的开发者。自定义 MCP 服务器可以暴露供 Enconvo 智能体调用的工具。你可以先从一个简单的本地服务器开始，验证其输入和返回结果，然后再逐步添加所需的特定服务逻辑。

要安装别人制作好的服务器，请参阅 [MCP 服务器](https://docs.enconvo.ai/zh/features/mcp.md)。如果你想分发自己的服务器，使其也能在 Codex 和 Claude Code 中安装，请使用 `--template mcp` 将其打包为插件（参见[插件格式](https://docs.enconvo.ai/extensions/plugin-formats.md#one-package-for-enconvo-codex-and-claude-code)）。

## 开始之前

你需要先安装 Node.js 和 npm。本示例使用 TypeScript SDK 的 **1.x JavaScript API**（固定为 1.29.0）。不同主版本的 SDK 可能使用不同的导入方式和配置方法；如需选择其他版本，请参考[官方 MCP 服务器指南](https://modelcontextprotocol.io/docs/develop/build-server)。

## 编写一个最小的本地服务器

```sh theme={null}
mkdir hello-mcp
cd hello-mcp
npm init -y
npm install @modelcontextprotocol/sdk@1.29.0 zod@3
```

将以下内容保存为 `server.mjs`：

```javascript theme={null}
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "hello-enconvo", version: "1.0.0" });

server.registerTool("greet", {
  description: "Return a greeting for the supplied name.",
  inputSchema: { name: z.string().min(1).describe("Name to greet") },
}, async ({ name }) => ({
  content: [{ type: "text", text: `Hello, ${name}!` }],
}));

await server.connect(new StdioServerTransport());
```

stdio 服务器会等待协议消息，因此在终端中直接启动它不会显示聊天界面。请将诊断日志输出到 stderr（例如使用 `console.error`），因为 stdout 负责传输 MCP 协议消息。[官方指南](https://modelcontextprotocol.io/docs/develop/build-server)中详细说明了这一传输要求。

## 连接到 Enconvo

**1. 添加服务器**

打开 **设置 → MCP 服务器**，点按 **添加服务器**。输入 **服务器名称**，例如 `hello-mcp`。

**2. 设置启动方式**

选择 **STDIO**。在 **命令** 中输入 `node`。在 **参数** 中输入 `server.mjs` 的绝对路径。如果 Enconvo 找不到 Node，请填写 Node 可执行文件的绝对路径。

**3. 保存并检查**

点按 **保存**。确认服务器已成功连接并暴露了 `greet` 工具。

**4. 试一试**

将它提供给你的智能体使用，并让它向“Ada”问好。预期的工具返回结果应为 `Hello, Ada!`。

等效配置如下：

```json theme={null}
{
  "command": "node",
  "args": ["/absolute/path/to/hello-mcp/server.mjs"]
}
```

请将示例路径替换为你文件的实际路径。

## 设计好用的工具

* 为每个工具提供清晰具体的操作与描述。
* 在工具入口处校验输入，并返回明确有用的错误信息。
* 将读取数据的操作与发送、删除等修改操作分开。
* 返回紧凑、易于智能体理解的结果。
* 将凭据存放在服务器对应的配置中，不要写入示例代码或日志里。

## 远程服务器与身份验证

对于远程服务器，请根据其配置说明选择 HTTP 或 SSE 传输方式，并在 Enconvo 表单中选择对应的选项（**HTTP** 或 **SSE**，而非 **STDIO**）。服务器 URL 必须是 MCP 端点地址，而不是普通网页地址。在启用其工具之前，请先完成所需的授权流程并确认连接成功。

远程传输、身份验证发现和会话行为取决于具体的服务器与协议版本。具体实现细节请以官方 SDK 和协议文档为准，不要自行编写 Enconvo 不会读取的 `auth` 清单。

## 故障排除

| 问题 | 解决方法 |
| - | - |
| 进程启动后立即退出 | 检查可执行文件路径、依赖项、语法错误以及 stderr 输出 |
| 已连接但没有出现工具 | 检查工具是否正确注册、工具是否已启用，以及当前选中的智能体 |
| 协议响应无效 | 检查是否意外向 stdout 打印了日志，或是否启动了错误的程序 |
| Schema 校验错误 | 将实际输入结构与你使用的 SDK 版本进行核对 |
| 远程连接失败 | 检查端点 URL、传输方式、身份验证以及网络连接 |

如需将 Enconvo 自己的文档暴露给其他 AI 客户端，请使用内置的[知识库 MCP 服务器](https://docs.enconvo.ai/zh/advanced/knowledge-base-mcp.md)，无需编写自定义服务器。

## 相关内容

> [card] [MCP 服务器](https://docs.enconvo.ai/zh/features/mcp.md)
>
> 在 Enconvo 中安装和管理 MCP 服务器

> [card] [插件格式](https://docs.enconvo.ai/extensions/plugin-formats.md)
>
> 将服务器打包为适用于 Enconvo、Codex 和 Claude Code 的插件


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.