连接本地 MCP 进程

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

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

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

开始前检查运行环境

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

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

示例服务与测试材料

示例使用官方 Filesystem MCP，提供文件读取等工具。它也有写入能力；本次练习只验证读取，并通过 list_allowed_directories 核对实际目录。安装和参数以服务项目说明为准。

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

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

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

拆分命令和参数

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

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

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

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

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

环境变量如何编辑

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

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

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

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

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

验证目录与读取结果

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

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

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

启动失败怎么定位

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

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

长期使用与迁移

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

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