ThinkRail 是一款轻量级 AI 编程 IDE，内置了完整的 MCP（Model Context Protocol）服务器管理能力。本文将从零带你完成 MCP 服务器配置：用 3 步添加第一个服务器、看懂 5 个内置预设（Context7、DeepWiki、Linear、Sentry、Playwright），并一次讲透 ThinkRail 独有的双层审批机制——让 AI 在改动任何数据之前，先征得你的同意。

为什么你需要配置 MCP 服务器

MCP 服务器相当于给 AI 装上的"外接插件"：

• 📚查文档：Context7 可以拉取最新的库和框架文档，避免模型"记错"API
• 🐛接工作流：Linear、Sentry 让 AI 直接读取你的 issue 和报错
• 🌐操作浏览器：Playwright 让 AI 真实打开网页、执行端到端验证

ThinkRail 基于 pi 内置的 MCP 引擎运行这些服务器，配置入口只有一个：Settings › MCP servers。

一分钟找到配置入口

所有 MCP 相关操作都在设置面板的Agent分组里（包含 Models、Providers、MCP servers、Prompt templates）。打开它需要先在 ThinkRail 中激活一个工作区，否则页面会提示 "Open a workspace to manage its MCP servers"。

每个服务器行都会显示：状态圆点与原因、User / Project 作用域徽章、HTTP / stdio 传输徽章、曝光（exposure）菜单和启用开关。完整的面板逻辑见 McpSettings.tsx。

MCP 服务器配置在哪个文件？

ThinkRail 沿用 pi 的两级mcp.json配置：

最小可用配置长这样（两种传输方式二选一）：

{ "mcpServers": { "docs": { "url": "https://example.com/mcp" }, "browser": { "command": "npx", "args": ["-y", "@playwright/mcp@0.0.83"] } } }

💡 个人使用的服务器放用户级文件；只有当你要把服务器分享给整个仓库时才写入.pi/mcp.json。

快速上手：5 个内置预设详解

打开 Settings › MCP servers 点击Add，第一档就是内置预设——5 个经过验证、版本锁定的"一键安装"选项，源码定义在 mcpPresets.ts：

几个新手最容易忽略的细节：

1. Context7 和 DeepWiki使用exposure: "direct"，工具会像内置工具一样预先声明给模型，连接即用。
2. Linear默认走厂商只读端点/mcp/readonly，添加后在服务器行的Sign in完成 OAuth 登录即可。
3. Sentry标记为可修改数据——每次写操作都会触发审批弹窗（后文细讲）。
4. Playwright以"禁用状态"加入用户级配置，同时为当前项目写入启用覆盖，即optInPerProject：它只在你主动选择的项目里运行，且绝不污染仓库文件。

预设下方还有一个Use recipe选项，会填入 GitHub 的只读端点配方（基于gh auth token），因为它依赖本机 GitHub CLI 登录状态，所以被设计成"配方"而非预设。

手动添加：表单、Paste JSON 与命名规则

Add对话框共三档，逐档灵活：

• 预设（上面 5 个）
• 短表单：填服务器名、选择传输方式（stdio 填 command + args，http 填 URL）、按需添加 env / headers、选作用域
• Paste JSON：直接粘贴mcpServers配置块，逐个服务器预览校验，SSE 或不合规条目会被标红

表单校验非常严格（见 mcpEntries.ts），记住三条规则即可：

• 名称只能用字母、数字、-和_，且-/_互换的同名会互相冲突
• SSE 传输不受支持，请改用服务器的 streamable HTTP 地址（通常以/mcp结尾）
• 包版本务必锁定（如@playwright/mcp@0.0.83），不要写@latest

密钥怎么填？只存引用，不存明文

这是 ThinkRail MCP 配置最重要的安全设计：表单里的 env 和 header 值只接受两种引用：

• ${GITHUB_TOKEN}—— 从宿主环境变量读取
• !gh auth token—— 每次聊天连接时执行命令取其输出（要求命令足够快，比如读缓存的 token）

任何明文密钥都会被直接拒绝，粘贴到 URL 里的凭据同样会被拦截并提示你改用Authorization: Bearer ${TOKEN}这类 header。这样mcp.json可以放心提交进 git。

审批机制全解析：ThinkRail 如何替你把关

ThinkRail 的审批分两层：服务器级审批管"这个仓库自带的 MCP 服务器能不能跑"，工具调用级审批管"这一次调用能不能动数据"。

第一层：仓库自带服务器的"Review & approve"

如果同事在.pi/mcp.json里放了一个 MCP 服务器，ThinkRail不会直接启动它。你会在 Settings 里看到一行Review & approve按钮，点击后它会列出：

• 将要执行的完整命令行或 URL（凭据参数显示为***）
• 工作目录
• 每一个!command
• 所有 env / header 名称及其引用

确认后 ThinkRail 用该条目的指纹（SHA-256）+ 项目记录记录批准。这意味着：

• 仓库不能"自带预批准"——授权存于项目记录，而不是.pi/mcp.json
• 条目内容任何改动都会使审批失效，需要重新审查
• 项目未被信任（trust）时，.pi/mcp.json根本不会被加载

第二层：工具调用的 4 个选项

当 AI 调用一个可能修改数据的 MCP 工具时，问题会直接显示在聊天里的工具卡片上，并完整列出本次调用的参数：

四个按钮按风险从低到高排列：Deny · Allow once · Allow in this chat · Always allow：

几个关键细节：

• 声明了readOnlyHint: true的只读工具不会弹审批
• Always allow只信任那一个工具，且授权存放在项目记录里；一旦服务器的 command 或 URL 发生变化，授权自动失效、下次重新询问
• 想收回授权？去Settings › MCP servers管理即可，已打开的聊天会在下一次调用时立刻生效
• 聊天中直接发送消息即可取消正在等待的审批弹窗

完整的引擎与守卫实现见 agent/mcp/SPEC.md，AI 助手管理 MCP 服务器的行为准则见 managing-mcp-servers/SKILL.md。

常见问题速查

• 改了mcp.json要重启吗？不用。空闲聊天会自动热加载，忙碌中的聊天会在空闲时自动生效。
• 连接失败怎么办？服务器行会出现Reconnect和Show log，日志内容已由宿主自动脱敏（token、Bearer 凭据等被掩码）。
• 保存失败报错？所有写操作都携带渲染时的指纹做乐观锁，报错通常说明另一个客户端或 git checkout 改动了文件——刷新后从最新条目重试即可。
• 项目级条目想改？用Edit以 JSON 方式编辑（明文值显示为<literal value hidden>，占位标记保留原值，新值必须是引用）。

相关实现与测试：McpServerDialogs.tsx、mcp-settings.spec.ts。

小结

• 配置入口：Settings › MCP servers，两级mcp.json（用户级 + 项目级）
• 新手路径：预设一键添加 → Sign in（OAuth 服务器）→ 聊天中按需审批
• 安全底线：密钥只存${VAR}/!command引用；仓库服务器先审批后运行；写操作先问再动

按这套流程走完，你的 ThinkRail 就拥有了既方便又可控的 MCP 能力。