OrnixBeta

Search docs

Jump to any page in the Ornix docs.

Log inStart free
MCP connector

Connect your AI to Ornix

Point Claude, ChatGPT, Cursor, or any MCP-compatible client at Ornix's hosted connector and it can read — or, once you allow it, write — your roadmaps, notes, flashcards, and progress.

What this is

A hosted Model Context Protocol endpoint — no server to run yourself.

The Ornix MCP connector is a hosted endpoint that speaks the Model Context Protocol over streamable HTTP. Point any MCP-aware client at it and, once you sign in, it can read your roadmaps, weeks, notes, flashcards, and progress directly in the conversation.

Every new connection starts read-only. Nothing gets created, changed, or deleted until you raise the access tier in your account settings.

Connect

Every client below points at the same URL — only the setup screen differs.

Connector URL
Text
https://mcp.ornix.io/mcp

No static API keys

Sign-in and consent happen in your browser the first time a client connects. Ornix issues short-lived OAuth tokens through Supabase, not a key you paste in.

Connect your client

claude.ai in any browser, or Claude Desktop. Nothing to install.

  1. In claude.ai or Claude Desktop, open Settings → Connectors.
  2. Click Add custom connector.
  3. Name it Ornix and paste the connector URL.
Connector URL
Text
https://mcp.ornix.io/mcp

Click Connect. Claude opens Ornix in your browser: sign in, then approve access.

Access tiers

One account-wide ceiling, three tiers, and an optional lower limit per app.

Read only
Default

View roadmaps, notes, flashcards, and progress. Can't change anything. Default for every new connection.

Read & write

Adds creating roadmaps, notes, and flashcards, editing notes and cards, completing goals, and reviewing cards. Adding, rewriting or removing a week, moving the schedule or start date, and publishing are proposed for you to apply.

Full access

Adds deleting roadmaps, notes, flashcards, and labs, each proposed for you to apply, and forgetting Memory notes.

Structural changes never happen straight from the AI: adding, rewriting or removing a week, shifting the schedule, changing the start date, publishing, and deleting a roadmap, note, flashcard or lab are saved as proposals. They appear on the roadmap with Apply and Discard, and nothing changes until you apply them. Forgetting Memory notes stays direct, since it removes only what the AI wrote about you.

Limit or disconnect one app

Under Connected apps, each authorized app has its own access setting and a Revoke button. Revoking blocks that app on its next call and also revokes its grant, so it must be approved again to reconnect. Every write an app makes is logged with that app's id.
Manage connected AI

How authentication works

Ornix never issues a static API key — every client authorizes through Supabase's OAuth 2.1 server.

  1. Your client opens Ornix's /oauth/consent page in a browser and asks to be authorized.
  2. If you haven't approved that client before, you see a consent screen listing the requested scopes and what the connector can do, capped by your account's access tier.
  3. Approving redirects the client back with an authorization code, which it exchanges for a Supabase-issued access token and refresh token. Ornix never generates a long-lived API key for this flow.
  4. Every call to Ornix's connector API carries that token as an Authorization: Bearer header, verified against the Supabase project's signing keys on every single request.
  5. Once verified, the request runs as you and is capped at your account's connector access tier — read, unless you've raised it — and at that app's own limit if you set one under Connected apps.

The authorization server is Supabase Auth's own OAuth 2.1 server — Ornix's code only supplies the consent screen and the per-request tier check on top of it. A revoked or expired grant fails the same way an invalid token does: every call returns 401 until you reconnect through the client's setup flow again.

Troubleshooting

Real failure modes, by the error a client actually shows you.

401 unauthorized — "Missing or invalid bearer token"

Your session token expired, or the OAuth grant behind it was revoked. Reconnect through the client's setup flow (the Connectors screen, or claude mcp add again) to get a fresh token.

403 forbidden_tier

The tool needs a higher access tier than your account is set to — for example a write tool on a read-only connection. Raise the tier in Account → Connected AI; it applies on the client's next call, no reconnect needed.

403 insufficient_scope

Your account allows the tool, but you limited this one app below it under Account → Connected AI → Connected apps. Raise that app's access there; other apps are not affected.

401 client_revoked

You disconnected this app under Connected apps. Connect it again from the app's own setup flow and approve it to restore access.

403 forbidden — "Not your plan"

The client is pointing at a plan ID it no longer has access to. Not a bug on your end — have it list your plans again instead of reusing a stale ID.

404 not_found

The plan, note, or flashcard doesn't exist anymore, or the ID or slug is wrong.

413 too_large

The write hit a size cap — too many phases or weeks in one authored roadmap, or a note body over the limit. Split it into smaller calls.

Client shows the connector as unreachable

Check it's using streamable HTTP transport at the exact URL above, not SSE or stdio. Some clients also cache old connector metadata after a URL change — remove and re-add the connector to clear it.

VS Code: invalid redirect URI

VS Code signs in through port 33418 on your machine. If another program holds that port, sign-in can fail. Close it, or restart VS Code, then start the ornix server again.

ChatGPT: no Create button for connectors

Custom connectors need Developer mode, under Settings → Apps & Connectors → Advanced settings. Some plans and workspaces don't offer it, or limit what it can do.

Client asks for a client ID or an API key

Ornix only supports OAuth with dynamic client registration. Leave those fields empty; if the client can't connect without them, it can't use Ornix yet.

Nothing happens after you approve

The consent screen needs you already signed in to Ornix in that browser. Log in at ornix.io first, then retry the client's connect flow.

Tools & prompts

42 tools, grouped by how much they touch your data, plus a library of prompts to try.

Reads run silently; writing and deleting always need the tier raised first. The full reference — every tool, its arguments, and a copy-paste prompt library — lives on its own page.

Browse the tool reference

Already connected? Manage access, or lower the tier at any time.

Connected AI settings