Use Ronja from your AI assistant

Ronja speaks the Model Context Protocol (MCP), the open standard AI assistants use to call tools. Point an assistant such as Claude Code, Codex or Cursor at your Ronja and it can read your organization’s policy, find tables and notes, read a table’s columns, query your data, read metrics, and query databases connected to Ronja — so it answers from the same numbers and definitions Ronja does.

This is for answering questions. To have an assistant build something — an app, a workflow, an automation, a table — it uses the Ronja CLI and the API instead.

1. Add Ronja to your assistant

Every assistant needs the same address: your Ronja address followed by /api/v2/mcp, for example https://<your-ronja-address>/api/v2/mcp. There is nothing to install and no token to copy — you sign in in the next step.

Claude Code

Run:

claude mcp add --transport http ronja https://<your-ronja-address>/api/v2/mcp

Then, in Claude Code, run /mcp, pick ronja, and choose to authenticate. Your browser opens Ronja.

Codex

Add this to ~/.codex/config.toml, with your Ronja address written out:

[mcp_servers.ronja]
url = "https://<your-ronja-address>/api/v2/mcp"
tool_timeout_sec = 130
default_tools_approval_mode = "writes"

Then run codex mcp login ronja. Your browser opens Ronja.

tool_timeout_sec = 130 sets how long Codex waits for a tool above the 120 seconds a queryRonja query may take (Codex documents a 60-second default). default_tools_approval_mode = "writes" lets Codex use the read-only tools without asking each time; it still asks before queryExternal, the one tool that can reach a database outside Ronja.

Cursor

Save this as .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "ronja": {
      "url": "https://<your-ronja-address>/api/v2/mcp"
    }
  }
}

Cursor shows that the server needs you to sign in. Connect it, and your browser opens Ronja.

Claude and ChatGPT

Add a custom connector and give it the address https://<your-ronja-address>/api/v2/mcp. When you connect it, your browser opens Ronja.

2. Allow the assistant

Sign in to Ronja if you are asked to, the same way you always do.
Read the Allow an AI assistant to use Ronja? page. It names the assistant, the organization it will work in, and where you will return once you allow: a website address such as claude.ai/api/mcp/auth_callback, an app on this computer, or, for an app that opens its own kind of link, the whole link it will be sent, such as cursor://anysphere.cursor-mcp/oauth/callback.
If you belong to more than one organization, pick the right one under Organization. The assistant works in that organization only.
Click Allow. Your browser returns to the assistant, which is now connected.

Allowing creates a personal access token for the assistant, named after it and marked (MCP), on Account → Access tokens. It carries your current permissions and shrinks if your role changes, so it can never do more than you can. It expires after 90 days; the assistant then asks you to sign in again. To disconnect an assistant sooner, revoke its token there. To use another organization, sign in again from the assistant and pick that organization.

Connect with a token instead

An assistant can also use a token from the Ronja CLI. Install the CLI and run ronja login --url https://<your-ronja-address>, then load the token without showing it:

eval "$(ronja env)"

That sets RONJA_URL and RONJA_TOKEN. Start the assistant from that same terminal, so it inherits them. An Admin can instead create a token on Account → Access tokens with Create token; one Limited to scopes needs at least Data: Read (see what each tool needs). Other kinds of token, such as one from the API Tokens page, are refused.

Your token must never be written into a settings file. The configurations below name the environment variable instead.

Claude Code — save this as .mcp.json in your project folder, then run eval "$(ronja env)" && claude:
```
{
  "mcpServers": {
    "ronja": {
      "type": "http",
      "url": "${RONJA_URL}/api/v2/mcp",
      "headers": {
        "Authorization": "Bearer ${RONJA_TOKEN}"
      }
    }
  }
}
```
Don’t add the server with claude mcp add --header "Authorization: Bearer $RONJA_TOKEN": your terminal fills in the variable first, so the live token is saved in plain text in ~/.claude.json.
Cursor — use "url": "${env:RONJA_URL}/api/v2/mcp" and "headers": { "Authorization": "Bearer ${env:RONJA_TOKEN}" } in .cursor/mcp.json. Quit Cursor completely first, then start it from the terminal where you ran eval "$(ronja env)", for example with cursor ..
Codex — add bearer_token_env_var = "RONJA_TOKEN" to the [mcp_servers.ronja] section above, then run eval "$(ronja env)" && codex. The Codex app only has your token if it was started from that terminal.

What each tool needs

The assistant should call instructions first — it explains the rest, in the order to use them. A token from signing in, or from ronja login, can use every tool your role allows. A token limited to scopes needs:

Tool	What it does	Scopes (Read)
`instructions`	How to work with Ronja’s tools	Data
`getPolicy`	Your organization’s policy	Data, Analytics
`find`	Find anything by describing it	Data
`list`	List resources by kind, feature, name or tag	Data, plus each kind’s own scope
`getTable`	Read a table’s columns, with their types and statistics, its description, and its health checks with whether each passes — the assistant reads it before writing SQL	Data — plus Analytics to also see the organization Knowledge entries attached to the table
`searchSchema`	List every column of a wide table, or the fields inside a nested column	Data
`getNote`	Read notes in full	Data, Analytics
`queryRonja`	SQL over your Ronja tables	Data
`queryMetric`	Read a metric at any grain and breakdown	Data
`queryExternal`	SQL against a connected database, through a stored secret	Data, Secrets

For list, each kind needs the scope that covers it in Token scopes: notes and apps need Analytics, secrets Secrets, workflows and automations Automation, Saved Agents, MCP servers and chats Agents, and managed databases Structure.

Limits

Answers are capped: queryRonja returns at most 10,000 rows (and about 32 KB of text), queryMetric 50,000, and queryExternal shows a preview of at most 100 rows. When a result is cut short it says so, and the assistant should aggregate in SQL rather than page.
A queryRonja query stops after 120 seconds, and a queryRonja or queryMetric query that reads more than 1 GB of table data is refused rather than run — the assistant should filter or aggregate so it reads less, or you can ask the same question in Ronja.
getTable shows at most 50 columns of a table; for a wider one the assistant lists the rest with searchSchema.
An assistant can have at most 3 queries running at once for one token; a fourth is turned away until one finishes.
A failed call comes back as an error the assistant can read — a missing scope is named, and a query that fails says why.

If the assistant can’t connect

“Unauthorized” or 401, often inside a longer connection error — the assistant’s token has expired, was revoked, or belongs to another Ronja address. If you signed in, sign in again from the assistant (in Claude Code, /mcp). With a CLI token, run ronja login again, then eval "$(ronja env)", and restart the assistant.
This sign-in link can’t be used — Ronja doesn’t recognize the assistant, or the page it was sent back to isn’t one the assistant registered. Remove Ronja from the assistant, add it again, and sign in.
“RONJA_TOKEN is not set” — the assistant was started without your CLI token. Run eval "$(ronja env)" and start it again from that terminal.
“pat_required” — the token isn’t a personal access token, for example one from the API Tokens page. Sign in from the assistant instead, or use one from ronja login or Account → Access tokens.

Use the Ronja CLI — signing in, and building from the terminal.
API reference — personal access tokens and scopes.
Connect MCP servers — the other direction: Ronja using other MCP servers.