# Connect your AI assistant to the docs (MCP)

> An MCP server on the portal lets Claude, Cursor and other AI assistants search the guides, read the reference and the error codes and follow the changelog while they write your code. A skill for Claude Code also gives them the rules and the way in.

You let an AI assistant write or review the integration with Rivr. It does better when it reads the docs than when it remembers: with the portal's MCP server it reads the same guides, the same reference and the same error codes you see here, in the version that is deployed. The documentation is public, so it needs no key and no account.

- Market: Sweden (`se`). Norway differs in currency, payment methods and what happens when nobody pays: https://developers.rivr.io/guides/mcp.md?market=no
- Language: English (`en`). Svenska: https://developers.rivr.io/guides/mcp.md?lang=sv
- 6 min read · 8 steps
- Page in the portal: https://developers.rivr.io/guides/mcp

Every example targets the sandbox (`https://api.test.rivr.io`) and needs test credentials. A platform client's tokens come from `https://auth.test.rivr.io`, an organisation key's from `https://auth.test.rivr.tech`.

## 1. The server and what it does

*Rivr → Journal system*

The portal has an MCP server at `https://developers.rivr.io/mcp`. It speaks MCP over Streamable HTTP and has five tools for the documentation: search the docs, read a page as Markdown, look up an error code, get the OpenAPI spec of a surface (the whole surface or a single operation) and read the changelog.

The answers are the same text as the pages here and as the `.md` addresses in `/llms.txt`, built from the same source. So there is no copy that can fall behind.

**Why:** An agent that looks the call up while it writes the code calls the API the way the docs say, not the way it remembers some other API. It also keeps up when the docs change, without anyone pasting anything.

> **Note.** The documentation needs no sign-in and no API key. The server never reads your organisation's data and never calls Rivr's API. The examples it shows target the sandbox.

## 2. Claude Code

*Journal system → Rivr*

Run `claude mcp add --transport http rivr-docs https://developers.rivr.io/mcp` in your project. Add `--scope user` to have the server in every project.

In Claude Code, `/mcp` shows that the server is connected and which tools it has.

## 3. Claude on the web and in the desktop app

*Journal system → Rivr*

Go to Settings → Connectors → Add custom connector. Name: `Rivr docs`. URL: `https://developers.rivr.io/mcp`. Leave the authentication empty.

On a Team or Enterprise plan, an owner adds the connector for the organisation first.

## 4. Cursor

*Journal system → Rivr*

Put the server in `.cursor/mcp.json` in the repository, or in `~/.cursor/mcp.json` for every project: `{ "mcpServers": { "rivr-docs": { "url": "https://developers.rivr.io/mcp" } } }`.

Cursor lists it with its tools among its MCP servers in the settings.

## 5. VS Code

*Journal system → Rivr*

Put the server in `.vscode/mcp.json` in the repository: `{ "servers": { "rivr-docs": { "type": "http", "url": "https://developers.rivr.io/mcp" } } }`.

The tools are then in Copilot Chat in agent mode.

## 6. Other clients

*Journal system → Rivr*

A client that supports MCP over Streamable HTTP needs only the address `https://developers.rivr.io/mcp`, with no authentication. The server keeps no sessions, so every call stands on its own.

A client that can only start local servers (stdio) reaches it through a bridge, for example `npx mcp-remote https://developers.rivr.io/mcp`.

## 7. The tools

*Journal system → Rivr*

`search_docs` searches with the portal's own search, the one behind its command palette: every step of the guides, every operation in the reference, every error code, event, limit and agent rule, the promise on versioning and the test data the sandbox accepts. It finds a word in its other forms ("refund" finds "refunded"), a half-written word and a word without its diacritics, and an identifier whole or by its parts (`Idempotency-Key`, `order_paid`). The answer has at most two matches from one page, and each match has its kind (`kind`: `guide`, `reference`, `error`, `event`, `limit`, `rule`, `policy` or `testdata`), a snippet and a path that ends in the anchor of the place on the page, for example `/guides/connect#step-merchant-token`. With `kind` you get only one kind of match, and then one page can give as many matches as you ask for with `limit`.

`get_page` reads a page as Markdown by its path, for example `/guides/connect`, `/reference/api-public/createOrder`, `/errors/order_paid`, `/llms.txt` or `/llms-full.txt` (the whole documentation as one text, cut at the limit of a tool answer), in English or Swedish and with the code languages you choose.

`lookup_error` looks a `code`, a `type` address or an HTTP status up in the error catalog: whether the same call can be retried, and what your system should do.

`get_openapi` gives an outline of a surface, for example `/api/public`, with every operation, or a single operation as an OpenAPI document of its own with the schemas it uses. Download a surface's whole spec from `/openapi/<surface>.json`, for example `/openapi/api-public.json`; `/reference.md` lists every spec.

`get_changelog` reads the changelog, newest first, and can show only what asks something of you.

**What your system does:** Ask the assistant to look up what it is about to do, for example: "How do I refund an order in Rivr, and what do I do when the answer is idempotency_in_progress?"

## 8. A skill for Claude Code: the rules and the way in

*Rivr → Journal system*

The MCP server gives the assistant the documentation. A skill gives it the way of working: when a task is about Rivr, Claude Code reads `SKILL.md`. It holds the binding rules for AI agents (the same as on the page Rules for AI agents), the shortest way from a token to a verified webhook in the sandbox, how the agent uses the MCP server, `/llms-full.txt`, the `rivr` CLI and the error catalog with `retryWhen`, and what it must never do. The portal serves it at `https://developers.rivr.io/skills/rivr/SKILL.md` and generates it from the same sources as the pages here, so it says what they say.

Download it to `~/.claude/skills/rivr/` with the command for your system. Both fetch the same files: `SKILL.md` and the reference files it links to. Add `?lang=sv` after each file name for the Swedish text, and run the command again to update. Claude Code also reads a skill in `.claude/skills/rivr/` in a repository, and then the whole team shares it.

**Why:** The rules and the way come with every task instead of someone pasting them in. The skill is a copy, not a link: the portal wins where they differ, and the skill says so.

**What your system does:** Put the sandbox credentials in the environment for the agent (`RIVR_CLIENT_ID` and `RIVR_CLIENT_SECRET`), never in a chat or a file. Then ask Claude Code to integrate with Rivr: the skill is loaded when the task fits its description.

> **Warning.** A skill is instructions your agent follows, so read it before you install it. It is plain Markdown, and the files are listed in the command.

**macOS and Linux**

```bash
curl -fsSL --create-dirs \
  -o ~/.claude/skills/rivr/SKILL.md https://developers.rivr.io/skills/rivr/SKILL.md \
  -o ~/.claude/skills/rivr/references/sandbox-flow.md https://developers.rivr.io/skills/rivr/references/sandbox-flow.md \
  -o ~/.claude/skills/rivr/references/cli.md https://developers.rivr.io/skills/rivr/references/cli.md \
  -o ~/.claude/skills/rivr/references/errors.md https://developers.rivr.io/skills/rivr/references/errors.md
```

**Windows (PowerShell)**

```powershell
$dir = Join-Path $HOME ".claude/skills/rivr"
foreach ($file in "SKILL.md", "references/sandbox-flow.md", "references/cli.md", "references/errors.md") {
  $target = Join-Path $dir $file
  New-Item -ItemType Directory -Force -Path (Split-Path $target) | Out-Null
  Invoke-WebRequest -UseBasicParsing -Uri "https://developers.rivr.io/skills/rivr/$file" -OutFile $target
}
```

## Common pitfalls

- Opening `https://developers.rivr.io/mcp` in the browser gives `405`. The server answers `POST` with JSON-RPC, which is what the clients send.
- The limit is 300 requests a minute per client address, and above it the answer is `429` with `Retry-After`. A tool call is one request, and a client makes a few more when it connects. If you connect through Claude on the web, you share an address with other users of that service. A request with several messages (a JSON-RPC batch) is refused with `400`: send one message per request.
- The server only reads the docs. It never reads your organisation's data, can never create, change or refund an order and never calls Rivr's API. You do that in the portal and against the sandbox's API.

## Next guide

- [Connect as a platform](https://developers.rivr.io/guides/connect.md): One set of credentials for the whole journal system, one token per clinic.