# 连接本地 MCP 进程

分清运行机器、可执行文件、参数与环境变量。

## 本地进程与远程服务的区别

STDIO MCP 由运行任务的机器启动子进程，通过标准输入输出交换消息。它需要本机依赖和文件权限。HTTP、SSE 连接的是一个已经运行的服务，不在这里启动程序。

桌面版的本地进程运行在桌面宿主，Web 版的本地进程运行在服务器环境。电脑里装好了 Node.js，不能证明服务器容器里也装好了。

## 开始前检查运行环境

确认服务要求的程序、版本、启动参数和必要环境变量。先在运行机器上确认可执行文件的位置，并准备一个只含教学材料的目录。不要把全部个人目录作为第一次测试范围。

如果只是让 Nexus 处理普通工作区文件，已有文件工具通常够用。以下示例用于学习 STDIO 配置，而不是要求每个人再安装一套文件工具。

## 示例服务与测试材料

示例使用官方 Filesystem MCP，提供文件读取等工具。它也有写入能力；本次练习只验证读取，并通过 `list_allowed_directories` 核对实际目录。安装和参数以[服务项目说明](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem)为准。

在自己选定的教学目录中新建 `sample.txt`，写入下面两行。

```text
这是一份 MCP 连接测试材料。
项目代号为 DOC-DEMO，暂不包含其他资料。
```

记下该目录的绝对路径。后文使用 `/path/to/nexus-mcp-demo` 表示它，填写时必须替换成实际路径。

## 拆分命令和参数

官方 npm 包为 `@modelcontextprotocol/server-filesystem`。使用 npx 时，需要运行机器已有 Node.js 和 npm，且能下载该包。

```sh
npx -y @modelcontextprotocol/server-filesystem /path/to/nexus-mcp-demo
```

在 **能力 → 连接器 → 自定义 MCP → 添加 MCP** 选择 STDIO，并拆成以下字段。

| 字段 | 内容 |
| --- | --- |
| 名称 | `demo-files` |
| 启动命令 | `npx`，必要时用其可执行文件的绝对路径 |
| 参数第 1 项 | `-y` |
| 参数第 2 项 | `@modelcontextprotocol/server-filesystem` |
| 参数第 3 项 | 教学目录的实际绝对路径 |
| 环境变量 | 此示例无需添加 |

![真实 Nexus App 中的 STDIO 命令、参数与环境变量字段](/images/docs/mcp-stdio-form.png)

每个参数单独一行，保持顺序。路径含空格时仍是一个参数，不再添加终端中用于分组的引号。不要把 `npx -y ...` 整段填进启动命令，也不要填 `cd ... && ...`；表单分别传入程序和参数，不是普通终端输入框。

## 环境变量如何编辑

其他服务需要 Key 时，在环境变量里添加名称和值。新增行两项都要填写，名称不能重复。配置已保存后，秘密值不会回显，保留该行并留空表示沿用旧值。

环境变量属于子进程配置，不要把 `KEY=value` 当成普通启动参数，除非服务文档明确这样要求。不需要的空行直接删掉。

## 为什么详情页没有工具列表

STDIO 服务只在用户运行环境中启动。详情页不会为了展示目录就用宿主身份执行你填写的程序，因此可能显示运行时读取的说明。这种状态本身不代表服务故障。

保存后启用到测试 Agent 或当前会话，在会话中验证实际调用。远程 MCP 的详情页读取目录流程不适用于这里。

## 验证目录与读取结果

```text
请使用 demo-files 服务，先查看 list_allowed_directories 的结果。
确认教学目录可访问后，读取其中的 sample.txt，逐字回复文件内容。
本次不要创建、修改、移动或删除任何文件。
```

检查工具记录中的服务名称，确认没有改用其他文件工具。输出应包含 `DOC-DEMO`。服务的实际允许目录以工具返回为准；客户端提供的目录能力可能影响服务最终采用的范围。

如果 Agent 只回答“配置好了”，还没有验证进程启动与协议交互。继续要求执行上述只读调用。

## 启动失败怎么定位

| 现象 | 原因方向 | 处理 |
| --- | --- | --- |
| 找不到 npx 或程序 | Nexus 的 PATH 与终端不同 | 填写可执行文件绝对路径 |
| 下载包失败 | npm 网络、代理或包名问题 | 在运行机器确认包能取得 |
| 进程启动后退出 | 参数、依赖或环境变量不完整 | 对照服务启动说明逐项检查 |
| 协议解析失败 | 服务把普通日志写入标准输出 | 服务日志应写入标准错误 |
| 文件访问被拒绝 | 工具允许目录或系统权限不符 | 核对实际允许目录和运行账号 |
| 电脑可用，Web 版失败 | 服务器缺少程序或挂载 | 在服务器重建同等依赖与路径 |

先修复启动，再修复文件访问。不要通过给 Agent 更宽的审批模式来解决缺少程序或错误路径。

## 长期使用与迁移

确认服务版本后，可按自己的依赖管理方式固定版本，避免每次启动都依赖不受控的最新版本。迁移到服务器时重新核对程序路径、容器挂载和秘密字段；复制一份桌面配置不会自动安装这些依赖。

停用或删除前检查依赖它的 Agent 和定时任务。需要通过网络访问已运行服务时，使用[远程 MCP](/docs/mcp-remote)。