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

Connecting Claude, ChatGPT, Cursor and other AI assistants (MCP)

Let Claude, ChatGPT, Copilot, Amazon Quick, Gemini Enterprise, Cursor or another MCP client read your Roiva figures and draft changes you accept.

View as Markdown

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

Checked against the product on November 9, 2026

Roiva can answer questions inside the AI assistant your team already uses. Connect Claude, ChatGPT, Microsoft Copilot Studio or Microsoft 365 Copilot, Amazon Quick, Gemini Enterprise, Claude Code, Cursor, Gemini CLI, Google Antigravity, or another client that speaks the Model Context Protocol (MCP), and it can look up your initiatives, costs, cash value, freed capacity and cash ROI while you work ("Which of our initiatives are live, and what's the ROI on each?"), with a link to the initiative or page in Roiva where it found one.

What it can and can't do

  • It reads initiatives, costs, cash value, freed capacity, cash ROI, and the status of your integrations. Each tool returns cash and freed capacity as separate figures and tells the client not to add them. Totals are in US dollars, and each says what it left out for want of an exchange rate.
  • It reads your account's assumptions, such as your loaded hourly rate: each figure with its unit, who set it and when, and which initiatives read it. It also reads how the business cases of initiatives that went live compare with what they've delivered so far. So when you ask it to estimate something new, such as a draft business case, it can start from your own figures instead of rates it makes up.
  • It can also read Roiva's help articles and each platform's How to Connect steps, so it can answer how Roiva works or how to connect a platform from Roiva's own instructions. It can also search your account the way the search at the top of the page does: initiatives, pages, metrics, connections, vendors, people, templates and help articles.
  • It can't change anything in Roiva by itself. Recording costs, approving value, and moving initiatives through their stages stay with a person in Roiva; an assistant can draft a new initiative's go-live date, for someone who may approve the initiative to accept.
  • It can draft a monthly figure for a person to accept, if your account lets it (below). Roiva asks a person to type in each month's figure that no connected system reports, such as tickets resolved or hours a task took. The assistant can list those requests, find a figure in something you share with it or in another tool it's connected to, and draft it with the source it came from. For an initiative recorded as live from an earlier date, it can draft, in one draft, every month since then that the initiative's Past months still asks for, except last month, which it drafts on its own as above. Nothing changes in Roiva until a person accepts the draft there, and the value it calculates then waits for an approver like any other entry.
  • It can also draft a vendor bill's charges as an initiative's costs, if your account lets it: a bill from a vendor Roiva doesn't connect to, such as an invoice, a receipt or a usage export you share with it. Roiva checks each line as it would a bill you upload, and says which may already be counted or fall in a locked month. Nothing is booked until a person reviews the lines and books them in Roiva, and booked costs count toward ROI at once, as costs you type do.
  • It can also draft a new initiative's whole setup, if your account lets it: the initiative from a library template, the date it went live if it was already running, its own assumption figures and baselines with a basis line for each, the figures for each month since, and a vendor bill's charges, from systems it can read such as your finance or billing system. Nothing is created until a person accepts it in Roiva.
  • It can also draft an initiative's business case, if your account lets it: its planned figures, each with a basis line naming the count, the rate, the document or system it came from and who supplied it, and the source it cites. Nothing changes until a person uses the figures they want on Edit Business Case and saves. It can't draft one for an initiative that is in review, rejected or dismissed. See Writing an initiative's business case.
  • Value counts only approved entries, the same as on the ROI dashboard. ROI covers all time unless you name a period ("ROI over the last year"), also as the dashboard does.
  • Every lookup it makes is recorded in your audit log.

Organization Settings → API Access lists exactly what a connected assistant can read.

Things to ask

  • "Which of our AI initiatives are live, and what's the cash ROI on each over the last year?"
  • "How did the business cases of our live initiatives compare with what they've delivered so far?"
  • "Why is the value on our support triage initiative lower this month? Show me the entries and the formula behind it."
  • "Help me draft a business case for an AI invoice-matching initiative, starting from our own hourly rate and how our earlier initiatives did against plan."
  • "Why isn't our Zendesk data coming in?"
  • "Which monthly figures is Roiva waiting for? Draft last month's ticket count from this export, and tell me where to accept it."
  • "Our invoice processing went live in July. Draft July to October's bill counts from these Sage Intacct exports."
  • "Draft this Anthropic invoice as costs on our support triage initiative, and tell me if any line may already be counted."
  • "Draft the business case for our contract review initiative from this vendor quote and last quarter's ticket export, with a basis line for each figure."

Drafts a person accepts

Who may let their assistant draft readings, costs, business-case figures and setups is an account setting, Who can let assistants propose changes, under AI Assistant Policy on Organization Settings → API Access: Owners and Admins unless an Owner or Admin changes it to everyone who can connect AI assistants (Who can connect, below), or to nobody. An access token drafts only if it was issued with Can draft changes for review. Don't put such a token in a header other people's assistants share: they would all draft as you.

A draft waits under Inbox → Proposals, with what it would change, the source the assistant gave and the assistant that drafted it. Only the person whose assistant drafted it and the account's Owners and Admins see it there, and either of them accepts or declines it. If an Owner turns on A second person accepts assistant proposals (Organization Settings → Approvals), another Owner or Admin accepts or declines it, unless nobody else could; the assistant can still withdraw its own. Whatever is accepted is recorded in the name of whoever accepts it, and Roiva records that an AI assistant drafted it. An assistant can't draft anything for a sample initiative.

  • A monthly reading is accepted on the proposal's page. Past months drafted together are accepted there too, one tick per month: each figure starts ticked unless it is flagged as far from the month before, and only the ticked figures are recorded. The value it calculates then waits for an approver, even where Auto-approve formula-derived value entries is on. The person whose assistant drafted the reading and the person who accepted it both count as having prepared that value, as if either had typed the figure, so neither approves it unless nobody else could or the account allows people to approve entries they recorded.
  • A vendor bill's costs are booked on the proposal's page, which checks the lines as a bill you upload is checked. The lines Roiva can book start ticked. A line that may already be counted starts unticked, and booking it takes Book anyway: it doesn't count twice and a reason, which is kept on the cost entry. A run of subscription charges that would become a recurring cost, and a line spread over several months, also start unticked, so tick them only if the bill says so. Booking records the ticked lines as costs, which count toward ROI at once, and files the bill on the initiative's Documents card. Lines left unticked aren't booked, and can't be booked from that proposal later.
  • A new initiative's setup is accepted on the proposal's page, once: choose the owner, tick what to keep, and Create the initiative. Recording when it went live has a tick of its own, because it approves the initiative in your name and makes it one of the initiatives your plan measures; only someone who may approve initiatives can tick it, and the months since are recorded only with it. Its figures and baselines are saved for that initiative alone, never the account. If the initiative, a figure, a baseline or the go-live can't be saved, nothing is; a month a connection already reports, or a bill Roiva can't book, is named afterwards and the rest stands. What its figures calculate waits for an approver, as for a reading, and the bill's lines then wait under Inbox → Proposals for you to book.
  • Business-case figures are accepted on Edit Business Case, where each figure shows under its field with its basis line. Use copies a figure and its basis line into the form; a flagged figure isn't taken by Use all. Saving accepts the figures you saved, and a save that used none of them leaves the draft waiting. See Writing an initiative's business case.

A draft nobody decides closes after 30 days, and a reading sooner, when its month is no longer the one Roiva asks for. Past months drafted together close once none of their months asks for a figure any more. The assistant can withdraw its own drafts. Roiva withdraws the drafts left waiting when the token is revoked or the assistant is disconnected, when the person whose assistant drafted them leaves the account, and when Who can let assistants propose changes no longer allows them; a draft from an expired token or connection can't be accepted and closes overnight.

Three ways to connect

  • Claude (claude.ai, the Claude desktop and mobile apps, Cowork and Claude Code) and ChatGPT connect by signing you in to Roiva. You approve access to one of your accounts, and the assistant reads it with your permissions. No token to copy.
  • 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 for your account first (below).
  • Cursor, Gemini CLI, Google Antigravity and other MCP clients use an access token an account Owner or Admin issues. Claude Code can use one too, instead of signing in.

Connect Claude

  1. In Claude, open Customize › Connectors and add a custom connector.
  2. Name it Roiva, and enter the MCP server URL shown on Organization Settings → API Access (https://app.roiva.ai/mcp). Leave the OAuth fields empty.
  3. Choose Connect in Claude. Claude opens Roiva's sign-in. Sign in the way your organization asks (with single sign-on if it requires it), choose the account if you're in more than one, and choose Allow (Allow read access where the account doesn't let your assistant draft changes).
  4. Ask Claude something, such as "What's our portfolio ROI over the last year?"

On a Claude Team or Enterprise plan, an Owner adds the connector once for the organization, and each person then connects it and signs in to Roiva themselves.

Connect Claude Code

  1. In a terminal, run claude mcp add --transport http roiva https://app.roiva.ai/mcp.
  2. In Claude Code, type /mcp, choose roiva, and choose to authenticate. Your browser opens Roiva's sign-in: sign in, choose the account, and choose Allow. Roiva's page says it will return to a program on this computer (localhost): that's Claude Code, listening for the answer. If you didn't just start this from Claude Code, choose Cancel.
  3. Ask Claude Code something, such as "What's our portfolio ROI over the last year?"

Claude Code keeps the sign-in on your computer, and it ends as Claude's does (below). Where a browser isn't available, such as a server or a build job, use an access token instead.

Connect ChatGPT

ChatGPT connects the same way, through a custom MCP server, on a ChatGPT plan that lets you add one (in a Business, Enterprise or Edu workspace, an admin may have to allow it first).

  1. In ChatGPT, open Plugins, choose + and then Add custom MCP server.
  2. Name it Roiva, enter the MCP server URL shown on Organization Settings → API Access (https://app.roiva.ai/mcp), and choose OAuth as its authentication. Leave any client ID and secret empty.
  3. Create it. ChatGPT opens Roiva's sign-in: sign in, choose the account, and choose Allow (Allow read access where the account doesn't let your assistant draft changes).
  4. In a new chat, type @, choose Roiva, and ask something, such as "What's our portfolio ROI over the last year?"

ChatGPT's deep research can also search Roiva and read what it finds: an initiative, a metric's definition, a connection's health, a template or a help article, each with a link back to Roiva.

Who can connect Claude, ChatGPT or an assistant you register a client for is an account setting, Who can connect, under AI Assistant Policy on Organization Settings → API Access: Owners and Admins unless an Owner opens it to every member. Changing it back to Owners and Admins disconnects the assistants members connected. If your account requires two-factor authentication, set it up before you connect.

To disconnect, open Profile → Connected Apps and choose Disconnect. Owners and Admins see every connection in the account in the Access table on Organization Settings → API Access, and can revoke any of them. A connection also ends when you leave the account, when an Owner limits connecting to Owners and Admins and you're a Member, when your account's two-factor or single sign-on rules no longer allow how you signed in, or a year after you connected; then you connect again. If the assistant goes 30 days without using it, its sign-in expires and you connect again too.

Register a client for Copilot Studio, Microsoft 365 Copilot, Amazon Quick or Gemini Enterprise

These assistants can't introduce themselves to Roiva the way Claude does, so an Owner or Admin registers a client for them: a client ID and secret you paste into the assistant's connection form. A client works only for the account that registered it, and only for the people there whom Who can connect allows (Owners and Admins unless an Owner opens it to every member). Each person still signs in to Roiva and approves it.

  1. Open Organization Settings → API Access and choose Register a client. Choose the assistant (Another assistant for Gemini Enterprise) and give the client a name people will recognize when they approve it.
  2. Enter the redirect address the assistant shows you, if you have it (see below for each). You can add it later. Roiva sends people back only to an address listed on the client.
  3. Choose Register, then copy the client secret right away. Roiva keeps only a one-way fingerprint of it and can't show it again. Paste the client ID, the secret, and the URLs shown with them into the assistant.

The assistant asks for these:

  • Authorization URL: https://app.roiva.ai/oauth/authorize
  • Token URL, and the refresh URL where it asks for one: https://app.roiva.ai/oauth/token
  • Scopes: roiva:read roiva:propose

Microsoft Copilot Studio. Add Roiva as an existing MCP server with the server URL https://app.roiva.ai/mcp, choose OAuth 2.0 and then Manual, and fill in the fields above. After you choose Create, Copilot Studio shows a callback URL: back in Roiva, choose Edit in the client's row in the Access table and add it as the redirect address. Then set each Roiva tool to User authentication, so each person signs in to Roiva as themselves. With the agent author's credentials, everyone who uses the agent would read Roiva as its author, and Roiva couldn't tell them apart. Your Power Platform admin can turn the author's credentials off for an environment.

Microsoft 365 Copilot. Register the client in the Teams Developer Portal (OAuth client registration) or Agents Toolkit with the fields above, and leave PKCE on. Every Microsoft 365 Copilot plugin returns to https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect, which Roiva fills in if you leave the redirect address empty. Set the registration to Any Teams app; tied to one app, every tool call fails.

Amazon Quick. Add an MCP integration with the server URL https://app.roiva.ai/mcp, choose user authentication with OAuth, and fill in the fields above. Enter the Redirect URL from that form as the client's redirect address in Roiva. When Roiva adds tools, sync the integration in Amazon Quick to pick them up.

Gemini Enterprise. Register the client as Another assistant, with https://vertexaisearch.cloud.google.com/oauth-redirect as its redirect address. In the Business edition, a team administrator opens Settings & help, then Manage team › Connected apps, and chooses Add MCP Server. In the Standard, Plus and Frontline editions, an administrator adds a Custom MCP Server data store in the Google Cloud console instead, after the organization policy and network steps Google's guide lists. Enter the server URL https://app.roiva.ai/mcp, choose OAuth 2.0, fill in the fields above, and turn on Enable PKCE Support: Roiva requires it. Choose Verify Auth to sign in once, finish creating the connection, then enable it and the Roiva actions you want, since Gemini Enterprise adds them turned off. Each person then authorizes the connector in Gemini Enterprise, which signs them in to Roiva. Google marks custom MCP servers as a preview feature.

If the secret is lost or exposed, choose Rotate secret in the client's row and paste the new one into the assistant. The old one stops working at once; connections already made keep working, but can't refresh until the assistant has the new secret. Delete disconnects everyone who connected through the client.

Who can issue a token

MCP access is on every plan, the free account included. An account Owner or Admin issues a token. The token reads what any member of the account can see, whatever the role of the person who issued it, and stops working if they leave the account. A change of their role doesn't stop it.

A token is issued from your sign-in, so your account's sign-in rules apply to it. If the account requires two-factor authentication, doesn't accept codes by text message, or allows only single sign-on, a token issued from a sign-in those rules wouldn't allow stops working. Turning one of those rules on revokes such tokens and connections, and Roiva emails each person who held one. A token or connection made from a sign-in through your account's own single sign-on is covered by it for as long as that single sign-on still covers you.

Set it up

  1. Open Organization Settings → API Access. Organization Settings is in the menu under your name at the bottom of the sidebar.
  2. Choose Issue Token, give it a name you'll recognize later, such as "Claude Code on my laptop", and how many days until it expires (90 unless you change it, up to 365). Then choose Issue.
  3. Copy the token right away. Roiva keeps only a one-way fingerprint of it and can't show it again.
  4. Add Roiva to your assistant:
    • Claude Code: run the claude mcp add command shown with your new token.
    • Cursor: paste the JSON shown with your new token into your mcp.json.
    • Gemini CLI: run the gemini mcp add command shown with your new token. It saves Roiva in your own ~/.gemini/settings.json, not the project you're in, so the token stays out of your code.
    • Google Antigravity: paste the JSON shown with your new token into its mcp_config.json. In the editor, open it from the agent panel's … menu, then MCP Servers › Manage MCP Servers › View raw config; in the CLI, type /mcp. Antigravity calls the URL serverUrl, not url, so Cursor's JSON doesn't work there.
    • Another MCP client: point it at the server URL shown on the page, and send the token as Authorization: Bearer <token>.
  5. Ask it something, such as "What's our portfolio ROI over the last year?"

Revoking a token

On Organization Settings → API Access, choose Revoke next to the token. An Owner or Admin can revoke any token in the account, not only their own. Any assistant using it is cut off on its next request. A token also stops working when it expires, when the person who issued it leaves the account or can no longer sign in, or when your account's sign-in rules no longer allow it.

On a paid plan, the same token also reads Roiva's read API, for pulling figures into a notebook or your own code, so you don't need a second one for that.

A token for Power BI or a warehouse loader is a different kind: a reporting token, issued on a paid plan under Organization Settings → Reporting Tables. It reads only Roiva's reporting tables and can't connect an assistant. See Roiva's figures in Power BI and your data warehouse.

Where your data goes

The answers Roiva returns go to your assistant and its AI provider, under your organization's own agreement with that provider. Roiva doesn't choose or control it, so check that your agreement covers this data before you connect. The AI transparency page has more detail.

A draft the assistant sends is stored in your Roiva account with the source it gave, which may quote an email or a document. An accepted draft keeps its source and the assistant's reasoning with the reading, costs or business-case figures it became; an accepted business case keeps only the figures someone saved, with their sources. One that is declined, withdrawn or closed has its figures or lines, source and rationale removed 90 days later, keeping who drafted and decided it, and when. The audit log keeps the figures drafted, or the bill's vendor and its lines' dates and amounts, and any note given when declining one, for as long as it keeps its other entries. It doesn't keep a line's wording, the source or the rationale.

Troubleshooting

  • 401 Unauthorized: the token is missing, wrong, expired, or revoked, the person who issued it has left the account, or your account's two-factor or single sign-on rules no longer allow it. An Owner or Admin can issue a new one on Organization Settings → API Access. In Claude, a 401 shows a Connect button: connect again. In ChatGPT, connect Roiva again from its plugin.
  • Claude, ChatGPT or another assistant that signs you in says it can't connect, or your account isn't listed: the sign-in page says why. Usually your role (only Owners and Admins can connect), your account requiring two-factor authentication you haven't set up, or single sign-on you need to sign in through first.
  • 403 Forbidden: Roiva has locked the account, the account owes an agreement to Roiva's Terms (accept them in Roiva and try again), or the token is a reporting token. The response says which.
  • 429 Too Many Requests: the assistant is calling Roiva faster than the rate limit allows, which is 120 requests a minute for each token or signed-in connection, and 300 a minute for all of an account's tokens and connections together. So an assistant calling hard can use up the account's allowance and slow the others. Wait a minute and try again.