# rivomi API and MCP documentation

> Connect an AI agent to rivomi, find people showing buying intent on LinkedIn, and run outreach from your own account over MCP or REST.

Source: https://rivomi.com/docs



rivomi finds people who are showing buying intent on LinkedIn, scores each one against what your
workspace sells, drafts a message that cites what they said, and sends it from your own LinkedIn
account once a human approves. Every action in the app is available to an AI agent over MCP and to
scripts over REST.

```
https://rivomi.com/api/mcp
```

The MCP server uses **Streamable HTTP**. Hosted connectors sign in with **OAuth 2.1**. Anything you
configure yourself can send an **API key** as a bearer token instead.

## Choose the shortest path [#choose-the-shortest-path]

| Goal                                        | Start here                                                                                                                                                                                                                                                               |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Connect an agent for the first time         | [Connect over MCP](/connect)                                                                                                                                                                                                                                             |
| Configure a specific client                 | [Claude](/connect/clients/claude), [Claude Code](/connect/clients/claude-code), [Cursor](/connect/clients/cursor), [ChatGPT](/connect/clients/chatgpt), [VS Code](/connect/clients/vscode), [Codex](/connect/clients/codex), or [another client](/connect/clients/other) |
| Create a key or understand scopes           | [API keys and OAuth](/connect/authentication)                                                                                                                                                                                                                            |
| Learn the nouns: agent, list, run, sequence | [How rivomi works](/concepts/model)                                                                                                                                                                                                                                      |
| Choose or inspect a tool                    | [Tool reference](/tools), then the live `tools/list` schema                                                                                                                                                                                                              |
| Call rivomi from a script                   | [REST API](/tools/rest)                                                                                                                                                                                                                                                  |
| Complete a job end to end                   | [Use cases](/use-cases/launch-an-agent)                                                                                                                                                                                                                                  |
| Handle an error or a cost question          | [Errors and limits](/reference/errors), [Credits](/reference/credits)                                                                                                                                                                                                    |

## The agent workflow [#the-agent-workflow]

<Steps>
  <Step>
    ### Connect and authorise [#connect-and-authorise]

    Point a Streamable HTTP client at `/api/mcp`, then sign in through OAuth or send
    `Authorization: Bearer <key>`. A credential belongs to exactly one workspace.
  </Step>

  <Step>
    ### Read the workspace [#read-the-workspace]

    Call `rivomi_get_workspace` first. It returns the three facts every later decision depends on: the
    **credit balance** (and whether spending is blocked), the **LinkedIn senders** and their headroom
    today, and whether a human has accepted the **sending terms**.
  </Step>

  <Step>
    ### Discover the live tools [#discover-the-live-tools]

    Use MCP `tools/list`. Tool schemas are the source of truth for arguments, defaults, and limits.
    A description that starts with `$` spends credits.
  </Step>

  <Step>
    ### Act, then poll [#act-then-poll]

    Reads return at once. Anything long (a search, an import, a scoring pass) returns a `run_id`; poll
    `rivomi_get_run` until `finished` is true. Sending always returns "queued": a sender paces the
    work inside its working hours.
  </Step>
</Steps>

The connection is ready when `rivomi_get_workspace` returns your workspace's real name and plan.
A job is complete when every run it started reports `finished: true`, and the result
(people found, drafts approved, replies sent) is confirmed by a read tool rather than assumed from a
write's response.

## What the server exposes [#what-the-server-exposes]

| Capability        | Tools cover                                                                  |
| ----------------- | ---------------------------------------------------------------------------- |
| Workspace         | Plan, credits, senders, sending consent, the funnel dashboard                |
| Agents            | Create, target, write the sequence, launch, pause, run now, review the queue |
| Prospects         | Search, read in full, label fit, write a research brief                      |
| Lists and imports | Make lists, move people, import a post's engagers, enrich, score and draft   |
| Runs              | List, poll, abort long jobs                                                  |
| Outreach          | Queue people into sequences, pause or stop one                               |
| Inbox             | Find threads that need a reply, read them, reply                             |

## Machine-readable documentation [#machine-readable-documentation]

Every page has a markdown twin. Append `.md` to a docs URL, or request it with
`Accept: text/markdown`.

* [`/docs/llms.txt`](/llms.txt) indexes every page.
* [`/docs/llms-full.txt`](/llms-full.txt) contains the whole manual in one file.
* [`/api/v1/openapi.json`](https://rivomi.com/api/v1/openapi.json) is the REST surface as OpenAPI 3.1.