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 the policy Ronja follows for you, 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. ronja context tells the assistant when your CLI is out of date and names the update to run. The assistant runs it once; when it can’t, it tells you and carries on.
1. Add Ronja to your assistant
Section titled “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
Section titled “Claude Code”For a step-by-step walkthrough with screenshots, see Connect Claude to Ronja. Run:
claude mcp add --transport http ronja https://<your-ronja-address>/api/v2/mcpThen, in Claude Code, run /mcp, pick ronja, and choose to authenticate. Your browser opens Ronja.
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 = 130default_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
Section titled “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
Section titled “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. For Claude, Connect Claude to Ronja walks through it step by step, including what your company’s Claude admin does.
2. Allow the assistant
Section titled “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 and the organization it will work in, and says what the assistant can do there: read what you can read in Ronja without changing anything in Ronja, and, on a database connected to Ronja, whatever that database’s own account allows. It also shows 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 ascursor://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 read-only personal access token for the assistant, named after it and marked (MCP), on Account → Access tokens. It has Read on every scope except Admin, which is everything the assistant’s tools need, so the token can’t change anything in Ronja, even if it is used outside the assistant. Only an Admin can widen it, from its page, as with any personal access token. It carries your current permissions and shrinks if your role changes, so it can never read more than you can.
The token lasts 90 days, and the assistant renews it while it keeps using Ronja, for up to a year; it ends after six months unused. You then sign in again from the assistant, as you do if you leave the organization (the token is deleted; if you are added back, connect the assistant again). To disconnect an assistant sooner, revoke its token there: that ends the sign-in at once. If an Admin changes the token’s Expires date or clicks Clear (never expires) on its page in API Tokens (in the admin sidebar, under People & Access), the renewals stop: the assistant signs in again the next time it needs to renew, and that token stays until the date set or, with no expiry, until it is revoked. Revoke it if it is no longer needed. To use another organization, sign in again from the assistant and pick that organization.
Connect with a token instead
Section titled “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. Unlike signing in from the assistant, the CLI’s token has full access, because the CLI builds things: the assistant’s tools still only read, but the token itself can also change things through the API. 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.jsonin your project folder, then runeval "$(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 raneval "$(ronja env)", for example withcursor .. -
Codex — add
bearer_token_env_var = "RONJA_TOKEN"to the[mcp_servers.ronja]section above, then runeval "$(ronja env)" && codex. The Codex app only has your token if it was started from that terminal.
What each tool needs
Section titled “What each tool needs”When it connects, the assistant gets a short description of Ronja’s tools, and each tool’s own description states its limits. Claude and ChatGPT show a tool by the name in Shown as, in their tool lists and when they ask before running one. A token from signing in, or from ronja login, can use every tool your role allows. A token limited to scopes needs:
| Tool | Shown as | What it does | Scopes (Read) |
|---|---|---|---|
getPolicy |
Read organization policy | The policy that applies to you: the organization-wide rules, the policies for your people properties, and your own — your organization’s definitions and reporting conventions, for answers that depend on them | Data, Analytics |
find |
Find in Ronja | Find anything by describing it | Data |
list |
List resources | List resources by kind, feature, name or tag | Data, plus each kind’s own scope |
getTable |
Read table details | Read a table’s columns, with their types and statistics, its description, and its health checks with whether each passes — what the assistant needs to write SQL against it | Data — plus Analytics to also see the organization Knowledge entries attached to the table |
searchSchema |
Search table columns | List every column of a wide table, or the fields inside a nested column | Data |
getNote |
Read notes | Read notes in full | Data, Analytics |
queryRonja |
Query Ronja tables (SQL) | SQL over your Ronja tables — and it can also join a Ronja-managed database live, through a login secret the token’s owner can use | Data — plus Secrets to join a managed database |
queryMetric |
Query a metric | Read a metric at any grain and breakdown | Data |
queryExternal |
Query a connected database (SQL) | 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.
A queryRonja that joins a managed database into the query also needs Secrets: Read.
Limits
Section titled “Limits”- Answers are capped:
queryRonjareturns at most 10,000 rows (and about 32 KB of text),queryMetric50,000, andqueryExternalshows 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
queryRonjaquery stops after 120 seconds, and aqueryRonjaorqueryMetricquery whose tables hold more than 4 GB of data is refused rather than run (Queries). getTableshows at most 50 columns of a table; for a wider one the assistant lists the rest withsearchSchema.- 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
Section titled “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, runronja login --profile <name>(the command the CLI prints when the sign-in expires), theneval "$(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 loginor Account → Access tokens.
Related
Section titled “Related”- 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.