# 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)
