OmniRush.ai MCP接入实战：一键连接本地工具、远程服务与OAuth登录，扩展AI智能体能力
【免费下载链接】omnirush-guiA desktop coding agent with free access to frontier models.项目地址: https://gitcode.com/gh_mirrors/om/omnirush-gui
OmniRush.ai 是一款桌面端 AI 编程智能体（coding agent），自带免费的前沿大模型。通过MCP接入（Model Context Protocol，模型上下文协议），你可以一键把本地命令行工具、远程 MCP 服务和需要 OAuth 登录的第三方平台（如 Notion、Linear、Stripe）接到智能体上，让它直接调用你的数据库、工单和文档。本文将带你用最少的步骤完成三种接入方式，并学会排查常见问题。
为什么需要 MCP：给 AI 智能体装上"手脚"
默认情况下，AI 智能体只能读写文件和执行命令。接入 MCP 之后，模型可以把 MCP 服务器暴露的工具以<服务器名>_<工具名>的形式直接调用，例如：
- 查询 Linear 上的工单并自动更新状态
- 让 Stripe 返回订阅数据辅助回答
- 读取本地数据库服务器的统计信息
所有模型（内置的 omnirush.ai 模型和你自己添加的外部模型）共享同一套 MCP 工具，配置一次即可全局生效。原理与完整机制可以参考官方文档 docs/skills-and-mcp.md。
三种接入方式总览
| 方式 | 配置形态 | 适用场景 |
|---|---|---|
| 本地（stdio） | 一条命令行，如node /path/server.mjs | 自己写或本机运行的 MCP 服务器 |
| 远程（HTTP） | 一个https://URL | 托管在云上的 MCP 服务 |
| 托管 OAuth | 远程 URL + 一键 Sign in | 需要账号登录的第三方服务（Notion、Linear、Stripe 等） |
一键添加本地 MCP 服务器（stdio 命令行）
- 打开Settings（设置）→ Library（库），点击Add（添加），选择MCP server (local)。
- 填写名称（只允许字母数字和
-/_），填入命令行。 - 保存后卡片状态变为Ready，说明握手（
initialize→tools/list）已完成，工具就绪。
💡 小贴士：桌面应用使用的 PATH 不是你的 shell PATH，本地命令请写绝对路径，例如
/usr/local/bin/node /path/to/server.mjs，避免 "Offline" 报错。
暂停/恢复：直接在卡片上切换开关即可，无需删除重建。
连接远程 MCP 服务（HTTP URL 方式）
流程与本地方式几乎一致，区别只是把命令行换成 URL：
- Settings → Library → Add → MCP server (remote)。
- URL 必须以
http://或https://开头且不含空格；可在高级选项中附加自定义请求头（如 API Key）。 - 保存后应用会向本地服务器注册并立即同步到引擎，卡片显示Ready即接入成功。
如果某个远程服务要求登录，卡片会显示Needs sign-in——此时就用下面的 OAuth 方式。
OAuth 登录：免手动的第三方服务授权
OmniRush.ai 的Managed OAuth（托管 OAuth）把繁琐的登录流程全部自动化：
- 添加远程 MCP 后展开OmniRush.ai-managed OAuth，可留空让系统自动注册；
- 应用自动完成 OAuth 发现（RFC 9728）、动态客户端注册（DCR）、PKCE 授权和 token 交换；
- 浏览器弹出授权页，点确认后回到应用即完成接入：
安全性设计是这套方案的最大亮点（详见 docs/features/local-managed-mcp-oauth/README.md）：
- access token、refresh token、client secret 全部以AES-256-GCM 加密存储在本机安全存储中；
- 模型引擎通过本地回环网关调用工具，永远拿不到你的凭据；
- 网关令牌与每个工作区绑定，每次重启自动轮换。
连接成功后，可以点View tools查看该服务暴露给智能体的工具目录：
云端团队场景：组织级 MCP Connections 管理
如果登录了 OmniRush.ai Cloud 组织，管理员可以在 Web 控制台集中管理 MCP Connections：连接一次，全组织可用；内置Notion / Linear / Stripe / Sentry / Context7快捷模板，点一下即可添加。
- 支持"个人账号"或"组织统一账号"两种授权模式；
- 成员只看到自己有权使用的工具，权限由组织策略控制；
- 删除连接会同时清理 token、授权状态和插件绑定，干净不留痕。
服务端实现位于 packages/enterprise-mcp-client/，云端管理流程文档见 docs/external-mcp-oauth.md。
常见问题排查：状态卡片含义速查
| 卡片状态 | 含义 | 处理方法 |
|---|---|---|
| Ready | 已连接，工具已列出 | 无需处理 |
| Needs sign-in | 远程服务要求 OAuth 登录 | 点卡片上的 Sign in |
| Paused | 被手动暂停 | 切换开关恢复 |
| Offline / Error | 命令不存在、URL 错误或网络问题 | 检查绝对路径 / HTTPS / 防火墙 |
其他高频问题（完整清单见 docs/skills-and-mcp.md 的 Troubleshooting 章节）：
- 🔄刚添加/修改后模型感知不到：引擎在会话空闲时同步，等待运行结束或在Settings → Advanced中重启引擎；
- ⚠️注册被推迟（503）：有会话正在运行，引擎空闲后会自动重试，无需手动干预；
- 🗑️删除后工具还"残留"：已开始的回合会保留旧工具集，回合结束后自动失效。
相关源码位置：界面在 apps/app/src/react-app/domains/settings/pages/mcp-view.tsx，库入口在 apps/app/src/react-app/domains/settings/pages/extensions-view.tsx。
延伸阅读：让智能体能力再进一步
- 🎛️UI 控制 MCP：OmniRush.ai 自身也对外暴露 MCP 服务器，HandsFree、Claude Desktop 等客户端可以按"动作名"直接操作它的界面，见 docs/mcp-ui-control-profile.md；
- 🖼️MCP Apps 内嵌界面：MCP 工具结果可以直接渲染成交互式 HTML 卡片，见 docs/features/mcp-apps-host/README.md；
- 📚Skills（技能）：与 MCP 互补，用 Markdown 教智能体固定流程，与 MCP 工具共享同一模型上下文。
如果想在源码层面学习实现细节，可以克隆仓库研读：
git clone https://gitcode.com/gh_mirrors/om/omnirush-gui现在打开你的 OmniRush.ai，去 Library 里添加第一个 MCP 服务器吧——从连接一个本地工具开始，你的智能体马上就能"看见"更多世界。🚀
【免费下载链接】omnirush-guiA desktop coding agent with free access to frontier models.项目地址: https://gitcode.com/gh_mirrors/om/omnirush-gui
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
