MCP & agent install

OriginAI offers three ways to connect an agent: a hosted MCP server, a Claude Code plugin (a local MCP bridge plus the skill), and CLI skill files for every major coding agent. 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 public remote endpoint (advanced)

https://mcp.getoriginai.com

• Transport: Streamable HTTP (MCP 2025-03-26).
• Auth: Authorization: Bearer oat_….
• The hostname is a Cloudflare reverse proxy, so clients never need to reach *.supabase.co.

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@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. A remote HTTP MCP with ORIGIN_TOKEN is optional, for automation.

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

Remote HTTP MCP (any client) — advanced

export ORIGIN_TOKEN=oat_…

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

npx originai link --project <project-id>

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