# MCP

Connect an AI agent to Rivier over the Model Context Protocol with one address and a key.

## Connect

The server is at `https://api.rivier.ai/mcp`. It speaks Streamable HTTP and keeps no session, so one address and one key are all an agent needs. Send the key as a bearer credential, the same as REST. An agent that signs in with OAuth finds the issuer at `/.well-known/oauth-protected-resource/mcp`.

Configuration:

```
{
  "mcpServers": {
    "rivier": {
      "type": "http",
      "url": "https://api.rivier.ai/mcp",
      "headers": { "Authorization": "Bearer ${RIVIER_API_KEY}" }
    }
  }
}
```

## Tools

The tool list follows the scopes of the key: a read key sees read tools, a write key also sees the writes its scopes allow. Three tools reach every operation in the API reference, so nothing in the app is missing for an agent.

- `rivier_api_operations`: Find an operation by words, area or level. Answers the id, the route, the level and a summary.
- `rivier_api_read`: Run a read operation with its parameters and query.
- `rivier_api_act`: Run a write operation with its parameters, query and body. Takes idempotencyKey so a retried write is not repeated.
- `rivier_key_scopes`: What the calling key holds: project, scopes and how many operations of each level it can run.
- `rivier_overview`: Contacts, campaigns and flows in one call.
- `rivier_contact_brief`: One person: the record, recent events and consent history in one call.

## Resources and prompts

Resources: `rivier://guide`, `rivier://scopes` and `rivier://operations`. Prompts: `weekly_digest`, `contact_follow_up` and `draft_campaign_brief`. None of the prompts sends or approves anything.

## What an agent cannot do

A call goes through the same route as REST with the same key, so scopes, project and rate limits are unchanged. Actions kept for a person, such as approvals, sends and removals at the admin level, are refused with the reason, and the agent can leave them for a person to approve in the app.

## When a call fails

A failed call answers a fixed shape. Branch on `code`, not on the wording. `hint` names the next step, `param` the fields at fault, and `next` the tool and arguments to call instead where there is one. Long answers are cut at a record boundary with a note to narrow the query; nothing is cut without saying so.

Response:

```
{
  "ok": false,
  "code": "insufficient_scope",
  "retryable": false,
  "error": "…",
  "hint": "…"
}
```

Codes: `invalid_input`, `insufficient_scope`, `not_found`, `conflict`, `rate_limited`, `missing_params`, `unknown_operation`, `wrong_mode`, `reserved_for_person` and `server_error`.