MCP 协议集成与各 Agent 客户端配置

面向 Claude Code 插件、Cursor、Codex、Pi/Hermes、skills.sh、托管式 MCP 与 CI/CD 环境的标准化配置指南。

OriginAI 提供了三种将各类编码 Agent 无缝接入的通道：云端托管式 MCP 服务、Claude Code 官方插件（本地 stdio MCP 桥接与 Skill 融合），以及面向全行业主流编码 Agent 的 CLI 与 Skill 规范文件。所有通道在系统底层均统一对齐相同的访问令牌鉴权模型，遵循完全一致的行为准则——读取默认返回最新已发布 Release 快照，写入在首次发布后严格受控转为变更请求。

必读核心：身份鉴权模型分工

交互主体与场景	推荐身份认证机制
人类开发者（日常推荐）	执行 `npx originai login`，凭据安全持久化于 `~/.origin/settings.json`。
Claude Code 官方插件	通过本地 stdio 调起的 `npx originai mcp` 服务运行（自动复用本地登录凭据）。
Skill / CLI 驱动的 Agent（Codex、Pi、Hermes、OpenCode、skills.sh）	复用相同的本地登录凭据；Agent 底层自动执行 `npx originai …` 命令。
CI/CD 流水线 / 纯远程 MCP 托管宿主	通过环境变量注入 `ORIGIN_TOKEN=oat_…`（在 Web 控制台系统设置中生成）。

在日常开发中，切勿将“创建访问令牌并手动导出 ORIGIN_TOKEN”视作默认的入门操作——该模式专为 CI/CD 自动化流水线与高级集成场景设计。交互式开发仅需直接登录即可，且严禁将包含 oat_ 的明文密钥提交至公开代码仓库。详见个人访问令牌指南。

公开远程托管端点（高级场景）

https://mcp.getoriginai.com

通信传输协议：Streamable HTTP（兼容 MCP 2025-03-26 标准）。
鉴权报头格式：Authorization: Bearer oat_…。
该域名由 Cloudflare 全球边缘反向代理统一驱动，客户端无需直接穿透访问 Supabase 基础设施端点。

MCP 可用工具清单速查

工具标识	核心功能与运作说明
`whoami`	查询当前访问令牌对应的所有者身份及名下项目概况。
`list_projects`	列举当前有权访问的项目清单，附带各项目最新的已发布 Release 版本哈希。
`create_project`	创建一个全新的空白项目（受当前套餐配额约束）。
`list_documents`	检索指定项目的文件树（默认返回最新已发布的 Release 快照）。
`get_document`	提取指定文件的完整正文内容。
`get_diff`	获取两个版本哈希之间的统合规格差异（Diff），支持按需嵌入全量上下文。
`grep_documents` / `find_documents`	在规格库中执行内容正则匹配检索或按文件名筛选文档。
`write_document` / `delete_document` / `delete_documents`	规格文档的增删改；在项目首次发布后调用，将自动创建或追加至变更请求（返回 `suggested: true` 及 `proposal_id`）。系统无需独立的 `create_change_request` 工具。通过 `proposal_id` 或 `new_proposal` 控制追加或新开。可选传入 `require_suggest: true`：若目标项目仍允许直接写工作区时强制返回 409 拒绝直接覆写。
`list_proposals` / `get_proposal` / `get_proposal_diff` / `describe_proposal` / `submit_proposal` / `commit_proposal`	变更请求全生命周期闭环。`list_proposals` 包含 `decided_items[]`、历史驳回原因 `dismiss_reason`，以及相对于最新版本的落后标识 `behind_latest`。`describe_proposal` 用于沉淀业务意图与架构权衡。在实现特定变更请求时调用 `get_proposal_diff`。
`comment_proposal` / `list_proposal_comments` / `list_proposal_reviews`	在变更请求讨论流中进行协作交流；读取 Ready / Not ready 审查结论（Agent 严禁自主敲定最终结论）。
`sync_origin_json`	返回在完成已发布版本实现后应当回写至本地 `.origin.json` 的指针结构。由 Agent 自行将 `origin_json` 写入本地文件——工具本身不直接越权操作宿主文件系统。
`list_webhooks` / `create_webhook` / `delete_webhook`	出站 Webhook 事件订阅管理：支持监听 `release.published`、`proposal.decided` 及 `proposal.commented` 等生命周期事件。
`validate`	校验 RPML 语法的合规性（支持通过内联 `source` 字符串或指定 `file_id` 触发）。
`search_shots` / `get_shot` / `list_shot_facets`	检索官方精选的标准设计 Shot（涵盖信息架构与推荐 RPML 结构）。在生成新界面前推荐主动调用参考。

变更请求的标准创建闭环

系统底层内核与 API 统一使用 *_proposal 命名。在项目发布首个 Release 之后的标准交互步骤：

调用 list_proposals（传参 status: "all"）了解历史背景与驳回原因。
运行 validate 校验语法，随后调用 write_document（首次暂存写入会自动创建该变更请求）。
调用 describe_proposal 补全上下文：包括关联 Issue（title、note）以及设计决策与变更日志 Decisions/Changelog（rationale）。
调用 submit_proposal 标记就绪。注意：Agent 严禁自审自批或自行记录 Ready 结论。

在实现变更请求时，优先调用 get_proposal_diff；在对齐已发布版本时，调用 get_diff。代码实现并测试通过后，调用 sync_origin_json 并将返回的元数据回写至本地 .origin.json，或在终端执行 npx originai sync。请注意：sync / sync_origin_json 仅在检测到全新 Release 哈希生成后，才会清除本地配置文件中的 proposal_id。

主流 Agent 客户端安装与集成指引

Claude Code 官方插件（强烈推荐）

npx originai login

在 Claude Code 交互会话中执行插件安装：

/plugin marketplace add 21stware/originai-context
/plugin install origin@origin-claude-marketplace

若在本地私有 monorepo 环境中进行扩展开发，可直接指定本地目录加载：

claude --plugin-dir /path/to/origin/packages/claude-plugin

随后在你的应用代码仓库中完成关联与健康检查：

npx originai link --project <project-id>
npx originai doctor

插件内置的 .mcp.json 会自动拉起一个本地 stdio MCP 桥接服务：

{
  "mcpServers": {
    "origin": {
      "command": "npx",
      "args": ["-y", "originai", "mcp"]
    }
  }
}

在日常使用 Claude Code 时，完全不需要在环境中手动 export ORIGIN_TOKEN。

Cursor

npx originai login
npx originai link --project <project-id> --cursor --skill
npx originai mcp config --cursor

将命令打印出的 JSON 配置块直接粘贴至 Cursor 的 MCP Settings 面板中——本地 stdio 桥接服务会自动复用你的本地登录凭据。基于 ORIGIN_TOKEN 的远程 HTTP MCP 模式可按需用于无头自动化流水线。

OpenAI Codex

npx originai login
npx originai link --project <project-id> --codex --skill

Codex Agent 会严格基于本地生成的 AGENTS.md 规则与 Skill 规范，以执行 CLI 命令的方式开展协同。若你的 Codex 宿主环境原生支持 MCP，亦可按需挂载。

Pi / Hermes / OpenCode（标准 Agent Skills 规范）

npx originai login
npx originai link --project <project-id> --skill

该命令将在本地仓库部署 .agents/skills/origin-product-spec-management/ 目录。Agent 默认使用 CLI 进行交互，MCP 支持作为可选扩展。

skills.sh / 公开 Agent Skills 市场 / Well-known 端点

通过 GitHub 来源安装（配合 npx skills add 工具）：

npx skills add 21stware/originai-context
# 仓库内部的标准 Skill 存放路径为：skills/origin-product-spec-management/

或直接从官方站点的 Well-known 发现端点安装：

https://getoriginai.com/.well-known/agent-skills/index.json
npx skills add https://getoriginai.com

完成 Skill 安装后，依然需要进行标准的授权与项目绑定两步走：

npx originai login
在应用代码仓库中执行 npx originai link --project <id>

官方 Skill 规范已经内置了“MCP 协议优先，CLI 命令兜底”的鲁棒回退策略，且规范正文中绝不硬编码任何敏感密钥。

Claude Code 纯规则文件模式（不安装插件）

npx originai login
npx originai link --project <project-id> --claude-code --skill
# 可选步骤：执行 npx originai mcp config --claude 生成配置

远程 HTTP MCP 接入模式（适用于任意支持 HTTP 传输的宿主环境）

export ORIGIN_TOKEN=oat_…

{
  "mcpServers": {
    "origin": {
      "type": "http",
      "url": "https://mcp.getoriginai.com",
      "headers": {
        "Authorization": "Bearer ${ORIGIN_TOKEN}"
      }
    }
  }
}

npx originai link --project <project-id>

一站式部署所有主流客户端指令文件

npx originai login
npx originai link --project <project-id> --all

CI/CD 自动化流水线配置

export ORIGIN_TOKEN=oat_…
npx originai get-diff
npx originai sync

常用 CLI 辅助诊断工具集

npx originai login           # 交互式浏览器授权登录
npx originai doctor          # 自动化环境体检：检查登录态、绑定关系、Skill 文件与 API 连通性
npx originai mcp             # 启动本地 stdio MCP 服务器（插件默认采用的底层模式）
npx originai mcp config --cursor # 生成针对 Cursor 的 MCP 配置 JSON
npx originai install-help    # 打印全套客户端集成矩阵速查指南

CLI 与 MCP 核心特性横向对比

考量维度	OriginAI CLI	本地 `originai mcp` 服务	远程云端 HTTP MCP
最契合场景	Codex / Pi / Hermes / CI 流水线	Claude Code 官方插件、Cursor stdio 桥接	纯远程无头容器环境
认证管理机制	`login` 会话或 `ORIGIN_TOKEN` 环境变量	与 CLI 完全相同（复用 `login` 会话）	通过 HTTP 报头携带 Bearer `ORIGIN_TOKEN`
同步指针推进	执行 `sync` 自动更新 `release_hash`	调用 `sync_origin_json` 或手动执行 `sync`	调用 `sync_origin_json` 或手动执行 `sync`
Skill 规范接入	通过 `link --skill` 部署本地规范	插件已完整打包内聚 Skill 规范	可选挂载本地 Skill 规范文件

面向维护者说明（Monorepo 架构）

bun run --cwd packages/skills sync-assets
bun run claude-plugin:sync
bun run --cwd packages/claude-marketplace sync

系统配置代码片段的单一真实源（SSOT）维护于 packages/skills/src/install-snippets.ts，Web 前端展示标签逻辑维护于 frontend/src/lib/agent-install.ts。