MCP & agent install

OriginAI offers two ways to connect an agent: a Claude Code plugin (a local MCP bridge plus the skill), and CLI skill files for every major coding agent. Local MCP is npx originai mcp (stdio). All of them go through the same access-token API, with the same behavior — reads default to the latest release, and writes are guarded after your first publish.

Read this first: the auth model

Don't treat "create an access token and export ORIGIN_TOKEN" as the default onboarding path — that's for CI and advanced setups. Create tokens only when you need them (see Access tokens), and never commit an oat_ value.

The available tools

Create a Change Request

Kernel names stay *_proposal. After a release:

1. list_proposals with status: "all".
2. validate, then write_document (first staged write creates the CR).
3. describe_proposal — Issue (title, note) + Decisions/Changelog (rationale).
4. submit_proposal. Never apply, dismiss, or record Ready / Not ready.

Prefer get_proposal_diff when implementing a change request, get_diff when implementing a published release. After implementing a published release, call sync_origin_json and write origin_json into .origin.json, or run npx originai sync. sync / sync_origin_json clears .origin.json proposal_id only after a new release hash exists.

Install by agent

Claude Code — the plugin (recommended)

npx originai login

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

For development inside the monorepo:

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

Then link and verify:

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

The plugin's .mcp.json runs a local MCP server:

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

There's no day-to-day export ORIGIN_TOKEN needed for Claude Code.

Cursor

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

Paste the printed JSON into Cursor's MCP settings — the stdio bridge uses your login.

OpenAI Codex

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

Codex agents use the CLI via AGENTS.md and the skill. MCP is optional if your Codex host supports it.

Pi / Hermes / OpenCode (Agent Skills)

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

This writes .agents/skills/origin-product-spec-management/. Tools default to the CLI, with MCP optional.

skills.sh / Agent Skills / well-known

From GitHub (works with npx skills add):

npx skills add 21stware/originai-context
# the skill path in the repo is: skills/origin-product-spec-management/

From the site's well-known endpoint:

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

After installing the skill, agents still need to:

1. npx originai login
2. npx originai link --project <id> in the product repo.

The skill documents the MCP-first, CLI-fallback approach, and it embeds no tokens.

Claude Code — CLAUDE.md only (no plugin)

npx originai login
npx originai link --project <project-id> --claude-code --skill
# optional: npx originai mcp config --claude

All instruction files at once

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

CI

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

Handy CLI helpers

npx originai login
npx originai doctor          # login + link + skill files + API
npx originai mcp             # stdio MCP server (the plugin default)
npx originai mcp config --cursor
npx originai install-help    # the full matrix

CLI vs MCP at a glance

For maintainers (monorepo)

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

The snippets' source of truth is packages/skills/src/install-snippets.ts, and the frontend tabs come from frontend/src/lib/agent-install.ts.

Related

• OriginAI CLI
• HTTP API (origin-api)
• Access tokens
• Connect a coding agent
• Review change requests