如何一次定义 MCP 服务器，并在 Claude Code、Codex 和 OpenCode 中使用（跨所有机器）
一种实用的方法：不再把 MCP JSON 复制粘贴到三个不同的工具里，让各个提供商和机器拥有一致的工具集。
- CLI
- 0.2.17
- 预览 ref
- a2c45c8
如果你曾经“认真”配置过 MCP 服务器，大概经历过这样的流程：
- 把 MCP JSON 粘贴到 Claude Code
- 把一份略有不同的 MCP JSON 粘贴到 Codex
- 发现 OpenCode 用的是另一个位置
- 在笔记本和服务器上再做一遍
这能用。
但这也是会话行为因所在机器不同而不同的原因。
你真正想要的是：
- 工具只定义一次
- 让它们一致可用
- 同时让机器专属的工具保持机器专属
本指南讲的就是这套工作流。
简要总结
- 先确定你要用 MCP 做什么（浏览器自动化、GitHub、文档搜索、内部工具）。
- 常见的失败模式是配置漂移：不同机器或提供商上的 MCP JSON 不一样。
- 更好的模型是“一个工具库 + 明确的应用范围”。
- 在 Happier 中，你可以一次定义 MCP 服务器，检测现有的提供商 MCP 配置，预览某个会话实际可用的工具集，并把服务器应用到：
- 所有机器
- 一台机器
- 一台机器上的一个工作区
问题所在
MCP 是个好主意，但简单粗暴的配置方式很脆弱：
- 多个配置文件
- 多台机器
- 多个提供商
所以问题不是“我能不能运行 MCP？”
而是：
我能不能让工具集一致到足以信任它？
常见做法及其权衡
- 到处复制粘贴 JSON：直到你忘了某台机器之前都能用。
- 只在一个提供商上配置：那就失去了可移植性的意义。
- 只按项目保留工具：某些情况下不错，但对 GitHub 这类通用工具很痛苦。
如果你第一次接触 Happier
如果你之前没见过 Happier：它是一款开源配套应用（移动端/网页/桌面），用于跨机器运行 Claude Code、Codex 和 OpenCode 等会话。
这里相关的是：它提供一个统一的地方来管理 MCP 服务器并一致地应用它们。
开始设置：
- 如何在手机上使用 Happier
- GitHub: https://github.com/happier-dev/happier
- 安装/下载: https://github.com/happier-dev/happier#how-it-works
- Discord（社区与支持）: https://discord.gg/W6Pb8KuHfg
可行的工作流
1) 把工具当作一个库，而不是一堆 JSON
一旦你有不止一台机器，MCP 配置就成了基础设施。
所以把它当作一个库：
- 已保存
- 可审阅
- 有范围
2) 用“已配置 / 已检测到 / 预览”来思考
在 Happier 中，MCP 服务器分为三个标签页：
- 已配置（Configured）：你在应用中管理的服务器
- 已检测到（Detected）：在提供商原生配置文件（Claude、Codex、OpenCode）中找到的服务器
- 预览（Preview）：某个后端 + 机器 + 工作区实际可用的工具集
预览是关键。
它回答的是：“这个会话实际能看到什么？”
3) 应用正确的范围：所有机器 / 一台机器 / 一个工作区
大多数漂移来自没有明确范围。
可行的规则：
- 远程 HTTP/SSE 服务器 → 所有机器（All machines）
- 通过
npx安装的本地 stdio 服务器 → 机器（Machine，一台） - 项目本地的服务器 → 工作区（Workspace，一台机器上的一个）
4) 不要把机密放进 JSON（别再泄露令牌）
每次你把令牌直接粘贴进 MCP JSON，就会造成机密扩散：
- 进入 shell 历史
- 进入 dotfiles
- 出现在截图里
- 最终不小心进入某个仓库
更好的做法是：
- 一个只保存一次机密的地方
- 一种无需嵌入、就能在 MCP 配置中引用机密的方式
- 一种在多台机器间安全复用的方式
Happier 为 MCP 服务器的请求头/环境变量支持三种值来源：
- 已保存的机密（Saved Secrets，推荐）
- 机器环境变量引用，如
${MY_TOKEN} - 纯文本（除非确实不敏感，否则避免）
“已保存的机密”这个选项让多机器 MCP 轻松了很多。
机密只需绑定一次，MCP 服务器定义就能在各台机器上保持一致。
完整示例：带 Authorization 请求头的 GitHub MCP 服务器（已保存的密钥）
一个很常见的模式是远程 MCP 服务器（HTTP/SSE）需要：
Authorization: Bearer <token>
下面是从头到尾、完全不用把令牌粘贴进 JSON 的设置方法。
第 1 步：创建 GitHub 令牌
按所需的最小权限范围创建 GitHub 令牌（classic PAT 或 fine-grained 令牌）。
（需要哪些范围取决于你打算调用的 MCP 工具：仓库、issue、PR 等。）
第 2 步：把令牌保存为已保存的机密
在 Happier 中：
- 设置（Settings）→ 已保存的机密（Saved Secrets）（或 设置（Settings）→ 机密（Secrets））
- 新的机密（New secret）
- 起一个你认得的名字，例如
github_pat_work - 粘贴令牌的值
现在这个值存放在 Happier 加密的设置存储中，而不是你的配置文件里。
第 3 步：在 Happier 中添加 GitHub MCP 服务器
在 Happier 中：
- 设置（Settings）→ MCP 服务器（MCP servers）→ 添加服务器（Add server）
- 选择 远程 HTTP（Remote HTTP）或 远程 SSE（Remote SSE）（取决于服务器支持哪种）
- 起个名字，例如
github
然后设置：
- 适用于（Applies to）：通常是 所有机器（All machines）（因为远程服务器可移植）
第 4 步：用已保存的密钥设置 Authorization 请求头
在 MCP 服务器配置中添加一个请求头：
- 请求头名称：
Authorization - 请求头值：
Bearer <your-saved-secret>
关键在于如何引用机密：
- 不要粘贴令牌的值
- 在请求头值字段中选择或引用你的已保存的机密（例如
github_pat_work）
在请求头编辑器中，你可以选择值来源：
- 字面量（Literal，纯文本）
- 已保存的密钥（Saved Secret）
选择 已保存的密钥 后，Happier 保存的是对机密的引用（而不是机密的值），并在测试或启动 MCP 服务器时于运行时解析它。
第 5 步：先测试，再预览
- 用 测试（Test）确认 Happier 能够：
- 解析已保存的机密引用，
- 连接或启动服务器，
- 并列出工具。
- 用 预览（Preview）（后端 + 机器 + 工作区）确认你关心的会话中确实有 GitHub 工具。
如果测试成功，但预览显示该会话有 0 个工具，基本都是范围不匹配（所有机器 / 机器 / 工作区）。
（可选）为什么可行（实现细节）
在环境变量或请求头编辑器中选择 已保存的密钥 时，界面保存的是一个小的带类型引用（机密 ID），而不是机密本身。
所以你可以：
- 在多台机器间复用同一个 MCP 服务器定义，而不用到处复制令牌
- 在一个地方轮换机密的值，而不用碰 MCP JSON
使用时不需要知道内部类型名称，但这正是这个模型稳健的原因。
示例：需要环境变量的本地 stdio MCP 服务器
对于 stdio 服务器（本地命令），很多 README 会让你设置环境变量。
诀窍是避免变成“每个人都在 shell rc 文件里永久 export 机密”。
更好的模式是：
- 把值作为已保存的机密保存一次
- 把它绑定到该服务器所需的环境变量名
5) 定义自定义 MCP 服务器（本地 stdio）
Happier 支持本地命令 MCP 服务器（stdio）。
在 设置（Settings）→ MCP 服务器（MCP servers）→ 添加服务器（Add server） 中，你可以：
- 粘贴一条命令行（Happier 会拆分命令和参数）
- 选择范围（本地安装的通常选 机器（Machine））
- 添加环境变量（优先用已保存的机密）
然后用 测试 确认它能启动并列出工具。
6) 定义自定义 MCP 服务器（远程 HTTP/SSE）
对于远程服务器：
- 把范围设为 所有机器
- 添加请求头（优先用已保存的机密）
- 测试一次
7) 开始重要会话前，预览实际可用的工具集
如果你只从本指南中带走一个习惯，就选这个：
- 用 预览 查看会话实际能拿到哪些工具
预览会合并显示：
- 默认应用的、由 Happier 管理的 MCP 服务器
- 针对该后端或上下文检测到的提供商原生 MCP 服务器
- 可用但当前未应用的服务器
它把“这个会话为什么没有 GitHub 工具？”变成一个 10 秒就能回答的问题。
8) 信任服务器之前先测试
一个节省时间的小习惯：
- 测试 MCP 服务器
- 确认它能列出工具
这能尽早发现错误的命令行和缺失的安装。
为什么可行（以及什么会出问题）
这套设置可行，是因为它把通常纠缠在一起的三件事分开了：
- 定义（MCP 服务器是什么）
- 范围（应该在哪里应用）
- 机密（如何认证）
出问题时，通常是以下之一：
- 范围不对（所有机器 / 机器）
- 本地 stdio 服务器在该机器上没有安装
- 机密无法解析（已保存的机密没有绑定、环境变量缺失）
- 提供商原生的 MCP 配置遮盖了你预期的配置
故障排查
MCP 服务器无法启动
- 检查命令行
- 确认所选机器上存在该命令
- 如果是
npx，确认该机器上安装了 Node 且可用
工具出现在“已配置”中，但不在会话中
- 检查该后端 + 机器 + 工作区的 预览
- 确认“适用于”的范围与该会话匹配
认证失败（401/403）
- 用已保存的机密替换内联令牌
- 确认请求头或环境变量正确引用了已保存的机密
- 重新测试服务器