iri docs

MCP overview

iri-notes speaks the Model Context Protocol so any MCP-capable client (Claude Code, Claude Desktop, Cursor, Cline, Zed, custom) can read your notes, push new ones, query the knowledge graph, and coordinate work on the task board.

Two transports

Hosted HTTP Local stdio
URL / command POST /api/mcp npx tsx mcp/server.ts
Setup URL + key header, no local install Requires Node on the user's machine
Best for Anyone connecting to a deployed iri Clients that don't yet support HTTP MCP

Both speak the same tool surface.

→ Hosted HTTP · Local stdio

Auth at a glance

All MCP requests carry a key as x-write-key (or Authorization: Bearer). Workspace keys (iri_ws_…, created at /workspaces/<slug> → API Keys) are preferred for MCP — they bind to a single workspace and carry an agent identity. Per-user keys (iri_…) also work.

Recommended bootstrap flow

When an agent starts a session, it should orient itself before doing work. Three discovery tools answer the obvious questions:

  1. whoami — "who am I, where am I?" Returns {valid, keyType, username, displayName, workspace: {id, slug, name}, agentId, sphereCount}. Tells the agent which workspace the key is bound to and how many spheres it can see.

  2. list_workspaces — "what workspaces am I at?" For workspace-bound keys this returns the single bound workspace. For personal user keys it returns every workspace the user belongs to.

  3. list_spheres — "what spheres do I have?" Lists spheres (sub-team / project memory areas) the caller can access, with slug, name, visibility, role, memberCount. Workspace-bound keys only see spheres in the bound workspace. Use the slug to scope subsequent calls.

Then pick the right read tool for the job:

  • Topic-relevant content → search_notes (semantic hybrid search) or get_briefing (curated, atom-grade synthesis).
  • What was just touched → list_notes with sort: "recent" and a small limit.
  • Specific entity → explore_entity or query_atoms.

Tool catalog

Full reference at MCP → Tool reference. 35 tools, grouped:

  • Identity & discovery — whoami, list_workspaces, list_spheres
  • Workspace lifecycle — create_workspace, delete_workspace (destructive; gated by confirm_slug matching the target slug exactly)
  • Sphere lifecycle — create_sphere, delete_sphere (destructive, CASCADE; same confirm_slug gate)
  • Workspace API keys — list_workspace_api_keys, create_workspace_api_key, revoke_workspace_api_key (admin-only; plaintext key returned once on create)
  • Notes CRUD — list_notes, read_note, list_sphere_notes, search_notes, create_note, inbox, update_note, delete_note, move_note
  • Folder memory — get_folder_memory, update_folder_memory (revision-based concurrency, 3-way merge on conflict)
  • Agent write-back — create_document (structured, feeds atoms)
  • Knowledge graph — get_briefing, query_atoms, get_contradictions, memory_status, explore_entity
  • Task board — create_task, list_tasks, update_task, claim_task, start_task, complete_task, assign_task, release_task, cancel_task

Troubleshooting

If something doesn't connect, start at MCP → Troubleshooting.