> 内容来源：Onevium 官方文档
> 文章: 连接并验证 MCP 服务
> 原文: https://onevium.com/zh/docs/mcp-servers
> 语言：简体中文
> 更新于: 2026-09-16
> 适用版本: 1.2.0+

---

# 连接并验证 MCP 服务

选择传输方式、配置项目或用户范围，并用真实工具调用检查连接与访问边界。

## 连接外部工具

MCP 服务器把工具提供给会话。本教程用两个例子说明实际字段：本地文件系统服务，以及微软公开文档的远程服务。

## 打开正确的配置入口

从左侧导航打开**插件 → MCP**，在作用范围选择器中选中目标项目，再点击**添加 → 手动添加**打开配置表单。需要用户范围配置时，选择**个人 · 所有项目**。新建手动配置会保存到这里选中的范围。

**添加 → AI 辅助添加**，或在会话中使用 **@MCP**，会让助手帮助配置。AI 入口准备的是会话草稿，补充服务信息并发送后才开始设置。

原有右侧 **MCP Servers → 添加服务器**快捷入口仍写入**全局/用户范围**。项目范围请使用上面的统一页面，或后面的 `.mcp.json` 示例。

本地例子需要 Node/npm。准备练习目录，放入 `hello.txt`，内容写 `MCP demo ready`；记下绝对路径，目录内不放无关文件。

## 添加本地文件系统服务

按下表填写：

| 字段                              | 示例值          |
| ------------------------------- | ------------ |
| Server Name／名称                  | `docs-files` |
| Server Type／类型                  | `stdio`      |
| Command／命令                      | `npx`        |
| Arguments／参数，每行一个               | 下方三行         |
| Environment Variables／环境变量 JSON | `{}`         |

```text
-y
@modelcontextprotocol/server-filesystem
/absolute/path/to/mcp-demo
```

最后一行换成真实练习目录，例如 Windows 的 `C:/mcp-demo`。点击**添加服务器**，确认条目已启用，再新建测试会话。包名和目录规则见[官方文件系统服务](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem)。

## 添加远程 HTTP 服务

[Microsoft Learn 官方 MCP](https://learn.microsoft.com/en-us/training/support/mcp)采用 Streamable HTTP，不要求认证。新增一项：

| 字段               | 示例值                                   |
| ---------------- | ------------------------------------- |
| 名称               | `microsoft-learn`                     |
| 类型               | `HTTP`                                |
| URL              | `https://learn.microsoft.com/api/mcp` |
| Headers／请求头 JSON | `{}`                                  |
| 环境变量 JSON        | `{}`                                  |

保存后提问：“通过 microsoft-learn 查找微软创建 .NET 控制台应用的文档，返回官方来源链接。”这个地址直接在浏览器 GET 可能返回 405，应通过 MCP 验证。

## 理解表单与 JSON

| 字段      | 何时使用                                    |
| ------- | --------------------------------------- |
| stdio   | 启动本地进程，命令和参数分开填写                        |
| HTTP    | 远程 Streamable HTTP 地址                   |
| SSE     | 服务明确要求旧式 SSE 时选择，不因结果会流式输出就选 SSE        |
| Headers | 远程服务请求头；有认证要求时按服务规则填写 Authorization 等字段 |
| 环境变量    | 传给本地进程的变量，使用 JSON 对象和字符串值               |
| JSON 标签 | 填**单个服务器**配置，不放外层 `mcpServers`          |

例如远程项的 JSON 标签可填：

```json
{
  "type": "http",
  "url": "https://learn.microsoft.com/api/mcp"
}
```

## 只在一个项目使用

最直接的方式是打开**插件 → MCP**，选中项目，再通过**添加 → 手动添加**保存配置。保存后保持该项目选中，确认条目出现在对应范围。

需要用项目文件维护配置时，在项目根目录创建或合并 `.mcp.json`，保留文件中已有服务器：

```json
{
  "mcpServers": {
    "microsoft-learn": {
      "type": "http",
      "url": "https://learn.microsoft.com/api/mcp"
    }
  }
}
```

重新打开项目会话，核对条目属于该项目。项目文件需要外层 `mcpServers`，新增服务器弹窗的 JSON 标签不需要。不要把真实凭据提交进示例文件。

## 验证实际工具

对 `docs-files`，要求列出实际允许目录并读取 `hello.txt`；应看到练习目录及 `MCP demo ready`。对微软服务，检查工具来源和返回的官方文档链接。

文件系统服务还包含写入工具，客户端 Roots 也可能改变允许目录，应以实际返回值核对范围。服务器条目支持启停、编辑、重启和删除。

## 常见问题

| 现象         | 检查方法                     |
| ---------- | ------------------------ |
| 找不到命令      | 确认 Node/npm 已安装及实际程序路径   |
| JSON 无效    | 使用双引号、字符串值，不写注释或末尾逗号     |
| 远程 401/403 | 检查该服务需要的请求头和账号；微软示例不需要凭据 |
| 配置改变但工具没变  | 重连或重启条目，新建测试会话           |
| 同名工具重复     | 先确认服务器来源与作用域，再停用重复项      |

## 下一步

成套集成见[插件](https://onevium.com/zh/docs/plugins)，操作控制见[权限](https://onevium.com/zh/docs/permissions)，网络和工具开关见[设置参考](https://onevium.com/zh/docs/settings/reference)。