---
title: Connect your AI coding agent to Clarion
slug: agent-setup
audience: developers
last_updated: 2026-05-11
version: 0.1.0
---

# Connect your AI coding agent to Clarion

This guide walks engineers through wiring up Cursor, Claude Code, GitHub Copilot, Codex, Windsurf, Cline, and JetBrains Junie to Clarion's MCP server. After setup, your agent can call Clarion to:

- See active opportunities, in-flight specs, and recently shipped features
- Ask Clarion's AI "what should we build next?" with cited customer evidence
- Trace any decision back to the customer signals that drove it
- Check if a proposed approach conflicts with existing decisions before you write the code

If you don't do this step, Clarion's MCP server exists but your agent never invokes it — copy-paste workflow stays the only path. **The skill file IS the activation.**

## TL;DR (one command)

```bash
npx @clarion/cli@latest init
```

That auto-detects your agent (by looking at `CLAUDE.md`, `.cursor/`, `.windsurfrules`, `.clinerules`, `AGENTS.md`, etc.), writes the right skill file, appends a reference block to your agent's rules file, and creates a project `.mcp.json` (or `~/.codex/config.toml` for Codex).

Then sign in:

```bash
npx @clarion/cli@latest login
```

Restart your agent. You're done.

## What the CLI installs

For Claude Code (representative; other agents follow the same shape):

- `.claude/skills/clarion/SKILL.md` — the canonical Clarion skill (when to call which tool, how to attribute, anti-patterns)
- `CLAUDE.md` — gets a small `<!-- clarion:start --> ... <!-- clarion:end -->` block appended pointing to the skill
- `.mcp.json` — registers `clarion` as an MCP server at `https://app.getclarion.in/api/mcp`

| Agent | Skill file | Rules file | MCP config |
|---|---|---|---|
| Claude Code | `.claude/skills/clarion/SKILL.md` | `CLAUDE.md` (append) | `.mcp.json` |
| Cursor | `.cursor/skills/clarion/SKILL.md` | `.cursor/rules/clarion-context.mdc` (own file, `alwaysApply: true`) | `.mcp.json` |
| GitHub Copilot / VS Code | `.agents/skills/clarion/SKILL.md` | `.github/copilot-instructions.md` (append) | `.mcp.json` |
| Windsurf | `.windsurf/skills/clarion/SKILL.md` | `.windsurfrules` (append) | `.mcp.json` |
| Cline | `.agents/skills/clarion/SKILL.md` | `.clinerules` (append) | `.mcp.json` |
| Codex CLI | `.agents/skills/clarion/SKILL.md` | `AGENTS.md` (append) | `~/.codex/config.toml` (append `[mcp_servers.clarion]`) |
| JetBrains Junie | `.junie/skills/clarion/SKILL.md` | `.junie/AGENTS.md` (append) | `.mcp.json` |

All writes are **idempotent** — re-running `clarion init` replaces the block in place, never duplicates.

## Authentication

Clarion uses OAuth 2.0 with PKCE for agent connections. There is no API-key copy-paste step. The flow:

1. `clarion login` opens your browser to Clarion's authorize page
2. You sign in (if not already) and pick the workspace you want to scope the token to
3. The CLI receives the authorization code on a loopback port, exchanges it for a Bearer token, and stores it at `~/.config/clarion/credentials.json` (chmod 600)
4. Tokens auto-refresh transparently — 1-hour access tokens, 30-day refresh tokens

Multi-workspace users: MCP tokens are scoped per-workspace. Switch with `clarion login --url https://...`. The agent's `.mcp.json` doesn't carry the token — it points at the MCP endpoint; auth flows through the CLI's stored credentials when the agent invokes a tool.

**Legacy fallback:** for CI/scripts, set `CLARION_API_KEY=<key>` in the environment instead of using OAuth. The MCP server accepts the API key via `X-Clarion-API-Key` header.

## Manual setup (no CLI)

If you can't run the CLI (offline environment, locked-down corp machine, etc.):

### Cursor

1. Create `.cursor/rules/clarion-context.mdc` with:
   ```
   ---
   description: Clarion — product context tools (signals, opportunities, specs, decisions, outcomes)
   alwaysApply: true
   ---

   At session start, call `clarion_get_onboarding_context` (scope=full).
   When the user asks "what should we build / focus on / prioritize?", call `clarion_ask` mode=advise.
   When the user asks "find feedback about X" or "who's asking for X?", call `clarion_search`.
   Always cite by entity id + title. Attribute by company, not personal name.
   ```
2. Create `.mcp.json` at the project root:
   ```json
   {
     "mcpServers": {
       "clarion": { "url": "https://app.getclarion.in/api/mcp" }
     }
   }
   ```
3. Open Cursor settings → MCP. Click "Connect" next to `clarion`. Cursor will open a browser tab for OAuth.

### Claude Code

1. Append the same skill content to `CLAUDE.md`.
2. Same `.mcp.json` as Cursor.
3. From the Claude Code chat: `/mcp connect clarion` — completes the OAuth flow.

### Codex CLI

1. Append to `~/.codex/config.toml`:
   ```toml
   [mcp_servers.clarion]
   url = "https://app.getclarion.in/api/mcp"
   ```
2. Restart Codex. Run `codex auth clarion` to complete OAuth (assumes Codex's OAuth UI; otherwise set `CLARION_API_KEY` env var).

## When to call which tool

This list is the same one the SKILL.md installs into your agent's context — it's the load-bearing decision tree.

| User intent | Call |
|---|---|
| Session start (once per session) | `clarion_get_onboarding_context` scope=full |
| "What should we build / focus on?" | `clarion_ask` mode=advise |
| "Is this consistent with what we decided?" | `clarion_ask` mode=check |
| "Find feedback about X" / "Who's asking for X?" | `clarion_search` |
| "Trace this back to customers" / "Why is X a priority?" | `find_evidence` |
| "Did this feature work after shipping?" | `get_outcomes` |
| "Has this been validated with customers?" | `validate_opportunity` |
| "Show me the spec for X" | `get_specification` |
| "List the top opportunities" | `query_opportunities` |

## Slash commands (Claude Code)

`clarion init` writes four commands into `.claude/commands/` for fast access:

- `/clarion-setup` — first-time setup walkthrough (one-shot)
- `/clarion-welcome-back` — returning user, new project (skips long onboarding)
- `/clarion-check <approach>` — quick proactive drift check against existing decisions
- `/clarion-decide <decision>` — propose recording a decision (committed after user approval in Clarion's UI)

Other agents don't yet have a stable slash-commands convention. Type the same phrases verbatim — the SKILL.md teaches the agent to recognize them.

## How agents should surface Clarion's answers

- **Cite by entity.** Every claim should reference an opportunity id + title. Example:
  > Per opportunity 3b918e1c "Faster Dashboard" — 565K ARR, 6 customers asking.
- **Respect confidence.** `HIGH` → direct guidance. `MEDIUM` → "Clarion suggests…". `EMERGING` → "early signal — worth investigating".
- **Attribute by company**, not personal name. "Acme and BigCo flagged this" beats "Jane Doe complained" — privacy norm.
- **Summarize. Do not paste JSON.** Titles + confidence + top 1–2 evidence points. The raw JSON is for the agent's reasoning, not the user.

## Anti-patterns

- Don't invent customer quotes or ARR numbers. Use Clarion's real data only.
- Don't call Clarion on every message. Cache `clarion_get_onboarding_context` once per session.
- Don't pre-emptively claim a decision is recorded. Wait for `status: active` in the tool response.
- Don't mix engineering context (codebase patterns) with product context (Clarion). Use Clarion for the WHY, your own tools for the HOW.

## Verify the connection

After `clarion init` + `clarion login`, restart your agent and ask:

> "Call clarion_get_onboarding_context and tell me what you see."

Expected: the agent makes the tool call, returns your workspace name, member count, top opportunities, and recent shipped features. If you see "tool not found" or "unauthorized," check:

1. `clarion whoami` — confirms the CLI can authenticate
2. Your `.mcp.json` (or `~/.codex/config.toml`) has the `clarion` entry pointing at `https://app.getclarion.in/api/mcp`
3. Your agent has been restarted since `clarion init` ran
4. The Clarion `/agents/connections` page shows your agent's host in the active list

## Troubleshooting

**"Tool not found: clarion_get_onboarding_context"**
The agent doesn't see the MCP server. Re-check `.mcp.json` and restart the agent.

**"401 Unauthorized"**
Your access token is expired or revoked. Run `clarion login` again.

**"My agent never calls Clarion"**
The skill file isn't being loaded. Confirm `.cursor/rules/clarion-context.mdc` has `alwaysApply: true` (Cursor), or that the rule snippet was appended to your agent's main instruction file (Claude Code, Copilot, Windsurf, Cline). For Cursor specifically: open the agent settings and confirm "Project Rules" includes `clarion-context.mdc`.

**Token leaks**
If a credential file leaks, run `clarion logout` to revoke server-side. Then `clarion login` again. Old refresh tokens are single-use — once revoked, they can't be reused.

## Updating the skill

When Clarion ships new tools, refresh the bundled skill content:

```bash
clarion init --refresh
```

This re-fetches this file from `https://getclarion.in/docs/agent-setup.md` and rewrites the SKILL.md in place. The MCP config and rule-file block are also refreshed if they've drifted from the current canonical form.

---

For the full developer reference (REST API, webhook events, schema definitions), see [getclarion.in/docs](/docs).