> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarion.cantina.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP access

> Connect external MCP clients (Claude Code, Cursor, CI scripts) to your Clarion workspace.

<Note>
  Clarion exposes a workspace-scoped Model Context Protocol (MCP) server so external clients can — without the Clarion web UI — read issues, tasks, monitors, signals, and signal rules; inspect agent-run records and transcripts; run assistant chats; operate the scheduler; author and edit agents and skills; browse and instantiate templates; and manage the workspace's default agent instructions. There are two ways to connect: OAuth (for IDE/agent clients) and long-lived API tokens (for headless ones).
</Note>

## Where it lives

In Clarion, go to **Settings > MCP access**. The page has two tabs:

* **API tokens** — mint, list, and revoke long-lived bearer tokens. One row per token; the plaintext is shown exactly once at creation time.
* **OAuth setup** — copy-paste snippets for Claude Code and Claude Desktop, plus a generic note for other MCP clients. No secrets to manage.

The MCP endpoint itself is at `https://<your-clarion-host>/api/mcp` (the OAuth setup tab fills in the right URL for your environment).

***

## Choosing a flow

|                       | OAuth                                                             | Long-lived token                             |
| --------------------- | ----------------------------------------------------------------- | -------------------------------------------- |
| Best for              | Claude Code, Cursor, any IDE/agent client that can open a browser | CI jobs, cron workers, headless scripts      |
| Setup                 | One browser sign-in, no secret to copy                            | Mint a token, copy it into the client config |
| Revocation            | From the client's settings                                        | Revoke the row in **Settings > MCP access**  |
| Appears in token list | No                                                                | Yes                                          |

If a client supports OAuth, use it. The browser flow handles re-auth automatically when access expires; long-lived tokens never rotate and stay valid until revoked.

***

## Connecting via OAuth

### Claude Code (CLI)

1. Open **Settings > MCP access > OAuth setup** and copy the `claude mcp add` command shown there. It already contains the right URL for your workspace.

2. Run it:

   ```bash theme={null}
   claude mcp add --transport http clarion https://<your-clarion-host>/api/mcp
   ```

3. Start a session. On the first tool call Claude Code opens the Clarion OAuth grant page — pick the workspace and approve. The token is captured by Claude Code's local callback.

### Claude Desktop

1. Open **Settings > MCP access > OAuth setup** and copy the JSON snippet.

2. Paste it into `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent path on Windows/Linux:

   ```json theme={null}
   {
     "mcpServers": {
       "clarion": {
         "type": "http",
         "url": "https://<your-clarion-host>/api/mcp"
       }
     }
   }
   ```

3. Restart Claude Desktop. The first tool call triggers the same browser grant flow as the CLI.

### Other MCP clients

Point any MCP client that speaks the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) at `https://<your-clarion-host>/api/mcp`. The first unauthenticated request returns a `WWW-Authenticate` challenge that points at `/.well-known/oauth-protected-resource`; any spec-compliant client follows the metadata to discover the authorization server and complete the OAuth flow without extra config.

***

## Connecting via a long-lived API token

Use this when the client can't drive an interactive browser sign-in.

1. In **Settings > MCP access > API tokens**, click **New token**.
2. Give it a label that lets you recognize it later (e.g. `CI nightly drift check`, `Cron worker`).
3. Click **Create token**. The dialog swaps to a one-time reveal — copy the plaintext **now**. Once you close the dialog the secret is gone for good.
4. Paste the token into your MCP client config as a `Bearer` credential:

   ```json theme={null}
   {
     "mcpServers": {
       "clarion": {
         "type": "http",
         "url": "https://<your-clarion-host>/api/mcp",
         "headers": { "Authorization": "Bearer <PASTE_TOKEN_HERE>" }
       }
     }
   }
   ```

<Warning>
  A long-lived token grants full workspace access over MCP — not just reads and light triage, but **creating and editing configuration**: agents, skills, schedules, and the workspace's default agent instructions. Treat it like any other secret — keep it out of source control and rotate (revoke + re-mint) on a cadence that matches your other credentials.
</Warning>

### Revoking a token

In the **API tokens** tab, click the revoke icon on the row, confirm, and the token stops authenticating immediately. Any client still using it gets a 401 on its next request. Revocation is one-way; revoked rows stay in the list with a "Revoked" badge so you can audit who created them and when.

***

## Available tools

After connecting, the client sees the following workspace-scoped tools under the `clarion` server (so each one appears as `mcp__clarion__<tool>`). Every tool is scoped to the token's workspace: reads filter by workspace, cross-workspace lookups return an error rather than another tenant's data, and mutations are attributed to the operator who minted the token.

### Read & triage

**Issues**

* `list_issues` — paginated list, filterable by status / severity / search. `status: ["escalated"]` narrows to the confirmed problems.
* `get_issue` — full issue detail by display number, including its parent issue and related child issues
* `complete_remediation_item` — toggle a checklist item on an issue's remediation list
* `retrigger_issue` — re-run triage agents for an issue (e.g. after deploying a fix)

**Tasks**

* `list_tasks` — paginated list, filter by status / priority / search
* `get_task` — single task by id

**Monitors & integrations**

* `list_monitors`, `get_monitor` — the workspace's ingestion sources, with sanitized per-type config (webhook secrets stripped)
* `list_integrations`, `get_integration_health` — integration sync health (consecutive failures, pause state, auth errors); credentials are never returned

**Signals**

* `list_signals`, `get_signal` — the raw ingested events that feed issues, before any alert filter fires

**Signal rules**

* `list_signal_rules`, `get_signal_rule` — the detections that turn signals into alerts, per monitor or workspace-wide (the matching sequence is returned by `get_signal_rule`)

**Agent runs**

* `get_agent_job` — the execution record of a single agent run (status, error, model, token usage, timing, and what it ran for: a triage investigation, an assistant chat, or a scheduled run)
* `get_agent_job_transcript` — the poll-friendly, step-by-step transcript of an agent run (assistant turns, tool calls, tool results), oldest first

**Assistant chats**

* `list_chats` — the workspace's assistant chats
* `get_chat_transcript` — a chat's messages and tool activity
* `start_chat` — open a new assistant chat with a first user message (optionally booting a specific agent persona); returns an agent-run id to poll
* `send_chat_message` — post a follow-up message into an existing chat

**Schedules**

* `list_schedules`, `get_schedule` — discover what's running in the workspace
* `list_schedule_runs`, `get_schedule_run` — poll-friendly run snapshots
* `run_schedule_once` — fire a schedule out-of-band without changing its cron cadence
* `cancel_schedule_run` — cancel a pending or running execution
* `create_schedule`, `update_schedule`, `set_schedule_enabled`, `delete_schedule` — full CRUD on recurring tasks

### Configure the workspace

<Note>
  Skill and instruction content is exchanged as **markdown** (with inline `<tool type="…" name="…">` pills) and converted to/from Clarion's rich-text format automatically — you never handle the raw editor JSON.
</Note>

**Agents**

* `list_agents`, `get_agent` — the workspace's triage agents and their linked skills/monitors
* `create_agent`, `update_agent` — manage an agent's name, active state, linked skills, and linked **existing** monitors. Monitor *creation* stays in the Clarion UI — it involves webhook secrets and registration that aren't exposed over MCP.

**Skills**

* `list_skills`, `get_skill` — reusable workspace skills, instructions returned as markdown
* `create_skill`, `update_skill` — author or edit a skill from markdown; tools are extracted from the inline `<tool>` pills, and edits snapshot a new version

**Templates**

* `list_skill_templates`, `get_skill_template` — browse the curated skill-template catalog
* `create_skill_from_template` — instantiate a skill template into a *managed* workspace skill (auto-updates when the template changes; idempotent — returns the existing copy if already instantiated)
* `list_agent_templates`, `get_agent_template` — browse the published agent-template catalog
* `create_agent_from_template` — scaffold an agent plus its managed skills from a template, created inactive so you can review before it runs

**Workspace**

* `list_workspace_tools` — the action tools currently **available** to agents in this workspace. Only tools whose backing integration (and any required credentials or pauser config) is actually connected are returned — unconfigured ones are omitted — so this reflects what a skill can reference *today*. Includes the workspace's custom MCP servers, custom API/CLI toolsets, and Microsoft Sentinel tools.
* `get_workspace_instructions`, `set_workspace_instructions` — read or replace the default agent instructions (markdown) applied to every agent in the workspace

<Note>
  Templates are a shared, platform-curated catalog. These tools only **browse** it and **instantiate** copies into your workspace — creating, editing, or deleting templates is admin-only and is not exposed over MCP.
</Note>

### Asset catalog & curated knowledge (Brain)

<Note>
  These tools are only registered when the workspace has the **asset-catalog (Brain)** feature enabled. If it's off, none of them appear in the client's tool list. Writes to curated knowledge require the `assets:write` permission.
</Note>

The Brain surface exposes the workspace's discovered infrastructure and the operator-curated architecture knowledge layered on top of it.

**Assets & systems (read)**

* `list_assets`, `get_asset` — the resources (compute, datastores, repos, services, DNS records, cloud accounts, …) discovered across connected integrations
* `list_systems` — the auto-correlated, cross-provider groupings of those assets
* `get_business_context` — durable org-level facts (industry, tech stack, regulatory posture, …)

**Annotations (write)**

* `annotate_asset` — record durable, attributed notes/attributes on a resource
* `annotate_workspace` — propose a workspace-level business fact (held for human review)
* `record_inferred_asset` — persist a triage-inferred narrative asset (attacker IP, involved user, vulnerable package, …) into the catalog

**Curated knowledge (read)**

* `search_knowledge` — text-search knowledge names, page bodies, and references
* `list_knowledge_elements`, `get_knowledge_element` — the hand-curated architecture nodes (systems, services, platforms, …) and their linked assets and references
* `list_knowledge_references` — curated external references filtered by semantic tag (`access_control`, `runbook`, `architecture`, …)

**Curated knowledge (write)**

* `propose_knowledge_element`, `update_knowledge_element`, `remove_knowledge_element` — create/enrich, edit, or delete a curated knowledge node
* `link_knowledge_asset`, `unlink_knowledge_asset` — connect or disconnect a catalog asset and a knowledge node
* `add_knowledge_fact`, `update_knowledge_fact`, `delete_knowledge_fact` — weave, supersede, or retract an atomic claim in a knowledge node's recap

<Info>
  The agent-side MCP server used by Clarion's own triage agents has a separate (broader) tool surface — agents see integration tools like `mcp__slack__*`, `mcp__okta__*`, `mcp__cloudtrail__*` etc. that aren't exposed externally. External MCP clients only see the workspace tools listed above. `list_workspace_tools` surfaces the *names* of the available integration tools so a skill you author can reference them by their `<tool>` type, but those tools still execute agent-side during triage.
</Info>