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

# MCP

> Connect Esheria's regulatory tools to Claude, Codex, Cursor, or an internal agent host.

Use Esheria MCP when an agent host needs citation-backed regulatory facts
without direct database, S3, or pipeline access.

<Tip>
  Production MCP URL: `https://mcp.esheria.ai/mcp`
</Tip>

## Choose Your Auth Path

<Columns cols={3}>
  <Card title="OAuth Remote" icon="plug">
    Claude or Codex opens Esheria consent. Click **Approve access**. No pasted API key.
  </Card>

  <Card title="API-Key Remote" icon="key-round">
    Use a dashboard data token as the bearer token.
  </Card>

  <Card title="Local Stdio" icon="terminal">
    Fallback for hosts without remote MCP. Runs locally.
  </Card>
</Columns>

| Path             | Flow                                                              |
| ---------------- | ----------------------------------------------------------------- |
| Claude Directory | Claude -> Esheria consent -> remote MCP                           |
| Codex OAuth      | Codex -> Esheria consent -> local loopback callback -> remote MCP |
| API-key hosts    | Host secret -> bearer token -> remote MCP                         |
| Stdio fallback   | Local MCP process -> `https://api.esheria.ai`                     |

Esheria is catalog-first. Start with `esheria_list_packs`, then pass the
selected `pack_id` to pack-specific tools. MCP does not silently select Kenya
or any other jurisdiction, and multi-pack graph or preview tools require an
explicit `pack_ids` list.

## Host Setup

| Host                                 | Connection                                             | Auth                                          |
| ------------------------------------ | ------------------------------------------------------ | --------------------------------------------- |
| Claude.ai / Claude Desktop Directory | Add `https://mcp.esheria.ai/mcp` in the connector flow | OAuth dashboard consent                       |
| Codex desktop app                    | Settings -> MCP servers -> Streamable HTTP             | OAuth dashboard consent                       |
| Codex CLI                            | Remote MCP URL in `~/.codex/config.toml`               | OAuth (recommended) or `bearer_token_env_var` |
| Cursor                               | Remote MCP or local stdio MCP                          | Bearer data token                             |
| Claude Code                          | Remote MCP if available; stdio fallback otherwise      | Bearer data token                             |
| Internal host                        | HTTP / Streamable HTTP MCP                             | Bearer data token                             |

### Claude.ai / Claude Desktop Directory

<Steps>
  <Step title="Add the connector">
    Use `https://mcp.esheria.ai/mcp`.
  </Step>

  <Step title="Approve access">
    Sign in to the Esheria dashboard and click **Approve access**.
  </Step>

  <Step title="Verify in Claude">
    Ask Claude to list Esheria packs, then inspect a pack such as
    `UK-DATA-PROTECTION-PRIVACY` or `EU-NIS2-CYBERSECURITY`.
  </Step>
</Steps>

<Warning>
  Do not paste an `esh_live_` or `esh_test_` token into a Claude Directory
  connector. Directory connections use OAuth.
</Warning>

### Codex Desktop App

<Steps>
  <Step title="Open MCP settings">
    Open **Settings**, select **MCP servers**, then choose **Add server**.
  </Step>

  <Step title="Add Esheria">
    Set the name to `Esheria`, choose **Streamable HTTP**, and use
    `https://mcp.esheria.ai/mcp` as the server URL.
  </Step>

  <Step title="Restart the app">
    Save the server, then select **Restart** so the app reloads its MCP
    configuration.
  </Step>

  <Step title="Authenticate">
    Select **Authenticate**, sign in to the Esheria dashboard, and click
    **Approve access**. No Esheria API key is required for this OAuth path.
  </Step>

  <Step title="Verify the connection">
    Type `/mcp` in the composer and confirm Esheria is connected, then ask
    Codex to call `esheria_list_packs`.
  </Step>
</Steps>

The Codex desktop app, CLI, and IDE extension can share MCP configuration when
they use the same Codex profile. If you already completed
`codex mcp login esheria` in that profile, Esheria may already appear as
authenticated in the app.

### Codex CLI

Configure and authenticate with OAuth:

```bash theme={null}
codex mcp remove esheria 2>/dev/null || true
codex mcp add esheria --url https://mcp.esheria.ai/mcp
codex mcp login esheria
```

Approve access in the Esheria dashboard. Codex returns to a strict loopback
callback on `127.0.0.1` with an ephemeral port. Then call `esheria_health`,
`esheria_ready`, and `esheria_list_packs`.

Bearer-token alternative:

```bash theme={null}
export ESHERIA_API_KEY="YOUR_DASHBOARD_CREATED_DATA_TOKEN"
```

```toml theme={null}
[mcp_servers.esheria]
url = "https://mcp.esheria.ai/mcp"
bearer_token_env_var = "ESHERIA_API_KEY"
```

Do not keep `bearer_token_env_var` on the same entry when testing OAuth.

### Generic Remote MCP

Use this shape for Cursor, Claude Code remote MCP, or an internal agent host
that accepts an HTTP MCP URL and bearer token:

```json theme={null}
{
  "name": "esheria",
  "transport": "http",
  "url": "https://mcp.esheria.ai/mcp",
  "authorization": "Bearer YOUR_DASHBOARD_CREATED_DATA_TOKEN"
}
```

### Local Stdio Fallback

Use this when a host does not support remote MCP URLs:

```bash theme={null}
uvx --from esheria esheria-mcp serve --stdio
```

Pass these environment variables to the host:

```bash theme={null}
ESHERIA_API_BASE_URL=https://api.esheria.ai
ESHERIA_API_TOKEN=YOUR_DASHBOARD_CREATED_DATA_TOKEN
```

Stdio validates the token before exposing a catalog. Invalid and
management-only tokens cause startup to fail closed.

## Verify The Connection

Use the same first calls in every host:

| Tool                       | Expected result                                                       |
| -------------------------- | --------------------------------------------------------------------- |
| `esheria_health`           | MCP process is reachable                                              |
| `esheria_ready`            | Runtime dependencies are ready                                        |
| `esheria_list_packs`       | Current pack catalog                                                  |
| `esheria_get_pack`         | Metadata for one `pack_id`                                            |
| `esheria_list_obligations` | Bounded `structuredContent` with published obligations and `trace_id` |

Example obligation lookup:

```json theme={null}
{
  "tool": "esheria_list_obligations",
  "arguments": {
    "pack_id": "UK-DATA-PROTECTION-PRIVACY",
    "query": "data subject",
    "limit": 3
  }
}
```

Choose any `verified_published` pack returned by `esheria_list_packs`; the UK
pack above is an example, not a default.

## Tool Access

The 37 tools are the complete catalog—not 37 obsolete or additional tools. Authentication determines the safe subset shown to each connection.

| Credential          | Visible tools | Access                                              |
| ------------------- | ------------: | --------------------------------------------------- |
| Hosted MCP OAuth    |            20 | Curated read-only tools.                            |
| API data token      |            29 | All safe read/read-like tools.                      |
| Operator data token |         29-37 | Adds only mutations authorized by its write scopes. |

Invalid and management-only credentials are rejected before initialization or
tool listing.

### Hosted OAuth: 20 read-only tools

| Area                     | Tools                                                                                                                                                     |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Runtime                  | `esheria_health`, `esheria_ready`                                                                                                                         |
| Packs and versions       | `esheria_list_packs`, `esheria_get_pack`, `esheria_list_pack_versions`, `esheria_get_pack_diff`, `esheria_list_change_events`                             |
| Published facts          | `esheria_list_obligations`, `esheria_get_filing_calendar`, `esheria_get_evidence_register`, `esheria_get_penalty_facts`, `esheria_get_legal_review_audit` |
| Applicability and claims | `esheria_check_applicability`, `esheria_check_graph_applicability`, `esheria_verify_claim`                                                                |
| Graph and export         | `esheria_list_relationships`, `esheria_query_regulatory_graph`, `esheria_get_entity_profile`, `esheria_export_pack`, `esheria_get_citation_context`       |

### API data tokens: nine additional safe tools

* `esheria_list_source_watches`
* `esheria_get_source_currentness`
* `esheria_list_source_change_events`
* `esheria_list_recompile_candidates`
* `esheria_get_graph_coverage`
* `esheria_list_customer_profiles`
* `esheria_preview_customer_lifecycle`
* `esheria_list_customer_obligation_instances`
* `esheria_list_customer_change_impacts`

Use `esheria_list_customer_profiles` with `customer_profile_id` to inspect one
profile. Add `include_applicability_runs: true` to retrieve its prior run
history through the same safe tool.

### Operator mutations

Every mutation requires both its scope and `"confirm": true`.

| Scope              | Tools                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `monitoring:write` | `esheria_create_source_watch`, `esheria_check_source_watches`                                                                                                                                                |
| `graph:write`      | `esheria_rebuild_graph_projection`                                                                                                                                                                           |
| `customer:write`   | `esheria_create_customer_profile`, `esheria_run_customer_applicability`, `esheria_update_customer_obligation_instance`, `esheria_recompute_customer_change_impacts`, `esheria_update_customer_change_impact` |

MCP does not expose token, billing, subscription, or workspace administration.

## Results And Large Responses

Successful calls return the same bounded JSON in text content and
`structuredContent`, so hosts that consume either representation receive the
result. Results include `trace_id` and an `mcp` object with:

* `truncated`
* `output_bytes`
* `max_output_bytes`

Structured payloads are bounded to 24 KiB by default. Use pagination or the equivalent
API/CLI command when `truncated` is true. MCP pack export is a bounded
manifest/count/sample view; use `esheria packs export` or the REST export route
for the complete artifact.

## Protocol Compatibility

The hosted service uses the official MCP SDK and negotiates MCP `2025-11-25`.
It supports `ping`, input-schema validation, lifecycle enforcement, MCP tool
errors, bounded active-session counts, idle expiry, and Streamable HTTP
sessions.

Clients must initialize, retain `Mcp-Session-Id`, send
`MCP-Protocol-Version` after initialization, and send
`notifications/initialized`. Invalid JSON-RPC, batches, unsupported versions,
missing sessions, unsafe Origin/Host headers, and malformed tool arguments fail
closed. Streamable HTTP requests use `Content-Type: application/json` and
advertise both `application/json` and `text/event-stream` in `Accept`.

API-token profiles expose three pack resource templates through
`resources/templates/list` and five prompts. `resources/list` is empty because
pack resources require a selected `pack_id`. Hosted OAuth remains tool-only.

## Source-Monitor Guardrails

Hosted source monitoring rejects local files, private/link-local/metadata
destinations, DNS rebinding, HTTPS-to-HTTP downgrade redirects,
caller-selected S3 endpoints, unapproved S3 buckets, non-standard ports,
oversized content, unbounded waits, and oversized check batches.
Offline local-file monitoring is a separate pipeline-only mode.

## Troubleshooting

| Symptom                             | Meaning                                                   |
| ----------------------------------- | --------------------------------------------------------- |
| `401` plus `WWW-Authenticate`       | Missing, invalid, expired, or management-only credential. |
| `403 Invalid Origin header`         | The browser/host Origin is not allow-listed.              |
| `400 Unsupported protocol version`  | Upgrade the MCP host or negotiate a supported version.    |
| `400 Missing session ID`            | Initialize and reuse the returned `Mcp-Session-Id`.       |
| Tool result has `isError: true`     | Check its validation/API message and `trace_id`.          |
| `mcp.truncated: true`               | Paginate or use CLI/API for the complete result.          |
| Mutation is absent                  | Mint a data token with the required write scope.          |
| Mutation says `confirm` is required | Retry only after review with `"confirm": true`.           |

## Agent Guardrails

Ask agents to:

* call Esheria before making regulatory assertions
* preserve citation IDs, readiness labels, limitations, and `trace_id`
* avoid legal-advice framing
* route uncertain or unsupported answers to human review