iri docs

Troubleshooting

Symptom Likely cause Fix
Invalid API key on startup Key revoked, typo, or wrong env name Rotate a new key; strip trailing whitespace; confirm IRI_WORKSPACE_KEY (preferred) or IRI_API_KEY
Could not connect to … IRI_SITE_URL unreachable curl $IRI_SITE_URL/api/whoami -H "x-write-key: $KEY" to confirm server is up and key is accepted
401 Missing credentials from HTTP endpoint Header not forwarded Some clients lowercase header keys — x-write-key is case-insensitive, but double-check your transport. Also accepted: Authorization: Bearer iri_ws_…
403 API key missing write scope Key is read-only Recreate with scopes: ["read","write"] (default)
404 Not found on read_note after delete_note Soft-delete working correctly Restore via /trash in the web UI
429 Rate limit exceeded Per-workspace + per-agent rate limit Back off; response carries Retry-After
Tools not visible in the client Client didn't reload the MCP config Fully quit/restart the client
iri-notes missing from Claude Code /mcp list despite .mcp.json Project-scoped servers need approval; prompt was dismissed or never fired See below
create_document returns Invalid frontmatter Missing type / agent / task All three are required — see Tool reference
HTTP request hangs Stateless transport expects single JSON-RPC per request Don't pipeline multiple calls; open a new request per call

iri-notes doesn't appear in /mcp

You added .mcp.json, restarted Claude Code, ran /mcp — and iri-notes is nowhere in the list. This is almost always the project-scoped-approval flow, not a bad config.

What's happening: Claude Code will not load a server defined in .mcp.json until you explicitly approve it for that project. Approval status lives in ~/.claude.json under projects.<path>.enabledMcpjsonServers. If that array is empty, the server is ignored.

Fix, in order:

  1. Reset and let the prompt fire again. Outside Claude Code:

    claude mcp reset-project-choices

    Fully quit Claude Code, reopen it inside the project. The trust dialog should appear — click Approve.

  2. If the prompt still doesn't appear (known flake on HTTP servers), skip .mcp.json and register at user scope — it bypasses approval entirely:

    claude mcp add --scope user --transport http iri-notes https://notes.iri-ai.com/api/mcp --header "x-write-key: iri_ws_…"

  3. Verify either way:

    claude mcp list

    You want iri-notes - ✓ Connected. If it says Needs authentication or Failed to connect, the config loaded but the key/URL is wrong — jump to the key/connectivity rows in the table above.

Is my key good?

curl -sf https://notes.iri-ai.com/api/auth/verify-key \
  -X POST -H "x-write-key: iri_ws_…" \
  | jq

{ "valid": true, … } means good. 401 or valid: false means rotate.

Debugging tool errors

Errors from tool handlers come back with isError: true on the content. If a tool silently returns nothing, check the server console:

  • Local dev: watch the terminal running npm run dev.
  • Vercel: vercel logs <deployment-url> --follow.

Still stuck?

Email hello@iri-ai.com with:

  1. Transport (HTTP / stdio)
  2. Client (Claude Code / Desktop / other)
  3. Redacted .mcp.json entry
  4. Output of the whoami tool or the verify-key curl above