{
  "markdown": "# Esheria CLI And MCP\n\nInstallable command-line and MCP tools for the Esheria Regulatory Pack API.\n\nGlobal, citation-backed regulatory intelligence for explicit published packs.\nDiscover current readiness, select the intended jurisdiction and pack, and\npreserve citations, versions, limitations, and trace IDs across CLI, Python,\nand MCP workflows. Esheria provides regulatory intelligence, not legal advice.\n\n<!-- mcp-name: io.github.esherialabs/esheria -->\n\nThe package exposes two commands:\n\n```bash\nesheria --help\nesheria-mcp --help\nesheria mcp serve --help\n```\n\nVersion `1.2.2` is the production/stable public release. The CLI, Python\nclient, and MCP software distributed in the `esheria` Python package are\nlicensed under the Apache License 2.0. Hosted API/MCP access, regulatory data,\nservice outputs, and Esheria trademarks are not licensed under Apache-2.0;\nthey remain governed by the [Esheria Terms of Service](https://esheria.ai/terms),\n[Privacy Policy](https://esheria.ai/privacy), and any applicable customer\nagreement. See `LICENSE` and `NOTICE` for the exact boundary.\n\n## CLI Quickstart\n\n1. Create a data API token in the Esheria dashboard.\n2. Install the command. `pipx` is recommended because it keeps command-line\n   tools isolated from project dependencies:\n\n```bash\npipx install esheria\n```\n\nIf you do not use `pipx`, use normal `pip`:\n\n```bash\npython3 -m pip install esheria\n```\n\n3. Configure your shell. Put these in your terminal for a one-off test, or in\n   `~/.zshrc`, `~/.bashrc`, or your shell profile to keep them:\n\n```bash\nexport ESHERIA_API_BASE_URL=\"https://api.esheria.ai\"\nexport ESHERIA_API_KEY=\"<client-api-key>\"\n```\n\nPowerShell:\n\n```powershell\n$env:ESHERIA_API_BASE_URL = \"https://api.esheria.ai\"\n$env:ESHERIA_API_KEY = \"<client-api-key>\"\n```\n\n`ESHERIA_API_TOKEN` is also accepted as an alias when `ESHERIA_API_KEY` is\nunset.\n\nDo not commit API keys. The CLI and MCP server read credentials from\nenvironment variables or command-line flags and redact API key values from\ndiagnostic output. Prefer the environment variable: `--api-key` can be exposed\nthrough shell history or the operating-system process list.\n\n4. Confirm the API is reachable:\n\n```bash\nesheria --version\nesheria health --format json\nesheria ready --format json\n```\n\n5. Discover packs, choose a `domain_pack_id`, then pass that pack ID to\n   pack-specific commands:\n\n```bash\nesheria packs list --format json\nexport ESHERIA_PACK_ID=\"UK-DATA-PROTECTION-PRIVACY\"\nesheria packs inspect \"$ESHERIA_PACK_ID\" --format json\nesheria packs versions \"$ESHERIA_PACK_ID\" --format json\nesheria packs diff \"$ESHERIA_PACK_ID\" --format json\nesheria packs change-events \"$ESHERIA_PACK_ID\" --format json\nesheria obligations list \"$ESHERIA_PACK_ID\" --limit 3 --format json\nesheria penalties list \"$ESHERIA_PACK_ID\" --limit 5 --format json\nesheria legal-review audit \"$ESHERIA_PACK_ID\" --limit 5 --format json\n```\n\nOutput flags can be placed globally or on a leaf command:\n\n```bash\nesheria --format json packs list\nesheria packs list --format json\n```\n\nUse `esheria --help` and `<group> --help` to discover the full command tree.\nThe CLI includes source-watch operations, graph coverage/rebuild operations,\nworkspace-scoped customer lifecycle commands, and workspace/token/billing\nmanagement commands in addition to the read workflows above.\n\nWorkspace, token, and billing commands require a management token. Normal\ndashboard-created and OAuth connector tokens carry only `regulatory:read`.\nState-changing regulatory workflows require an explicitly created operator\ndata token with one or more of `monitoring:write`, `graph:write`, or\n`customer:write`; `regulatory:read` alone is rejected. For example:\n\n```bash\nesheria tokens create \\\n  --name \"Monitoring operator\" \\\n  --scope regulatory:read \\\n  --scope monitoring:write \\\n  --pack UK-DATA-USE-AND-ACCESS\n```\n\nThe dashboard remains the recommended place for self-serve workspace, token,\nbilling, and subscription administration. Keep operator tokens short-lived and\ngrant only the scopes and pack entitlements they require.\n\nThe CLI and MCP server are catalog-first: users list packs and then call tools\nwith the explicit pack ID they want. `ESHERIA_DEFAULT_PACK_ID` is an optional\nclient preference, not a server-side jurisdiction default.\n\nThe CLI reports the API's readiness labels, limitations, citations, and trace\nIDs; preserve them in downstream workflows. Published packs may represent a\nreviewed subset of the full legal corpus, and evaluator-gated claim verification\nis not available for every pack. Esheria output is regulatory intelligence, not\nlegal advice or a substitute for qualified counsel.\n\n## Hosted MCP\n\nProduction MCP uses the hosted Esheria endpoint:\n\n```text\nhttps://mcp.esheria.ai/mcp\n```\n\nUse this endpoint for normal customer onboarding. It avoids local Python, `uvx`,\nvirtual environments, and package discovery on the user's machine.\n\nClaude Directory hosts use OAuth. Other agent hosts send a dashboard-created\nEsheria data token as a bearer token or `X-API-Key`. The hosted MCP server\nintrospects the credential before initialization and calls the Regulatory Pack\nAPI with it, so billing, pack entitlements, trace IDs, and published-only\nbehavior remain centralized. Invalid and management-only credentials cannot\nenumerate tools.\n\n## Codex MCP\n\nSet the token where Codex can read it:\n\n```bash\nexport ESHERIA_API_KEY=\"<client-api-key>\"\n```\n\nEdit `~/.codex/config.toml` and add:\n\n```toml\n[mcp_servers.esheria]\nurl = \"https://mcp.esheria.ai/mcp\"\nbearer_token_env_var = \"ESHERIA_API_KEY\"\n```\n\nRestart Codex, then call `esheria_health`, `esheria_ready`, and\n`esheria_list_packs`.\n\n## Local MCP Fallback\n\nFor local development, or for agent hosts that do not support remote MCP URLs,\nyou can run the stdio server yourself:\n\n```bash\nesheria-mcp serve --stdio\n```\n\nOperator-only HTTP transport command:\n\n```bash\nESHERIA_API_BASE_URL=\"https://api.esheria.ai\" \\\n  esheria-mcp serve --http --host 127.0.0.1 --port 8081 --path /mcp\n```\n\nProduction is already deployed at `https://mcp.esheria.ai/mcp`; end users\nshould not run this command.\n\nThe hosted OAuth profile exposes a read-only 20-tool catalog for health, readiness, pack discovery, obligations, applicability, claim verification, versions, diffs, change events, filing calendars, evidence, penalties, audit metadata, relationship queries, exports, and citation context. Normal API data tokens expose 29 safe read/read-like tools. Operator data tokens add only mutations authorized by `monitoring:write`, `graph:write`, and/or `customer:write`, up to the complete 37-tool catalog. Every mutation\nalso requires `confirm=true`; OAuth Directory sessions remain read-only.\n\nThe hosted service uses the official MCP SDK and current Streamable HTTP.\nSuccessful tools mirror bounded JSON in text content and `structuredContent`,\nwith `trace_id` and `mcp` truncation metadata. Use the API or CLI when a\ncomplete large export is needed.\n\nUse stdio only for hosts that do not support remote MCP URLs:\n\n```toml\n[mcp_servers.esheria]\ncommand = \"uvx\"\nargs = [\"--from\", \"esheria\", \"esheria-mcp\", \"serve\", \"--stdio\"]\nenv = { ESHERIA_API_BASE_URL = \"https://api.esheria.ai\", ESHERIA_API_KEY = \"<client-api-key>\" }\n```\n\n## Claude Code\n\nUse Claude Code's remote MCP setup when your installed version exposes it:\n\n- URL: `https://mcp.esheria.ai/mcp`\n- Authorization: `Bearer <client-api-key>`\n\nIf your Claude Code version only supports local stdio MCP servers, run this\nfallback once from a terminal:\n\n```bash\nclaude mcp add --scope user --transport stdio \\\n  --env ESHERIA_API_BASE_URL=https://api.esheria.ai \\\n  --env ESHERIA_API_KEY=<client-api-key> \\\n  esheria -- uvx --from esheria esheria-mcp serve --stdio\n```\n\nThen run:\n\n```bash\nclaude mcp list\n```\n\nStart or restart Claude Code and ask it to use the Esheria MCP tools.\n\n## Claude Desktop\n\nUse Claude Desktop's remote MCP setup when your installed version exposes it:\n\n- URL: `https://mcp.esheria.ai/mcp`\n- Authorization: `Bearer <client-api-key>`\n\nIf your Claude Desktop version only supports local stdio MCP servers, use the\nfallback below.\n\nOpen the Claude Desktop MCP config file:\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nAdd or merge this object:\n\n```json\n{\n  \"mcpServers\": {\n    \"esheria\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"esheria\", \"esheria-mcp\", \"serve\", \"--stdio\"],\n      \"env\": {\n        \"ESHERIA_API_BASE_URL\": \"https://api.esheria.ai\",\n        \"ESHERIA_API_KEY\": \"<client-api-key>\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving the file.\n",
  "bytes": 8629,
  "sha": "bf76b5cdd43b2af4e1f73eca0e8eb637e3de53537473684e24125127d7261d4d",
  "repo_slug": "esherialabs/esheria-python",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_esherialabs_esheria_556f18e5/readme"
}