---
name: exos-mcp
version: 1.5.0
updated: 2026-10-02
---

# Exos MCP server

The same capabilities as `/skill/instances.md`, `/skill/presets.md`,
`/skill/preview.md` and `/skill/drafts.md`, as MCP tools. Remote, stateless, streamable HTTP:

```
URL:     https://exosdex.xyz/api/runtime/mcp
Header:  Authorization: Bearer exos_ak_…
```

Claude Code:

```
claude mcp add --transport http exos https://exosdex.xyz/api/runtime/mcp \
  --header "Authorization: Bearer $EXOS_AGENT_KEY"
```

Other clients: add a remote HTTP MCP server with that URL and header.

## As a connector (OAuth)

A chat assistant that adds remote MCP servers as **connectors** needs no
pasted key. Give it the URL alone (the person's steps, per assistant:
`https://exosdex.xyz/docs/connect`). The server answers a request without a
bearer with `401` and a `WWW-Authenticate` header naming
`/.well-known/oauth-protected-resource/api/runtime/mcp`; the client follows
it, registers itself (`/api/runtime/oauth/register`, public clients only,
PKCE), and sends the person to `https://exosdex.xyz/oauth/authorize`. There
they connect their wallet, read what the connector may do, and sign ONCE:
the same signature that mints an agent key on the running-copies page. The
token the client receives IS that key (`exos_ak_…`), labelled with the
client's name, lasting 90 days, listed and revocable under **AGENT KEYS** on
`https://exosdex.xyz/forge/running`. Revoke there to disconnect.

Scopes are asked for with `scope`, space-separated, from `instance:read`,
`instance:control` and `spec:write`; when none is asked the person chooses
the level on the approval page (watch by default, steer, draft), and the
token's `scope` says what was granted. There is
no refresh token: when the key expires or is revoked the server answers
`401` with `error="invalid_token"` and the client authorises again.

Over MCP, every connection needs a token (pasted or obtained as above),
including the two public tools. Over HTTP they stay public:
`/skill/presets.md` and `/skill/preview.md` need no key.

## Tools

| Tool | Scope | Does |
|---|---|---|
| `exos_list_instances` | `instance:read` | the person's copies |
| `exos_get_instance` | `instance:read` | one copy's status and recent intents |
| `exos_get_events` | `instance:read` | one copy's ledger |
| `exos_kill_instance` | `instance:read` | end a copy (confirm first) |
| `exos_flatten_instance` | `instance:read` | close everything now, keep the copy paused (confirm first) |
| `exos_pause_instance` | `instance:control` | pause a running copy |
| `exos_resume_instance` | `instance:control` | resume a paused copy (confirm first) |
| `exos_tighten_risk` | `instance:control` | tighten-only risk overrides |
| `exos_list_presets` | none | the strategy catalogue |
| `exos_preview_strategy` | none | compile and rehearse a draft, keeping nothing (`/skill/preview.md`) |
| `exos_save_draft` | `spec:write` | save a new draft on the person's wallet (confirm first; `/skill/drafts.md`) |
| `exos_save_version` | `spec:write` | save a draft's next version |
| `exos_whoami` | `instance:read` | the wallet this key acts as; call it first for any "my" question |
| `exos_my_standing` | `instance:read` | the owner's place on the Rankings and this month's Royale qualification |
| `exos_my_chronicle` | `instance:read` | the owner's own recent events on the Arena |
| `exos_rankings` | any token | the public ladder, `limit` rows (default 20) |
| `exos_royale` | any token | this month's Royale (or `month`, `field` H/A): seats, board, gates, results, payouts, the pot |
| `exos_duels_board` | any token | the Colosseum now: queues, live bouts, recent verdicts |
| `exos_nose` | any token | the Bloodhound's Nose: smart lean vs crowd lean per market, the gap, cold or strong |
| `exos_outcomes_board` | any token | the Outcomes caller board by hit rate |
| `exos_outcomes_feed` | any token | today's Outcomes calls, `coin` to scope |
| `exos_chronicle` | any token | the Arena's public feed, `before` to page |
| `exos_legions` | any token | the Legions board |
| `exos_legion` | any token | one legion's page by `name` |
| `exos_battles` | any token | the 3v3 battles board |

## Reading

The reads (2 Oct 2026) answer the questions a person asks a connector day
to day: where do I stand, what happened overnight, what is hot, what is
the Nose saying. Every one answers **from the store**, the same bodies the
site serves; none asks the venue, so read as often as the person asks.
"My" reads need `instance:read` and resolve the key's own wallet through
`exos_whoami`; the boards are public record and take any token. Numbers
come as the site shows them (a rating as a string, a lean from −100 to
+100); a null is unread or withheld, never zero, so say "not read" rather
than a figure.

## Drafting a strategy

Four tools take a person from an idea to a saved draft. Use them in this
order:

1. `exos_list_presets`: find a starting point with the person.
2. `exos_preview_strategy` with `{ preset: { id, fightingName } }`. Show the
   person the `readout`. Edit the returned `document` as they ask and
   preview it again as `spec`, with the previous one as `against`, until
   they are happy. A passed `gate` is a rehearsal, not a verdict.
3. Confirm the fighting name and the strategy with the person, then
   `exos_save_draft` with the same `preset` or `spec`. It claims the name
   for good. **Keep the returned `id`.**
4. For later edits, `exos_save_version` with that `id` and the edited
   `spec`. The name must not change. Tell the person the returned
   `changeClass`: `patch` re-proves on replay only; anything else re-enters
   the wall-clock gate.

Steps 3 and 4 need a key with `spec:write` (`/skill/keys.md`); without it,
stop after step 2 and point the person to `https://exosdex.xyz/forge`.
Saving is not retried safely: each call makes a new row, so on a timeout
check with the person before calling again.

A saved draft trades nothing. No tool proves, activates or starts it; the
person does that in the app with their wallet. A key stops creating drafts
once the wallet holds 10 unproven ones. Details and errors:
`/skill/drafts.md`.

## Rules

The rules in `/skill.md` apply unchanged: confirm kills, resumes and saves, poll no
faster than `recommendedPollMs`, and never ask for a wallet key.

A `401` from the server means the key is unknown, revoked or expired. A
connector authorises again; a pasted key is replaced by the person. Do not
retry the dead one.

The server is reached from wherever your client runs. A client hosted in a
region Exos does not serve will be refused with `GEO_BLOCKED`, token or no
token, whatever the person's own location (ruled 2 Oct 2026: every door
stays behind the gate, the server-to-server ones included). Tell the
person so, and point them at a client that runs on their own machine.