MCP - Esheria

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

Production MCP URL: https://mcp.esheria.ai/mcp

Choose Your Auth Path

OAuth Remote

Claude or Codex opens Esheria consent. Click Approve access. No pasted API key.

API-Key Remote

Use a dashboard data token as the bearer token.

Local Stdio

Fallback for hosts without remote MCP. Runs locally.

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

Add the connector

Use https://mcp.esheria.ai/mcp.

Approve access

Verify in Claude

Ask Claude to list Esheria packs, then inspect a pack such as UK-DATA-PROTECTION-PRIVACY or EU-NIS2-CYBERSECURITY.

Do not paste an esh_live_ or esh_test_ token into a Claude Directory connector. Directory connections use OAuth.

Codex Desktop App

Open MCP settings

Open Settings, select MCP servers, then choose Add server.

Add Esheria

Set the name to Esheria, choose Streamable HTTP, and use https://mcp.esheria.ai/mcp as the server URL.

Restart the app

Save the server, then select Restart so the app reloads its MCP configuration.

Authenticate

Select Authenticate, sign in to the Esheria dashboard, and click Approve access. No Esheria API key is required for this OAuth path.

Verify the connection

Type /mcp in the composer and confirm Esheria is connected, then ask Codex to call esheria_list_packs.

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:

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:

export ESHERIA_API_KEY="YOUR_DASHBOARD_CREATED_DATA_TOKEN"

[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:

{
  "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:

uvx --from esheria esheria-mcp serve --stdio

Pass these environment variables to the host:

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:

{
  "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

​Choose Your Auth Path

OAuth Remote

API-Key Remote

Local Stdio

​Host Setup

​Claude.ai / Claude Desktop Directory

​Codex Desktop App

​Codex CLI

​Generic Remote MCP

​Local Stdio Fallback

​Verify The Connection

​Tool Access

​Hosted OAuth: 20 read-only tools

​API data tokens: nine additional safe tools

​Operator mutations

​Results And Large Responses

​Protocol Compatibility

​Source-Monitor Guardrails

​Troubleshooting

​Agent Guardrails

Choose Your Auth Path

Host Setup

Claude.ai / Claude Desktop Directory

Codex Desktop App

Codex CLI

Generic Remote MCP

Local Stdio Fallback

Verify The Connection

Tool Access

Hosted OAuth: 20 read-only tools

API data tokens: nine additional safe tools

Operator mutations

Results And Large Responses

Protocol Compatibility

Source-Monitor Guardrails

Troubleshooting

Agent Guardrails