Getting started (end-to-end)

This is the full path from zero to a working itera-mcp connection and your first authoring call. Budget about five minutes.

0 · Prerequisites

You'll need

An Itera account with an author role in at least one tenant. How you get one depends on who you are — see Authentication. Internal DFL teachers federate from their DFL login; third-party instructors get an Itera Supabase account provisioned by their Itera admin.
An Itera Supabase access token (JWT) — this is what the MCP authenticates. See how to obtain a token.
An MCP-compatible client: Claude Code, Cursor, VS Code, codex, or the Anthropic SDK. Any one is fine — or just curl.

1 · Get an author-role token

The MCP validates an Itera Supabase user-JWT (HS256, signed by the Itera project) and reads your author memberships from it. A token from any other project (e.g. DFL prod) fails signature verification and is rejected.

Internal DFL teacher → exchange your DFL session for an Itera session via POST https://api.iterahq.dev/v1/embed/session, then use the returned access_token. See Authentication → Internal DFL teacher.
Third-party instructor → sign in to your Itera Supabase account and use that session’s access_token. See Authentication → Third-party instructor.

Once you have a token, self-check your authoring rights with the whoami tool (step 4) — it returns your memberships and the tenant ids you can author in.

2 · Configure your client

Pick your client below. Replace YOUR_ITERA_JWT with the access token from step 1.

Add to your project’s .mcp.json (or the global ~/.claude/mcp.json):

{
  "mcpServers": {
    "itera": {
      "type": "http",
      "url": "https://mcp.iterahq.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_ITERA_JWT" }
    }
  }
}

Then restart Claude Code (or run /mcp to reconnect). The Itera authoring tools (create_program, create_lesson, …) appear.

Cursor needs mcp-remote as a proxy so the Authorization header is passed through. Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "itera": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.iterahq.dev/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${ITERA_TOKEN}"
      ],
      "env": { "ITERA_TOKEN": "Bearer YOUR_ITERA_JWT" }
    }
  }
}

VS Code (1.102+) has native MCP support. Add to .vscode/mcp.json (or run MCP: Add Server):

{
  "servers": {
    "itera": {
      "type": "http",
      "url": "https://mcp.iterahq.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_ITERA_JWT" }
    }
  }
}

Add the server to ~/.codex/config.toml:

[[mcp_servers]]
name = "itera"
url = "https://mcp.iterahq.dev/mcp"
[mcp_servers.headers]
Authorization = "Bearer YOUR_ITERA_JWT"

Paperclip reads MCP servers from its agent config. Add an HTTP server entry:

{
  "itera": {
    "type": "http",
    "url": "https://mcp.iterahq.dev/mcp",
    "headers": { "Authorization": "Bearer YOUR_ITERA_JWT" }
  }
}

Pass the endpoint in the mcp_servers array:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    mcp_servers=[
        {
            "type": "url",
            "url": "https://mcp.iterahq.dev/mcp",
            "name": "itera",
            "authorization_token": "YOUR_ITERA_JWT",
        },
    ],
    messages=[{"role": "user", "content": "List the Itera tenants I can author in."}],
)

No client needed — initialize a session directly. The transport is Streamable-HTTP; advertise both application/json and text/event-stream in Accept:

curl -X POST https://mcp.iterahq.dev/mcp \
  -H "Authorization: Bearer YOUR_ITERA_JWT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "curl-test", "version": "1.0.0" }
    }
  }'

The response carries an mcp-session-id header — send it back on subsequent tools/call requests.

3 · Make your first authoring calls

Once connected, just ask in natural language — the model picks the tool:

“Which Itera tenants can I author in?” → calls whoami

“Create a program called ‘Intro to Kafka’ in my tenant, then add a first unit and lesson.” → create_program → create_unit → create_lesson

Every level takes the parent id returned by the previous call. The end-to-end sequence, with real inputs/outputs, is in Recipes → Author a full course.

4 · Self-check with `whoami`

Before writing, confirm your permissions. whoami returns your memberships and the tenant ids where your role is author / instructor / tenant_admin / owner:

{
  "memberships": [
    { "tenant_id": "8f3c…", "role": "author", "created_at": "2026-07-01T…" }
  ],
  "author_tenant_ids": ["8f3c…"]
}

Use a tenant_id from author_tenant_ids as the tenant_id argument to create_program. If the list is empty, you don’t yet have an authoring role — see Authentication.

5 · Troubleshooting

`-32001` / `401` — token rejected

Your JWT is missing, expired, or from the wrong project. The MCP only accepts tokens signed by the Itera Supabase project. A DFL token will fail signature verification. Re-mint via the flow in Authentication, or refresh (below).

Writes return “Permission denied” / empty result

You’re authenticated but your role lacks authoring rights for that tenant. Writes require author / instructor / tenant_admin / owner on the target tenant (RLS). Learners can read but not write. Check whoami.

Token refresh

Itera tokens are short-lived. Renew without a fresh login by posting your refresh token to the MCP’s refresh proxy (no auth header needed):

curl -X POST https://mcp.iterahq.dev/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'

It returns a new access_token + refresh_token.

Rate limited

The endpoint rate-limits (~100 req/min by default, keyed to your user id). Back off and retry.

Next: the lesson model Program → Unit → Lesson → Activity, the ten activity kinds, and the spec / rubric / title_i18n shapes you'll pass to the tools.