---
name: isodora-mcp
description: >
  Connect agent hosts to Isodora's MCP server at /api/mcp (Streamable HTTP).
  Use for Cursor, Claude Code, VS Code, mcp-remote, n8n MCP, or AI SDK
  experimental_createMCPClient. Covers host configs, whoami-first workflow,
  customer tool catalog, write-scope gates, and platform-only tools to avoid.
  Requires a personal API key (isk_u_*) from Settings → API keys.
metadata:
  author: isodora
  version: "1.0.0"
  parent: isodora
---

# Isodora MCP

Endpoint (Streamable HTTP):

- EU: `https://app.isodora.se/api/mcp`
- US: `https://app.isodora.app/api/mcp`

Auth header: `Authorization: Bearer isk_u_…`

**Prerequisite:** `isodora-keys`. Host JSON templates: [references/host-configs.md](references/host-configs.md). Tool catalog: [references/tools.md](references/tools.md).

OAuth for Claude.ai web / ChatGPT hosted connectors is **not** supported yet — use bearer keys or `mcp-remote` for stdio-only hosts.

---

## Always call `whoami` first

Returns the user, effective organizations, writability, and key metadata. Most auth bugs are explained here before any compliance tool runs.

Then typical reads:

1. `list_organizations`
2. `list_projects` / `get_compliance_overview`
3. `list_gap_findings` / `list_remediation_tasks`

---

## Customer tools (personal keys)

**Read:** `whoami`, `list_organizations`, `list_projects`, `get_project`, `get_organization_context`, `get_compliance_overview`, `list_gap_findings`, `list_remediation_tasks`, `search_requirements`, `get_requirement_evidence`, `search_documents`, `list_project_documents`, `list_risks`, `list_suppliers` (QMS).

**Write** (requires Read & write key): `update_task_status`, `update_gap_status`, `import_project_document`, `get_document_ingestion_status`.

**Not for personal keys / default customer path:** `provision_customer_organization`, `analyze_website_for_provisioning`, migration preview/commit — platform-oriented.

After connecting, prefer live `tools/list` over this cached catalog.

---

## Quick Cursor config

```json
{
  "mcpServers": {
    "isodora": {
      "url": "https://app.isodora.se/api/mcp",
      "headers": {
        "Authorization": "Bearer isk_u_…"
      }
    }
  }
}
```

Use `app.isodora.app` for US keys. Prefer env-substituted secrets over pasting plaintext into committed `.cursor/mcp.json`.

---

## Claude Code

```bash
claude mcp add --transport http isodora https://app.isodora.se/api/mcp \
  --header "Authorization: Bearer $ISODORA_API_KEY"
```

---

## Rules

- Do not call write tools with a read-only key — expect `forbidden_scope` / role errors.
- `search_documents` and imports can burn AI credits / hit import quota.
- Same region rule as REST.