Answered from these docs only, by a model that cannot see your account. Check the pages it cites.

MCP tools

Every tool Roiva's MCP server serves an assistant: what each one answers and the parameters it takes.

View as Markdown View as JSON

Answered from these docs only, by a model that cannot see your account. Check the pages it cites.

Generated from what Roiva ships, on every deploy.

On every plan, the free account included, Roiva serves an MCP endpoint at https://roiva-staging.com/mcp, so Claude, ChatGPT, Microsoft Copilot, Amazon Quick, Gemini Enterprise, Gemini CLI, Cursor or another client can read your account's figures where you are already working, and, where your account allows it, draft a monthly reading, a vendor bill's costs or an initiative's business-case figures for a person to accept.

Connecting a client

Claude (claude.ai, the desktop and mobile apps, and Cowork) needs no token: add the URL above as a custom connector in Claude, then sign in to Roiva and approve access to one account. Roiva's sign-in applies your account's single sign-on and two-factor rules, and by default only Owners and Admins can connect.

ChatGPT connects the same way: add the URL above as a custom MCP server under Plugins, with OAuth, then sign in to Roiva and approve. Its deep research uses search and fetch below.

Microsoft Copilot Studio, Microsoft 365 Copilot, Amazon Quick and Gemini Enterprise sign people in the same way, through a client an Owner or Admin registers first under Organization Settings → API Access (Register a client). Paste its client ID and secret, with the authorization URL, token URL and scopes shown there, into the assistant's OAuth form, and add the assistant's redirect address to the client. For Gemini Enterprise, choose Another assistant, use https://vertexaisearch.cloud.google.com/oauth-redirect as the redirect address, and turn on PKCE in Gemini Enterprise. Each person then signs in to Roiva and approves.

Claude Code can sign in the same way: run claude mcp add --transport http roiva https://roiva-staging.com/mcp, then type /mcp in Claude Code and authenticate, which opens Roiva's sign-in in your browser. It can use a token instead, as below.

For Cursor, Gemini CLI, Google Antigravity and other clients, or Claude Code without a browser, an Owner or Admin issues a token under Organization Settings → API Access, which prints these with the token already in them. They 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:

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

Gemini CLI, in a terminal:

gemini mcp add --scope user --transport http --header "Authorization: Bearer YOUR_TOKEN" roiva https://roiva-staging.com/mcp

Google Antigravity, its editor and its CLI, in mcp_config.json:

{
  "mcpServers": {
    "roiva": {
      "serverUrl": "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, ChatGPT, Cursor and other AI assistants (MCP) covers issuing a token and what one can see.

What a client can do with it

The tools in the first table read. 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 — that list is held to the read-only tools, and a spec runs each one and checks it wrote nothing.

The second table drafts. Where your account's Who Can Let AI Assistants Propose Changes setting allows it (Owners and Admins by default), a client can also draft one month's figure for a metric Roiva asks a person to type in, the figures for every month an initiative has been live that its Past months page still asks for, a new initiative's whole setup from a library template, the charges on a vendor bill Roiva doesn't connect to as an initiative's costs, or an initiative's business-case figures with a basis line for each, all with the source they came from, and withdraw its own draft. A token drafts only if it was also issued with Can draft changes for review. A draft writes nothing else: it waits under Inbox → Proposals until a person accepts or declines it. An accepted reading's value then waits for an approver, past months' and a setup's too; costs a person books count at once, as typed costs do; business-case figures become the plan when a person saves them on Edit Business Case.

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

Every connection

Tool What it answers Parameters
get_roi_summaryGet ROI Summary Get the actual ROI rollup — cash value and freed capacity (approved entries, two figures never added), cost, net cash, cash ROI %, capex/opex split, with the URL of the ROI page that shows them. 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, which opens on the 1st of the first whole month in it.
list_initiativesList 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_initiativeGet 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_roivaSearch 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_integrationsList Integrations List the account's integration connections, with platform, status, last sync time, whether one needs to be reconnected, and its latest error. For why one isn't bringing data in, use get_connection_health. None
get_help_articleGet 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 (the last part of an article's /docs/ URL, or from the help index where you have one) or its ID, as search_roiva and search_help return it. A /docs/reference/ page is generated, not an article, and this can't fetch it. slug — string. optional. The article's slug, e.g. "inviting-your-team".id — integer. optional. The article's ID.
get_platform_setup_guideGet 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".
get_templateGet Initiative Template One initiative template from the library: what it is for, its hypothesis, ratings, the financial defaults it prefills (Roiva's typical figures, not this account's), what it counts as cost, and the value formulas it ships, with the metrics each one reads and why. Use it for "why does this template use X" or "what does it measure". Find the ID with search_roiva (types: templates) or from a template page's URL. id — integer. required. The template's ID, as search_roiva returns it.
get_metricGet Metric One metric's definition: what it counts, its unit, why a formula asks for it where that isn't obvious, what to watch out for and the help article that goes further. Pass its metric key (such as cloud.usage.unit_count) or the ID search_roiva returns. metric_key — string. optional. The metric's key, e.g. "cloud.usage.unit_count".id — integer. optional. The metric's ID.
get_value_breakdownGet Value Breakdown The value entries behind an initiative's value figure, newest first, with the sum computed for you. Each entry gives its period, type (cash or freed capacity), amount, status, whether it counts, what it rests on, the formula and every input it was calculated from, notes about those inputs, readings that changed since, and who approved it. An entry not counted yet says who can approve it now ("you" is the user), or what has to happen before anyone can; repeat that rather than guessing at the approval rules. Totals are counted as the ROI page counts them, for that month or all periods (not a reporting period), plus what is not counted yet. Use it for "how does this figure tie", "why is this month lower" and "what is in this number". Pass month (YYYY-MM) for one month; omit it for all periods. initiative_id — integer. required. The initiative's ID.month — string. optional. One month as YYYY-MM. Omit for all periods.limit — integer. optional. Most entries to list (default 40, max 100). Totals always cover all of them.
get_formulaGet Formula The value formulas live on an initiative: each one's expression, the type of value it books, and every input with what it reads today (the latest reading, the baseline with its method and when it was set, or the assumption and who set it) and the figure it last used. Use it for "how is this calculated", "what baseline is it using" and "how do I change the baseline". For a template's formulas before an initiative uses them, use get_template. initiative_id — integer. required. The initiative's ID.
get_cost_breakdownGet Cost Breakdown The cost entries behind an initiative's total cost, newest first, with the sum computed for you: each entry's period, type, capex or opex, amount in dollars, vendor, source and notes; totals by type and category; and anything counted at a provisional rate or left out for want of one. Pass month (YYYY-MM) for one month. initiative_id — integer. required. The initiative's ID.month — string. optional. One month as YYYY-MM. Omit for all periods.limit — integer. optional. Most entries to list (default 40, max 100). Totals always cover all of them.
get_entry_historyGet Entry History What happened to one value entry, cost entry or reading: who recorded, edited and approved it, who can approve a value entry not counted yet ("you" is the user) or what has to happen first, the approval decisions and reasons, inputs that changed since it was calculated, and, for an Admin or Owner on a plan with the audit log, its audit log rows. Pass the entry's ID from get_value_breakdown or get_cost_breakdown. kind — string. required. one of value_entry, cost_entry, reading. Which kind of record the ID is.id — integer. required. The record's ID.
get_connection_healthGet Connection Health One integration connection's health: whether it needs to be reconnected, its latest error, and what its last few syncs did (records brought in, skipped and failed, and why). Use it for "why isn't my data coming in" and "did the sync work". Get the ID from list_integrations. connection_id — integer. required. The connection's ID, from list_integrations.
get_assumptionsGet Assumptions The account's assumptions: the figures its formulas price with, such as a loaded hourly labor rate, a cost per deflected ticket or a contribution margin, as the Assumptions page lists them. Each gives the figure in force today with its unit (money is US dollars, unless an account typed a unit naming another currency, which nothing converts), whether it is the account's own or Roiva's unconfirmed default, who set it and when, whether it stands in for a figure nobody has measured, and how many formulas and initiatives read it. Pass input_key for one assumption in full: what it measures, its basis or source, every dated figure by period with who set each and why, and each formula reading it. Use these figures, not rates of your own, when estimating with this account's numbers. A share of an outcome's change credited to one initiative is that initiative's own: get_formula shows it. input_key — string. optional. One assumption's key, e.g. "labor_rate_cents_per_hour", as a list from this tool returns it.query — string. optional. Words from its name, key or description, e.g. "hourly rate". Omit to list all.status — string. optional. one of missing, default, set, unused. missing (something reads it and nothing sets it), default (Roiva's, not confirmed by the account), set (the account's own) or unused (nothing reads it).limit — integer. optional. Most to list (default 20, max 50).before — string. optional. With input_key: list the dated figures that start before this day (YYYY-MM-DD), for history older than the 12 shown. The answer names the date to pass next.
get_plan_vs_actualGet Plan vs Actual How the business cases of initiatives that went live (including any since paused, completed or dismissed) compare with what they delivered: for each, its planned figures (CapEx, OpEx and value per period, freed capacity), the plan to date beside approved actuals to date for cash value, freed capacity and cost, cash ROI actual and planned to date, how long it has been live, time to first value against its target, what its value rests on, and what was left out for want of an exchange rate. Cash value against plan is judged as ROI › Initiatives judges it (behind, on plan, ahead, or why not yet). Cash and freed capacity are separate figures, never added. Use it for "how far off were our earlier business cases" before estimating a new one. Filter by category or template_id (from search_roiva, types: templates). category — string. optional. one of sales, operations, finance, customer_success, hr, marketing, product, engineering, supply_chain, legal_compliance, other. Only initiatives in this category. Say a category by its label, never its key: sales is Sales, operations is Operations, finance is Finance, customer_success is Customer Support, hr is HR, marketing is Marketing, product is Product, engineering is Engineering & IT, supply_chain is Supply Chain, legal_compliance is Legal & Compliance, other is Other.template_id — integer. optional. Only initiatives started from this template.limit — integer. optional. Most initiatives to detail, earliest go-live first (default 10, max 25). The vs-plan counts cover all of them.
searchSearch Roiva Documents Search the user's Roiva account for documents to read in full with fetch: initiatives, metric definitions, integration connections, initiative templates and help articles. Returns each one's ID for fetch, title and URL to cite. For the app's pages, people, vendors and assessments, use search_roiva. query — string. required. Search text (min 2 chars).
fetchFetch Roiva Document Read in full one document search returned, by its ID (such as initiative:42 or help:7): an initiative's figures, a metric's definition, a connection's health, a template or a help article. id — string. required. The document's ID, as search returns it.

Drafts a person accepts

Served only to a connection your account lets draft: Owners and Admins by default. Nothing changes in Roiva until a person accepts a draft there.

Tool What it answers Parameters
list_requested_readingsList Requested Readings The monthly figures Roiva is asking a person to type in, because no connected system reports them: for each, the initiative, the metric key and its name, the month it is asked for (YYYY-MM; a month's total is asked once the month has ended), its unit, where to find it, and any proposal already waiting. Use it before propose_reading. For an initiative recorded as live from an earlier date, it also lists the months since then that still take a figure (the initiative's Past months page in Roiva); draft those with propose_past_readings. initiative_id — integer. optional. Only this initiative's. Omit for the whole account.
propose_readingPropose Reading Draft one month's figure for a metric Roiva asks for (list_requested_readings), for a person to review and accept in Roiva. Nothing in Roiva changes until they accept it there, and what it calculates then waits for an approver; say so plainly to the user. Give the source the figure came from. Roiva checks it as the form would and says what to fix. A second call for the same initiative, metric and month replaces your earlier proposal. It takes only the month list_requested_readings asks for; earlier months since the initiative went live, the ones on its Past months page, go in one propose_past_readings call. initiative_id — integer. required. The initiative's ID.metric_key — string. required. The metric key list_requested_readings gives.month — string. required. The month the figure is for, YYYY-MM: the one list_requested_readings asks for.value — number. required. The figure for that month, in the metric's unit.unit — string. optional. What the figure counts, for a metric whose unit the account chooses (list_requested_readings says).source — object. required. Where the figure or bill came from, shown to the person who accepts it: kind is document, link, system or quote; label names it ("Zendesk Explore export, Sept 2026", "Email from finance, Oct 3"), at most 200 characters; url is an https link to it, optional; quote is the line the figure is in, optional, at most 300 characters.rationale — string. optional. One short paragraph on how you arrived at the figure, at most 1,000 characters.idempotency_key — string. optional. Any string unique to this proposal; a retried call with the same key returns the same proposal.
propose_past_readingsPropose Past Months Draft the figures for the months an initiative has already been live, for a person to review and accept in Roiva: the months list_requested_readings lists as past months (the initiative's Past months page), for an initiative recorded as live from an earlier date. One call takes every figure and month for the initiative; the month Missing Inputs asks for (the last ended one) goes through propose_reading instead. Nothing in Roiva changes until a person accepts it there; each month whose figures are all in is then calculated (once the figures every month reads are set, which Roiva's reply names when they aren't), and what it calculates waits for an approver, so say plainly that it is only a draft. Give the source each figure came from. Roiva checks each month as the page would (it still takes a figure, isn't locked, the figure is in range) and says what to fix. A second call for the same initiative replaces your earlier proposal. initiative_id — integer. required. The initiative's ID.readings — array. required. One item per figure (metric key), at most 10.rationale — string. optional. One short paragraph on how you arrived at the figures, at most 1,000 characters.idempotency_key — string. optional. Any string unique to this proposal; a retried call with the same key returns the same proposal.
propose_costsPropose Costs Draft the charges on one vendor bill Roiva doesn't connect to (an invoice, receipt or usage export you can see) as costs on an initiative, for a person to review and book in Roiva. Nothing in Roiva changes until they book it there; the costs they book then count toward ROI at once, so say plainly that it is only a draft. Roiva checks each line against what the initiative already books (its cost connections, vendor mappings, entries and locked months) and says which may count twice or can't be booked. Amounts are in the bill's currency; Roiva books US dollars only. At most 50 lines, and the call must stay under 16 KB, so keep descriptions and quotes short and propose a longer bill in parts (a month at a time), giving each part its own bill_reference ("INV-0042 part 2"): parts with the same one replace each other. Give the source the bill came from. A second call with the same vendor and bill_reference (or, with no bill_reference, the same vendor and lines) replaces your earlier proposal; give the bill_reference every time if the bill has one. initiative_id — integer. required. The initiative the costs are for.vendor — string. required. Who sent the bill, e.g. "Anthropic", at most 100 characters.product — string. optional. What the bill is for, where the whole bill is one product ("Claude Team"). Optional.document_type — string. optional. one of usage_export, invoice, receipt, payment_history, other. What the bill is. Default invoice.bill_reference — string. optional. The bill's own number or ID (an invoice number), if it has one.lines — array. required. The bill's charges, one per line as the bill lists them.source — object. required. Where the figure or bill came from, shown to the person who accepts it: kind is document, link, system or quote; label names it ("Zendesk Explore export, Sept 2026", "Email from finance, Oct 3"), at most 200 characters; url is an https link to it, optional; quote is the line the figure is in, optional, at most 300 characters.rationale — string. optional. One short paragraph on why these are this initiative's costs, at most 1,000 characters.idempotency_key — string. optional. Any string unique to this proposal; a retried call with the same key returns the same proposal.
propose_plan_figuresPropose Business Case Figures Draft an initiative's business case: its planned figures, each with a basis line and the source it came from, for a person to review and save on Edit Business Case in Roiva. Nothing in Roiva changes until they save it there, so say plainly that it is only a draft. Open the help article writing-an-initiatives-business-case first. Write each basis line with the count, the rate, the document or system it came from, and who supplied it. Price hours at the loaded hourly rate the initiative's own formulas read (get_formula, get_assumptions), so the plan and the measured value are priced alike. Not while the initiative is in review (its CapEx and OpEx decide who approves it), nor once it was rejected or dismissed. After approval its budget doesn't move. Roiva says how each figure compares with the one there now. A second call for the same initiative replaces your earlier proposal, so give every figure you mean each time. initiative_id — integer. required. The initiative whose business case this is.figures — array. required. Each planned figure once. Money is US dollars.rationale — string. optional. One short paragraph on how the case was put together, at most 1,000 characters.idempotency_key — string. optional. Any string unique to this proposal; a retried call with the same key returns the same proposal.
propose_initiative_setupPropose Initiative Setup Draft a new initiative's whole setup for a person to review and accept once in Roiva: the initiative from a library template (get_template shows what its formulas read), the date it went live where it was already running, its own assumption figures and baselines (each with a basis line naming the count, the rate, the document or system and who supplied it), the figures for each complete month since it went live, and a vendor bill's charges. Nothing in Roiva changes until a person accepts it there: they choose what to keep, recording the go-live approves the initiative and takes one of the plan's measured places, what the figures calculate waits for an approver, and the bill's lines wait to be booked. Say plainly that it is only a draft. Only figures the template's formulas read, and only ones an initiative can hold for itself; an account-wide figure is refused. For an initiative that already exists, use propose_past_readings, propose_plan_figures and propose_costs instead. title — string. required. The initiative's title, at most 80 characters.template_id — integer. required. The library template it is set up from.owner_name — string. optional. Who should own it, as a suggestion the person accepting sees; they choose the owner.live_since — string. optional. The date it went into use, YYYY-MM-DD, where it is already running. Omit for one not live yet.figures — array. optional. The initiative's own assumption figures, at most 10.baselines — array. optional. Baselines, at most 10: method history (the months before it went live) or estimate.readings — array. optional. Figures for each complete month since live_since, one item per metric key, at most 10.bill — object. optional. One vendor bill's charges as its costs, as propose_costs takes them, at most 20 lines.rationale — string. optional. One short paragraph on how you arrived at the setup, at most 1,000 characters.idempotency_key — string. optional. Any string unique to this proposal; a retried call with the same key returns the same proposal.
list_my_proposalsList My Proposals The changes you have drafted for a person to accept in Roiva, newest first: each one's status (waiting, accepted, declined with the reason given, withdrawn, expired or superseded), who decided it, and its page in Roiva. status — string. optional. one of pending, accepted, declined, withdrawn, expired, superseded. Only this status.limit — integer. optional. Most to list (default 20, max 50).
withdraw_proposalWithdraw Proposal Withdraw one of your own proposals that is still waiting for a person. It changes nothing else. proposal_id — integer. required. The proposal's ID, from list_my_proposals or propose_reading.