# Ornix > Ornix is a learning planner for self-study: it plans a dated, week-by-week roadmap around a learner's hours, shows the next goal each day, and keeps a learning memory that Claude, ChatGPT and other MCP clients can read. --- ## Ornix docs Connect Claude, ChatGPT, Cursor or another MCP client to your roadmaps. The docs cover setup for each client, every tool it can call, and Markdown versions of the docs and public pages. Source: https://ornix.io/docs ### Start here - [Connect your AI](https://ornix.io/docs/mcp): Point Claude, ChatGPT or any MCP-compatible client at Ornix and give it access to your roadmaps, notes and progress. - [Tool reference](https://ornix.io/docs/mcp/tools): Every tool the connector exposes, grouped by access tier, with what each one does and its parameters. ### Quick start Connect Claude to your roadmaps in three steps. 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 ``` Using ChatGPT, Claude Code, Codex, Cursor, VS Code, Windsurf, OpenCode or another MCP client instead? Each has its own setup in [Connect your client](https://ornix.io/docs/mcp#connect-your-client). You can also pick your app under Settings → Connected AI in Ornix. ### Docs for AI The docs, pricing, ready roadmaps and every public roadmap and note are plain Markdown too, so an assistant can read them directly. Use Copy page at the top of any docs page to copy it as Markdown, or open it in ChatGPT or Claude. Append `.md` to a URL to fetch the Markdown version, for example `/docs/mcp.md` or `/pricing.md`, or request the normal URL with an `Accept: text/markdown` header. ```bash curl -H 'Accept: text/markdown' https://ornix.io/docs/mcp ``` - [llms.txt](https://ornix.io/llms.txt): what Ornix is, the MCP endpoint, featured roadmaps and how agents should work with a learner's roadmap. - [llms-full.txt](https://ornix.io/llms-full.txt): every docs page in one Markdown file. --- ## 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. Source: https://ornix.io/docs/mcp ### 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 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. ##### ChatGPT Needs ChatGPT Developer mode, a beta on paid plans. What it allows depends on your plan and workspace settings. 1. In ChatGPT, open Settings → Apps & Connectors → Advanced settings and turn on Developer mode. 2. Back in Apps & Connectors, click Create. 3. Name it Ornix, paste the connector URL and choose OAuth. 4. In a new chat, open the + menu, choose Developer mode and turn on Ornix. **Connector URL** ```text https://mcp.ornix.io/mcp ``` ChatGPT opens Ornix in a new tab: sign in, then approve access. ##### Claude Code Needs the Claude Code CLI. 1. Run the command below in a terminal. 2. Start Claude Code and run `/mcp`, then choose ornix to sign in. ```bash claude mcp add --transport http ornix https://mcp.ornix.io/mcp ``` Your browser opens Ornix. Sign in if asked, then approve access on the consent screen. ##### Codex Needs the Codex CLI. The Codex IDE extension reads the same config. 1. Run the add command, or put the block in `~/.codex/config.toml` yourself. 2. Run `codex mcp login ornix` to sign in. Add `--no-browser` on a machine without a browser. ```bash codex mcp add ornix --url https://mcp.ornix.io/mcp ``` **~/.codex/config.toml** ```text [mcp_servers.ornix] url = "https://mcp.ornix.io/mcp" ``` ```bash codex mcp login ornix ``` Your browser opens Ornix. Sign in if asked, then approve access on the consent screen. ##### Cursor Needs the Cursor desktop app. 1. Click Add to Cursor and confirm the install, or add the block to `~/.cursor/mcp.json`. 2. In Cursor Settings → MCP, click Connect next to ornix. [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=ornix&config=eyJ1cmwiOiJodHRwczovL21jcC5vcm5peC5pby9tY3AifQ%3D%3D) **~/.cursor/mcp.json** ```json { "mcpServers": { "ornix": { "url": "https://mcp.ornix.io/mcp" } } } ``` Your browser opens Ornix. Sign in if asked, then approve access on the consent screen. ##### VS Code Needs VS Code desktop with GitHub Copilot chat in agent mode. 1. Click Add to VS Code, or add the block to `.vscode/mcp.json`. 2. Start the ornix server when VS Code asks, and allow it to sign in. [Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22ornix%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.ornix.io%2Fmcp%22%7D) **.vscode/mcp.json** ```json { "servers": { "ornix": { "type": "http", "url": "https://mcp.ornix.io/mcp" } } } ``` Your browser opens Ornix. Sign in if asked, then approve access on the consent screen. ##### Windsurf Same JSON shape as Cursor, in Windsurf's own config file. **~/.codeium/windsurf/mcp_config.json** ```json { "mcpServers": { "ornix": { "url": "https://mcp.ornix.io/mcp" } } } ``` ##### OpenCode Add Ornix as a remote server in your OpenCode config, then authorize it. **opencode.json** ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "ornix": { "type": "remote", "url": "https://mcp.ornix.io/mcp", "oauth": {} } } } ``` ```bash opencode mcp auth ornix ``` OpenCode opens your browser for sign-in and consent. Run opencode mcp list to check the connection. ##### Any MCP client Works with any client that supports remote MCP servers over streamable HTTP with OAuth sign-in and dynamic client registration. 1. Add a remote server named ornix with the connector URL, using HTTP transport (not SSE or stdio). 2. Leave API keys and headers empty. Ornix uses OAuth, not a static key. **Connector URL** ```text https://mcp.ornix.io/mcp ``` ```json { "mcpServers": { "ornix": { "type": "http", "url": "https://mcp.ornix.io/mcp" } } } ``` When the client connects, it opens Ornix in your browser: sign in, then approve access. Clients that only accept a pre-registered client ID or an API key can't connect. ### 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](https://ornix.io/account?category=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](https://ornix.io/docs/mcp/tools) Already connected? Manage access, or lower the tier at any time. [Connected AI settings](https://ornix.io/account?category=connected-ai) --- ## MCP tool reference Every tool the Ornix MCP connector registers — 42 in total — grouped by access tier, with parameters and what each one touches. Source: https://ornix.io/docs/mcp/tools ### Overview The connector registers 42 tools, all prefixed `ornix_`. Your account's access tier — read, write, or full — is the most any authorized app can call, and you can limit each app further under Connected apps. Structural roadmap changes from any tier are proposals you apply on the roadmap. Haven't connected yet? Start with [connector setup](https://ornix.io/docs/mcp). ### Read Runs without asking, since nothing here changes your data — the default tier for every new connection. - `ornix_get_context` (Plans): Resume where the learner left off: the current roadmap, current week, what is due today, and a short learning-memory brief. Call it first in a new conversation. - Parameters: `plan?` - `ornix_list_plans` (Plans): List your roadmaps — status, progress, and current week for each. - Parameters: `status?, limit ≤100 (default 20), cursor?` - `ornix_get_plan` (Plans): Pull a roadmap's outline — phases, weeks, and which goals are done. Narrow to one phase or a set of week ids. - Parameters: `plan, format: concise | detailed, phase?, week_ids?` - `ornix_get_week` (Weeks): Zoom into one week: goals, resources, the concepts it teaches, its note list, flashcard counts, and what your learning memory says about it. - Parameters: `plan, week_id, include_notes?` - `ornix_get_progress` (Progress): Streaks, due-card count, and how each plan tracks against schedule. Scope to one plan to also get today's queue. - Parameters: `plan?` - `ornix_list_notes` (Notes): List the notes on a plan, optionally filtered to one week. - Parameters: `plan, week_id?, limit ≤200 (default 50), cursor?` - `ornix_get_note` (Notes): Read one note in full, including its markdown body. - Parameters: `id — or plan + slug` - `ornix_get_due_cards` (Flashcards): Fetch the flashcards due for a study session, across one plan or all of them. - Parameters: `plan?, limit ≤200 (default 50)` - `ornix_flashcard_stats` (Flashcards): Deck summaries — due/new counts, retention, a 7-day review count, and the review forecast. - Parameters: `plan?` - `ornix_list_labs` (Labs): List the interactive labs attached to one week (titles and summaries, no HTML). - Parameters: `plan, week_id` - `ornix_get_lab` (Labs): Fetch one lab in full, including its HTML, so you can read or revise it. - Parameters: `lab_id` - `ornix_get_memory` (Memory): Read a roadmap's learning memory — concept mastery with evidence, open misconceptions, next steps, your background, and past session recaps. Entries show #ids for ornix_remember. - Parameters: `plan, week_id?, kind?, include_resolved?, limit ≤100 (default 30), response_format? (concise | detailed), cursor?` - `ornix_get_flashcard` (Flashcards): Fetch one flashcard including its back, for grading a single answer. - Parameters: `card_id` - `ornix_get_visual` (Notes): Fetch one visual's full content (widget HTML or mermaid source) by id, after a note reports its visuals collapsed. - Parameters: `note, plan?, visual_id` - `ornix_list_resources` (Library): List the documents you uploaded and the links you saved to your library. - Parameters: `status?, limit ≤100 (default 20), cursor?` - `ornix_get_resource` (Library): Read a windowed slice of one library document's extracted text; page through large documents instead of pulling them whole. - Parameters: `id, offset_chars?, limit_chars ≤20000 (default 8000)` - `ornix_search_resources` (Library): Full-text search inside your uploaded documents, returning matching excerpts with resource ids. - Parameters: `q, limit ≤25 (default 10)` - `ornix_search` (Search): Search across plans, notes, flashcards, and the public resource catalog. - Parameters: `query, types?, limit ≤50 (default 10)` ### Write Prompts before running, with an “Allow always” option per chat — requires write tier or above. - `ornix_create_plan` (Plans): Author a brand-new roadmap in one call — phases, weeks, goals, and resources — and Ornix stores, schedules, and starts tracking it. - Parameters: `title, summary?, start_date?, prerequisites?, phases[] (≤10 phases, ≤60 weeks total)` - `ornix_update_plan` (Plans): Rename a roadmap, shift its start date, recover it from a failed status, or switch it between private/public visibility. - Parameters: `title?, start_date?, status? ("ready" to recover from failed), visibility?` - `ornix_complete_goals` (Plans): Mark one or more goals done or undone in a single batch; completing every goal in a week finishes it and extends the streak. - Parameters: `updates[]: week_id, goal_index, done (≤100 per call)` - `ornix_get_timeline` (Plans): See the schedule for every week, plus how far it's drifted from the original dates. - Parameters: `plan` - `ornix_shift_schedule` (Plans): Push every remaining date out by N days, or resync the whole schedule to a resume date. - Parameters: `days or resume_date (exactly one)` - `ornix_update_week` (Plans): Edit a single week's content — goals, focus, resources — without touching the rest of the plan. - Parameters: `plan, week_id, fields to update` - `ornix_insert_week` (Plans): Add a hand-authored week into the plan at a given position. - Parameters: `plan, position, week content` - `ornix_remove_week` (Plans): Remove a week from the plan and renumber the weeks that follow. - Parameters: `plan, week_id` - `ornix_undo_plan_edit` (Plans): Revert the plan's last structural edit — available for 3 days after the edit. - Parameters: `plan` - `ornix_create_note` (Notes): Write a new note on a plan, optionally scoped to one week. - Parameters: `plan, week_id?, title?, body_md? (≤100k chars)` - `ornix_update_note` (Notes): Replace a note's body, append to it, or rename it — pass body_md or append, never both. - Parameters: `body_md or append (exactly one), title?` - `ornix_update_visual` (Notes): Edit a generated visual in place — replace its widget HTML or mermaid source without appending a new one. - Parameters: `note, plan?, visual_id, html or source (exactly one), prompt?` - `ornix_create_note_visual` (Notes): Add a visual to a note. You write it yourself: widget HTML (self-contained, one inline style and script, no network, up to 80,000 characters) or mermaid source (up to 8,000 characters). Ornix stores it and does not generate it from a prompt. - Parameters: `note_id, plan?, kind: widget | mermaid, html (widget) or source (mermaid), anchor?` - `ornix_create_lab` (Labs): Author an interactive lab for a week and attach it to the week canvas. You write the HTML: one inline style and one inline script, no network, sized to fill the viewport, themed with the --ornix-* CSS variables, with a stepped story and Play/Pause/Step/Reset controls. Up to 100,000 characters. - Parameters: `plan, week_id, title, html, summary?` - `ornix_update_lab` (Labs): Revise a lab in place: replace its HTML, title or summary. - Parameters: `lab_id, html?, title?, summary?` - `ornix_remember` (Memory): Save what your AI learned about you on a roadmap — mastery with evidence, misconceptions, next steps, background, and a session recap — so the next session, in any AI app, picks up where this one stopped. - Parameters: `plan, memory_version, entries[]?, resolve[]?, recap? (≤12 entries per call)` - `ornix_create_flashcards` (Flashcards): Turn a note or a conversation into up to 50 flashcards in one batch. - Parameters: `plan, week_id?, note_id?, cards[]: front_md, back_md (≤50)` - `ornix_review_flashcard` (Flashcards): Grade one flashcard and log a real spaced-repetition review, updating its due date. - Parameters: `card_id, rating: again | hard | good | easy` - `ornix_undo_review` (Flashcards): Undo your single most recent flashcard review, across any plan. - Parameters: none ### Destructive Requires full tier, the highest access level — how much confirmation each tool adds varies (see below). > **Confirmation varies by tool.** `ornix_delete_plan`, `ornix_delete_note`, `ornix_delete_flashcard`, and `ornix_delete_lab` only propose the deletion: nothing is removed until you apply it on the roadmap. `ornix_delete_plan` also requires the caller to state the plan's exact title back. `ornix_forget` acts straight away and relies on your AI client's own confirmation prompt before it calls the tool. - `ornix_delete_plan` (Plans): Propose deleting a roadmap and everything on it — weeks, notes, and flashcards. Requires the plan's exact title as confirmation; nothing is removed until you apply it. - Parameters: `plan, confirm_title (must match exactly)` - `ornix_delete_note` (Notes): Propose deleting a single note; it is removed once you apply it. - Parameters: `id` - `ornix_delete_flashcard` (Flashcards): Propose deleting a single flashcard; it is removed once you apply it. - Parameters: `id` - `ornix_delete_lab` (Labs): Propose deleting a lab from its week; it is removed once you apply it. - Parameters: `lab_id` - `ornix_forget` (Memory): Permanently delete learning-memory entries by #id, for when you ask your AI to forget something. - Parameters: `plan, ids (1–50)` ### Prompt library Four of these are wired in as canned prompts on the connector itself — `weekly_review`, `study_session`, `tutor_session`, and `capture_notes` — they show up as slash commands in Claude Code and in claude.ai's + menu, so you don't have to type the prompt at all. The rest are plain prompts — copy, paste, and edit the specifics. #### Create a roadmap ```text I want to learn systems design well enough to pass senior-level interviews in about 4 months. I can put in 6-8 hours a week, and I'm coming from 3 years as a backend engineer. Ask me whatever you need, then build the full roadmap in Ornix. ``` Your AI interviews you, then authors the whole plan — phases, weeks, goals, and resources — as one structured roadmap with ornix_create_plan. Ornix takes it from there: storing it, scheduling it week by week, and tracking your progress. #### Weekly review Slash command: `/weekly_review` ```text Run my weekly review — what's my progress, what's due this week, and am I on track? Mark anything I've actually finished, and if I'm behind, suggest a replan. ``` #### Study session Slash command: `/study_session` ```text Quiz me on my due flashcards for the ML roadmap. Ask one at a time, don't show me the answer first, and log my rating after each one. ``` #### Tutor session Slash command: `/tutor_session` ```text Tutor me on my systems-design roadmap, week 4. Pick up from what you remember about me, teach one concept at a time, and save what my answers show as we go. ``` Your AI reads the roadmap's learning memory first, so it starts from where you left off and what you still get wrong, then records mastery, misconceptions, and next steps as the session goes. Turn off AI updates in Memory and it only reads. #### Capture notes → flashcards Slash command: `/capture_notes` ```text Turn what we just talked about into a note on week 6 of my systems-design plan, and pull 5 flashcards out of the key ideas. ``` #### Explain & quiz ```text Walk me through week 4 of my AI roadmap like you're teaching it fresh, then quiz me on it and log my answers as flashcard reviews so it feeds my spaced repetition. ``` #### Replan when life happens ```text I was out sick for 10 days and I'm three weeks behind on my chemistry roadmap. Replan the rest of it around where I actually am — don't touch the weeks I've already finished. ``` [Back to connector setup](https://ornix.io/docs/mcp)