# MCP tools

> Every tool Roiva's MCP server serves an assistant: what each one answers and the parameters it takes.
>
> Source: https://roiva-staging.com/docs/reference/mcp-tools
> Generated from what Roiva ships, on every deploy.

Roiva serves an MCP endpoint at `https://roiva-staging.com/mcp`, so Claude, Cursor or another client can read your account's figures where you are already working.

#### Connecting a client

An Owner or Admin issues a token under **Organization Settings → MCP Access**, which prints these with the token already in them. Both are shown here so you can see what connecting involves before you have one.

Claude Code, in a terminal:

```
claude mcp add --transport http roiva https://roiva-staging.com/mcp --header "Authorization: Bearer YOUR_TOKEN"
```

Cursor, or any client that takes an `mcp.json`:

```json
{
  "mcpServers": {
    "roiva": {
      "url": "https://roiva-staging.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

Anything else: point it at the URL above and send the token as an `Authorization: Bearer` header. [Connecting Claude, Cursor and other AI assistants (MCP)](https://roiva-staging.com/docs/connecting-ai-assistants-mcp) covers issuing a token and what one can see.

#### What a client can do with it

**Every tool reads.** None of them can record a cost, approve value or move an initiative: a client can quote Roiva's numbers, not change them. That is enforced rather than promised — the served list is held to the read-only tools, and a spec runs each one and checks it wrote nothing.

The table is the server's own schemas, so it cannot name a tool the server does not serve or miss a parameter it takes.

| Tool | What it answers | Parameters |
| --- | --- | --- |
| get_roi_summary; Get ROI Summary | Get the actual ROI rollup — value (approved entries), cost, net, ROI %, capex/opex split. Pass initiative_id for a single initiative; omit for the whole portfolio. | initiative_id — integer. optional. Optional — single initiative scope.; window — string. optional. one of 1yr, 3yr, 5yr, all. Reporting period (default 'all', the same as the ROI dashboard). 'all' includes everything; '1yr', '3yr' and '5yr' count only entries in that trailing span. |
| list_initiatives; List Initiatives | List AI initiatives for the current account. Returns id, title, stage, and status. Optionally filter by status. | status — string. optional. one of not_started, active, completed, inactive. Filter to one rolled-up status. Omit to list all.; limit — integer. optional. Max rows to return (default 20, max 50). |
| get_initiative; Get Initiative | Get detailed information about a single initiative: stage, category, owner, expected financials (its business case), its approved budget against spend to date, and recent costs/value entries/notes. | initiative_id — integer. required. The ID of the initiative to retrieve. |
| search; Search Roiva | Search the user's Roiva account: initiatives, the app's pages, metric definitions (Roiva's library and the account's own), connections and the platforms not yet connected, vendors on cost entries, people, initiative templates, help articles, and active assessments. Use this to find IDs before calling other tools, or a page URL to send the user to. | query — string. required. Search text (min 2 chars).; types — array. optional. Optional — restrict to certain result types. |
| list_integrations; List Integrations | List the account's integration connections, with platform, status, and last sync time. | None |
| get_help_article; Get Help Article | Fetch the full text of a published Roiva help article: how the product works, where things are and who can do them. Pass its slug (from the help index, where you have one) or its ID (the number at the end of a help article's URL, as search and search_help return it). | slug — string. optional. The article's slug, e.g. "inviting-your-team".; id — integer. optional. The article's ID. |
| get_platform_setup_guide; Get Platform Setup Guide | The guide for connecting one platform to Roiva (Zendesk, HubSpot, AWS, GitHub, QuickBooks…), as the connect form shows it: how it connects, the steps, where to find the credential, any setup script, tips, whether this account has connected it, and the page to connect it from. Use it for any "how do I connect X" question. | platform — string. required. The platform's name or key, e.g. "Zendesk", "Google Cloud" or "google_workspace". |