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

# Remote MCP endpoint

> Connect any MCP client to Conquoreum over HTTPS: no install, no daemon, just a key.

Conquoreum hosts a **stateless MCP endpoint** at:

```
POST https://api.conquoreum.com/mcp
```

It speaks JSON-RPC 2.0 per the MCP spec (2026-07-28, stateless Streamable HTTP). There is nothing to install and nothing to keep running: every request is self-contained and authenticated with a `cqk_` bearer key. Any MCP client (Claude Code, Claude Desktop, Seifuku Studio, a server-side agent) can read your board, tick off tasks, and read your XP summary from anywhere.

<Note>
  This is different from the local Reality Harness MCP you install for Levels 1 and 2. The local MCP scans repos **on your machine** (commits, planning docs), which a hosted endpoint can't do. The remote endpoint covers the board, the harness summary, and outcomes. The two are complementary, not alternatives.
</Note>

## Connect from Claude Code

Mint a key with the scopes you need (see the table below), then:

```bash theme={null}
claude mcp add --transport http conquoreum https://api.conquoreum.com/mcp \
  --header "Authorization: Bearer cqk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

Or in any MCP client's JSON config:

```jsonc theme={null}
{
  "mcpServers": {
    "conquoreum": {
      "type": "http",
      "url": "https://api.conquoreum.com/mcp",
      "headers": {
        "Authorization": "Bearer cqk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

<Warning>
  Store the key in your MCP client's config or an environment variable, never in a script or a repo. Revoke it any time from the Key Console.
</Warning>

## Tools

| Tool                   | Scope          | Paid tier? | What it does                                                                        |
| ---------------------- | -------------- | ---------- | ----------------------------------------------------------------------------------- |
| `board_week`           | `board:read`   | Yes        | Read the board week view: 7 days, tasks grouped by skill lane.                      |
| `board_complete`       | `board:write`  | Yes        | Tick off a task by `vaultId`. Awards XP exactly once (server-side latch).           |
| `board_reopen`         | `board:write`  | Yes        | Reopen a ticked task. Never claws back XP.                                          |
| `harness_summary`      | `harness:read` | No         | Your XP, level, streak, skill-lane totals, and unlocked skills.                     |
| `outcome_ledger`       | `rhp:outcome`  | No         | Read your verified outcomes and recent events.                                      |
| `submit_reality_event` | `rhp:outcome`  | No         | Record a verified outcome (`proof.payment` / `proof.release` / `proof.evaluation`). |

A completion made here flows all the way back: XP is awarded through the same server logic the app uses, and if you run the Level 3 board-sync bridge, the check-off lands in your Obsidian vault on the bridge's next poll.

## Plain HTTPS routes

The same four operations exist as plain REST-style routes if you'd rather skip MCP entirely:

| Route                                               | Method | Scope          |
| --------------------------------------------------- | ------ | -------------- |
| `/route/board/week?weekOf=<ms>&tzOffsetMin=<min>`   | GET    | `board:read`   |
| `/route/board/complete` (body `{"vaultId": "..."}`) | POST   | `board:write`  |
| `/route/board/reopen` (body `{"vaultId": "..."}`)   | POST   | `board:write`  |
| `/route/harness/summary`                            | GET    | `harness:read` |

```bash theme={null}
curl -s -H "Authorization: Bearer $CONQUOREUM_API_TOKEN" \
  "https://api.conquoreum.com/route/harness/summary"
```

## Privacy and gating

The endpoint fails closed, in this order:

1. **Key** must exist, be live, and carry the tool's scope (401 / 403 otherwise).
2. **Board tools** (`board_*`) require the Reality Harness paid tier: without it you get `402 payment_required`.
3. **Board sync master switch**: if `syncEnabled` is off in the app (the default), board tools return `403` with `"board sync disabled"`. Your board is never readable over the wire until you opt in.
4. **`hideTaskTitles`**: when on, `board_week` returns statuses with titles, project names, and tags redacted. Same redaction your Companion sees.

`harness_summary` is exempt from 2 and 3: XP totals exist for every account and contain no task content.

## Limits and errors

* `board_week`: 600 requests/hour. Board writes: 300/hour (shared with the bridge's check-off budget). `harness_summary`: unlimited.
* Optionally send `x-rhp-version: 1.2` so the server knows your client's protocol expectations.

| Status | Code               | Meaning                                             |
| ------ | ------------------ | --------------------------------------------------- |
| 400    | `bad_request`      | Malformed body or params                            |
| 401    | `unauthorized`     | Key missing, revoked, or not live                   |
| 402    | `payment_required` | Board tool without the Reality Harness tier         |
| 403    | `forbidden`        | Missing scope, or board sync is disabled in the app |
| 404    | `not_found`        | Unknown `vaultId`                                   |
| 429    | `rate_limited`     | Over the hourly bucket; back off and retry          |
| 500    | `internal`         | Server fault; safe to retry                         |