# rivomi API and MCP documentation

> The manual for driving rivomi from an AI agent or a script: connect over MCP or REST, authenticate, choose among the thirty tools, and run complete outreach jobs. Every page is also available as markdown by appending `.md` to its URL, or by requesting it with `Accept: text/markdown`.

rivomi finds people showing buying intent on LinkedIn, scores them against what a workspace sells, and runs outreach from the workspace's own LinkedIn account once a human approves it. The MCP endpoint is https://rivomi.com/api/mcp (OAuth 2.1, or an API key as a bearer token); REST lives at https://rivomi.com/api/v1 with an OpenAPI document at https://rivomi.com/api/v1/openapi.json.

## Start here

- [rivomi API and MCP documentation](https://rivomi.com/docs): Connect an AI agent to rivomi, find people showing buying intent on LinkedIn, and run outreach from your own account over MCP or REST.

## Connect

- [Connect over MCP](https://rivomi.com/docs/connect): Add the rivomi endpoint to an MCP client, authenticate, and confirm the connection with one free call.
- [API keys and OAuth](https://rivomi.com/docs/connect/authentication): The two kinds of credential, the three scopes, and how each is created, bound to a workspace, and revoked.
- [Claude](https://rivomi.com/docs/connect/clients/claude): Add rivomi to claude.ai or Claude Desktop as a custom connector, signed in with OAuth.
- [Claude Code](https://rivomi.com/docs/connect/clients/claude-code): Add rivomi to Claude Code from the terminal, with OAuth or an API key.
- [Cursor](https://rivomi.com/docs/connect/clients/cursor): Add rivomi to Cursor's MCP configuration.
- [ChatGPT](https://rivomi.com/docs/connect/clients/chatgpt): Add rivomi to ChatGPT as a connector, signed in with OAuth.
- [VS Code](https://rivomi.com/docs/connect/clients/vscode): Add rivomi to VS Code's MCP configuration.
- [Codex](https://rivomi.com/docs/connect/clients/codex): Add rivomi to the Codex CLI.
- [Other clients](https://rivomi.com/docs/connect/clients/other): Connect any MCP client, or write your own against the rivomi endpoint.

## Concepts

- [How rivomi works](https://rivomi.com/docs/concepts/model): The nouns an agent works with (workspace, agent, signal, prospect, list, run, sequence, conversation) and how one leads to the next.
- [What agents cannot do](https://rivomi.com/docs/concepts/guardrails): The human gates in front of sending, and the actions no credential can take. Plan around them rather than hitting them.

## Tools

- [Tool reference](https://rivomi.com/docs/tools): All thirty rivomi MCP tools grouped by job, with the scope each needs, whether it spends credits, and its REST twin.
- [REST API](https://rivomi.com/docs/tools/rest): The same actions as the MCP tools over plain HTTP, for scripts, CRMs and scheduled jobs.

## Use cases

- [Launch an outreach agent](https://rivomi.com/docs/use-cases/launch-an-agent): Create an agent from a goal, give it targeting and a sequence, launch it, and confirm its first run found people.
- [Import a post's engagers](https://rivomi.com/docs/use-cases/import-post-engagers): Price a LinkedIn post for free, pull its commenters into a list, then enrich, score and draft them.
- [Review and send](https://rivomi.com/docs/use-cases/review-and-send): Walk an agent's review queue with the user, approve the right people, and confirm their sequences are queued.
- [Work the inbox](https://rivomi.com/docs/use-cases/work-the-inbox): Find every conversation that needs an answer, read each in full, and reply with the user's approval.
- [Tune the scorer](https://rivomi.com/docs/use-cases/tune-the-scorer): Find the borderline people, label them with the user, tighten targeting, and rescore.
- [Weekly report](https://rivomi.com/docs/use-cases/weekly-report): Answer "how is outreach going" in five free reads, covering the funnel, each agent, failures and open replies.

## Reference

- [Credits](https://rivomi.com/docs/reference/credits): What spends credits, what is free, how to price work before paying for it, and how retries are protected.
- [Errors and limits](https://rivomi.com/docs/reference/errors): How errors arrive on MCP and REST, every error code with the fix, and the rate limits.
- [Statuses](https://rivomi.com/docs/reference/statuses): Every state an agent, prospect, run and sequence can be in, and what moves it.

## Optional

- [All pages in one file](https://rivomi.com/docs/llms-full.txt): every page of this manual, concatenated.
- [OpenAPI document](https://rivomi.com/api/v1/openapi.json): the REST surface, machine-readable.