> For the complete documentation index, see [llms.txt](https://xerberus.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xerberus.gitbook.io/documentation/mcp/xerberus-mcp.md).

# XERBERUS MCP

Give your agent structured access to the **Xerberus Risk Framework** — the assessment layer: token risk **scorecards**, dimension answers, **evidence**, entity relationships, price data, and a full **dispute** workflow. Connect once, then ask in plain English; your agent calls the tools.

**What builders use it for:**

* **Due diligence** — pull an entity's framework scorecard and its top failure modes.
* **Evidence & assessments** — see the dimension answers, confidence, and the evidence behind a rating.
* **Contribute & dispute** *(writer keys)* — record evidence/answers, or open and track a dispute.

{% hint style="info" %}
Looking for live, on-chain systemic risk (portfolio briefs, contagion, cascade, exit liquidity)? That's the separate **Xerberus MCP (Enterprise / V7)** — see *Which Xerberus MCP?*
{% endhint %}

***

## See it work

One question — the agent picks the tools.

> **You:** *"What's the Xerberus risk picture for GHO — its scorecard, top failure modes, and the evidence behind them?"*

The agent chains `search_subjects` → `get_scorecard` → `get_failure_modes` → `get_evidence`, then answers:

> **Agent:** GHO's Xerberus framework scorecard, the dimensions dragging the grade down, its top failure modes (each tied to a scorecard subdimension), and the **cited evidence** each assessment is based on — so you get the rating *and* the reasoning, not just a number.

Tool output is structured JSON (your agent summarizes it; you can read it directly). A **reader** key is all you need for this.

***

## Quickstart

{% hint style="warning" %}
You need an API key — request one from the Xerberus team on [Telegram](https://t.me/+g4xO7-LE8_41ODIy). **Reader** keys get the read-only risk-intelligence tools; **writer** (`user_scoped`) keys also unlock framework contributions and the dispute workspace. A reader key never even *sees* the write tools — they're filtered out of `tools/list`.
{% endhint %}

* **Endpoint:** `https://mcp.xerberus.io/framework/mcp` *(Streamable HTTP)*
* **Auth:** `X-API-Key: <your-key>` on every request
* **Wallet binding** *(disputes only):* `X-Wallet-Address: <wallet>`

```bash
# connected? (tools/list returns 200 with a valid key)
curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  -H 'Content-Type: application/json' -H "X-API-Key: $KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  https://mcp.xerberus.io/framework/mcp
```

***

## Connect your agent

Standard **Streamable-HTTP MCP** with a custom header — connect it like any remote MCP server:

{% tabs %}
{% tab title="Claude Code" %}

```bash
claude mcp add --transport http xerberus \
  https://mcp.xerberus.io/framework/mcp \
  --header "X-API-Key: ${XERBERUS_KEY}"
```

Then ask: `claude "Show me the Xerberus risk scorecard for the GHO token"`
{% endtab %}

{% tab title="Cursor" %}
`~/.cursor/mcp.json` (or project `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "xerberus": {
      "url": "https://mcp.xerberus.io/framework/mcp",
      "headers": { "X-API-Key": "<your-key>" }
    }
  }
}
```

{% endtab %}

{% tab title="Claude Desktop / Codex / Amp (mcp-remote)" %}
For harnesses that bridge HTTP MCP via a command:

```json
{
  "mcpServers": {
    "xerberus": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.xerberus.io/framework/mcp",
               "--header", "X-API-Key:${XERBERUS_KEY}"],
      "env": { "XERBERUS_KEY": "<your-key>" }
    }
  }
}
```

{% endtab %}
{% endtabs %}

***

## What you can do

Your agent reads the full machine-readable schema on connect (`tools/list`). The surface:

#### Risk intelligence (reader + writer)

| Tool                                                      | What it does                                         |
| --------------------------------------------------------- | ---------------------------------------------------- |
| `search_subjects`                                         | fuzzy-search assets, protocols, organisations        |
| `get_scorecard`                                           | full scorecard for an entity — scores + dimensions   |
| `get_failure_modes`                                       | failure modes extracted from scorecard subdimensions |
| `get_token_assessment_summary`                            | summary of dimension answers for a token             |
| `get_past_assessments` / `get_recent_assessments`         | past / most-recent assessment results                |
| `get_evidence`                                            | evidence items backing a token's assessment          |
| `get_connections`                                         | relationships/connections for an entity              |
| `get_price_data`                                          | price data for an asset                              |
| `count_by_dimension` / `_grouped`                         | counts for a dimension (optionally by object class)  |
| `get_confidence_distribution` / `get_answer_distribution` | confidence + YES/NO/UNKNOWN distributions            |

#### Framework contribution (writer keys)

| Tool                     | What it does                        |
| ------------------------ | ----------------------------------- |
| `write_evidence`         | record a new evidence item          |
| `write_dimension_answer` | write a dimension evaluation result |

#### Dispute workspace (`user_scoped` writer keys; send `X-Wallet-Address`)

| Tool                                                              | What it does                                                          |
| ----------------------------------------------------------------- | --------------------------------------------------------------------- |
| `propose_dispute_draft`                                           | compose a dispute draft + mint a single-use token (read-only preview) |
| `send_dispute_message`                                            | submit a dispute (with the draft token) or follow up on one           |
| `get_my_disputes` / `get_dispute_status` / `get_dispute_messages` | list / poll / read disputes                                           |
| `dispute_reopen` / `archive_dispute`                              | reopen a rejected dispute / archive toggle                            |

***

## Example prompts

* *"What's the Xerberus risk scorecard for GHO, and what are its top failure modes?"*
* *"Search for Aave and summarise its latest dimension assessments."*
* *"Show recent assessments where the supply-dynamics dimension answered NO."*
* *"Pull the evidence behind the liquidity assessment for token 0x… and explain it."*
* *(writer)* *"Draft a dispute on the supply-dynamics answer for my token, then submit it."*

***

## Good to know

{% hint style="info" %}
**Capability tiers** — reader keys are read-only; contribution + dispute tools require a `user_scoped` (writer) key, and are hidden from `tools/list` for reader keys.
{% endhint %}

* **Wallet binding** — dispute writes reject any call whose supplied wallet doesn't match the `X-Wallet-Address` session header, so an agent can't act on a wallet you didn't bind.
* **Single-use dispute tokens** — `propose_dispute_draft` mints a token consumed by `send_dispute_message`, spent only after the backend confirms (no double-submit).
* **Rate limits** — per-tool limits are enforced; back off on `429`.
* **Coverage** — the Xerberus Risk Framework dataset (assets, protocols, organisations).

## Get a key

Request a **reader** or **writer** key from the Xerberus team on [Telegram](https://t.me/+g4xO7-LE8_41ODIy) — issued per client. Treat it like a secret: send it only over HTTPS in the `X-API-Key` header, never commit it to source control.