Muse Code 怎么接 MCP？从配置到第一次查资料

01｜先看你正在用哪个 Muse

搜 Muse MCP，会看到好几种东西。有的是让其他 AI 调用 Muse 的社区桥接，有的是给 Muse Code 加外部工具。它们的配置方向不同，别拿到一个命令就往自己的手机应用里找入口。

这篇讲终端里的 Muse Code。我们核对了 Meta 的扩展手册和开发者预览文档，后者注明示例来自 1.3.0。先在你的终端看 muse --version，再看 muse mcp --help。版本或帮助内容不同，就打开对应版本文档，别把预览版规则当成所有旧版的固定行为。

先准备一个你有权使用、已经知道地址和认证方式的 MCP 服务。下面用团队文档服务作练习，地址是占位符，本文没有声称实际连过你的服务。

02｜先连一个服务，搞清谁会执行工具

MCP 把外部服务的工具交给 Muse Code 使用，例如搜索团队文档。stdio 表示 Muse Code 启动本机程序；streamable HTTP 表示它连接一个服务地址。服务提供者需要告诉你用哪种方式、有什么工具、访问哪些数据。

官方文档特别说明，MCP 工具不受 Muse Code 自身 shell 沙箱的隔离。接入时保留审批规则，选你信任的服务，并从只读查询开始。文档中的提示词也不能替代服务端的访问范围。

03｜把远程服务放进用户配置

用户配置位置是 $XDG_CONFIG_HOME/muse/settings.json；没设置 XDG_CONFIG_HOME 时，文档给出的默认位置是 ~/.config/muse/settings.json。先备份已有文件，把新的服务合并到原来的配置中。别用一份最小示例覆盖你的其他设置。

下面是一份最小示例。docs.example.com 是保留的示例域名，必须替换成服务提供者给你的真实 MCP 地址。team-docs 是自己选的名称，后面的登录命令用同一个名称。

{ "schema_version": 1, "mcpServers": { "team-docs": { "type": "streamable-http", "url": "https://docs.example.com/mcp", "required": false } } }

用户 settings.json 保留 schema_version 为 1。不要同时放 mcpServers 和旧拼法 mcp_servers，也别在同一服务里混用 type 与 transport。示例明确写 required 为 false，先接通一个可选服务，再决定工作是否必须依赖它。

04｜需要登录时，在终端完成 OAuth

如果服务要求 OAuth，在终端执行 muse mcp login team-docs。阅读浏览器打开的服务域名、账号和授权范围，确认后完成登录。OAuth 回调和令牌不需要贴进 Muse 对话，也不要截进公开教程。

1.3.0 预览文档说明，这个登录命令针对用户 settings.json 中的 streamable HTTP 服务。只写在项目 .mcp.json 的条目、stdio 服务或已经配置静态 Authorization 请求头的服务，不能按这条路径登录。遇到拒绝提示，先检查配置种类。

05｜重开进程，再用 /mcp 看清工具

保存配置后，重新启动一个 muse 进程。在交互会话输入 /mcp，检查服务名称、状态、工具列表和错误信息。文档说明，配置在进程启动时读取；在旧进程里 /clear 或 /new 并不会重载配置。OAuth 登录完成后被正在运行的进程识别，是另一件事。

看到 connected 还要看看工具是不是你要的。第一次可以要求“只用 team-docs 查询我指定的公开测试文档，返回标题和原文位置，不修改或创建任何内容”。测试问题和预期答案由你提供，再对照原文核查。工具名和参数按 /mcp 的实际列表来，不猜一个 search 命令。

06｜本机服务与项目文件，另看这两处

如果提供者给的是 stdio 服务，就把它的真实可执行程序写入 command，把各个参数分别放进 args。command 直接执行，不经过 shell。需要的 token 或运行环境变量按服务说明放进 env；不要把一整段带管道的安装命令当作 command。

项目共享配置可以放 .mcp.json，但 Muse Code 只读取可信工作区里的文件。用户配置与项目配置还会合并，同名服务可能被更靠近当前目录的配置改掉。第一次在陌生仓库里接入时，先读文件，核对实际地址和程序路径。

预览文档还指出，${VAR} 替换只发生在 stdio 的 env 值里，HTTP headers 不会替换。某个字段写了环境变量并不意味着运行时已经带上了你的凭据。

07｜连接失败，从具体报错往回找

• 完全没出现服务。确认保存的位置和服务名，重启进程；项目配置还要检查工作区信任。
• settings.json 配置错误。检查 JSON 格式、schema_version、重复的新旧字段和缺失环境变量。
• stdio 程序不可用。核对可执行程序、参数和工作目录，先按服务提供者的方法确认它能启动。
• 401 或要求 OAuth。核对所登录的账号和服务，按错误给出的 muse mcp login 命令处理。
• 超时或 tools 列表不对。检查服务本身的状态和文档，别通过放开全部权限来解决连接问题。

08｜不用了，分别处理连接与授权

远程 OAuth 服务可以执行 muse mcp logout team-docs。官方说明它会移除本地凭据，并尽力请求远端撤销；不要把成功退出理解成服务端已经删除所有历史数据。必要时到服务提供者的账号授权页面检查。

停止后续连接，可以将该配置条目的 enabled 设为 false，或移除不再需要的条目，然后重新启动 Muse Code。再用 /mcp 确认状态。这样你知道收回的是哪条连接，而不只是让它“忘掉这个工具”。想复用一整套工作步骤，再看 Muse Skills 教程。