Connect AI agents to Herv.ai

What an agent can do

Each tool needs one scope (see Scopes). The full list with arguments is the Tool reference.

A check run started by an agent does exactly what a run started in the web app does, including the client email, Karbon work items and Zapier hooks your firm has set up.

What an agent can never do

Whatever scope it holds, an agent cannot:

• run, turn on or configure Inactivate Unused Vendors or any other check that changes live

QuickBooks Online or Xero data (it is not even listed to agents as manageable);

• create, delete or disable clients, use "Enable All", or run checks across every client at once;
• connect or disconnect QuickBooks Online, Xero, Karbon or Zapier;
• invite people, change roles or permissions, or change who can open a client;
• touch billing, the subscription or discount codes;
• change firm settings, 2FA, or switch AI agent access on or off;
• change where notifications go (client email, Karbon, Zapier);
• create, see or revoke API keys or connected apps, or read the agent activity log;
• export reports (XLSX or PDF), edit dashboards, reorder checks or edit client templates;
• read general accounting data (P&L, general ledger, vendor lists); the only live lookup is the

one transaction behind a problem the member can already see;

• see bank account or routing numbers, tax ids, attachments, other people's email addresses,

or anything from another firm.

Text that came from your clients' books (names, memos, descriptions) or that another person typed is handed to the agent marked untrusted, with an instruction to report it and never follow instructions inside it.

Before you start

1. A Super Admin (owner) turns on Settings → AI Agents → AI agent access. It is off by

default. Turning it off later revokes every key and disconnects every app in the firm at once, and turning it back on restores none of them.

1. Platform-admin accounts can never connect agents.
2. Creating a key or approving an app needs a sign-in within the last 15 minutes; Herv.ai asks

you to sign in again if yours is older.

1. A firm whose subscription has lapsed into read-only mode keeps read tools; write and

destructive tools answer PAYMENT_REQUIRED, and no new app or key can be connected.

Every new key or app is emailed to the member who connected it and to every Super Admin of the firm.

Connecting with OAuth

OAuth is the normal way to connect an app: you paste the server URL into the app, sign in to Herv.ai in your browser, and approve it. Nothing secret is copied by hand. In Herv.ai, the Connect an AI agent card at the top of Connected apps & keys has the address with a Copy button and these steps; turning AI agent access on takes the owner straight there.

The steps below follow each client's published instructions and Herv.ai's discovery documents. They will be replaced by the exact verified steps, with the date, as each client passes its launch gate.

What the consent screen shows

After you sign in, Herv.ai shows a consent page with:

• the app's name, or "Unnamed app" when it registered without a usable one, and an

"Unverified app" label (Herv.ai does not vouch for any app);

• the redirect host: where Herv.ai will send you back to. Check it is the app you meant to

connect. A warning appears when it is only your own computer (localhost / 127.0.0.1);

• your email and your firm;
• the access: read is always included, write is pre-checked, and destructive is

unchecked, with the warning "Lets the agent hide findings: dismiss problems, turn checks off, add exceptions."

Approve or Deny. Denying needs no recent sign-in. An approved app holds access for at most 90 days, then asks you to approve it again.

Claude.ai and Claude Desktop (not yet verified)

1. In Claude, open Settings → Connectors → Add custom connector.
2. Name it Herv.ai and enter the URL https://app.herv.ai/mcp. Leave any client id and

secret fields empty: Claude registers itself.

1. Click Connect. Your browser opens Herv.ai; sign in (and complete 2FA) if asked.
2. Check the consent screen (above) and approve.
3. Back in Claude, ask: "Use Herv.ai's whoami tool." It should name you and your firm.

Claude Code (not yet verified)

claude mcp add --transport http herv-ai https://app.herv.ai/mcp

Then run /mcp inside Claude Code, choose herv-ai and Authenticate. Your browser opens the Herv.ai sign-in and consent pages. Claude Code receives the result on a loopback address on your own computer, which the consent page names as the redirect host.

ChatGPT (not yet verified)

1. In ChatGPT, open Settings → Apps & Connectors (developer mode may need to be on for

custom connectors on your plan) and create a connector.

1. Enter the MCP server URL https://app.herv.ai/mcp and choose OAuth authentication.
2. Sign in to Herv.ai when asked, check the consent screen and approve.

Cursor (not yet verified)

Add Herv.ai to ~/.cursor/mcp.json (or the project's .cursor/mcp.json):

{
  "mcpServers": {
    "herv-ai": {
      "url": "https://app.herv.ai/mcp"
    }
  }
}

Open Cursor Settings → MCP, find herv-ai and click Login (or Connect). Approve in the browser.

Hermes Agent (verified 2026-11-14)

In ~/.hermes/config.yaml, under mcp_servers:, add:

  herv:
    url: "https://app.herv.ai/mcp"
    auth: oauth

Run /reload-mcp in Hermes (or restart it) and choose Authenticate. Your browser opens Herv.ai: sign in, check the consent screen and approve. Hermes keeps its tokens on your computer and refreshes them itself. Verified on production with Hermes Agent v0.22.5: discovery, registration, consent and a list_clients call.

Disconnecting an app

Open Connected apps & keys (user menu, or Settings → AI Agents). Under Your connected apps, click Disconnect on one connection or Disconnect all for an app. The app's access stops on its next request. Changing or resetting your Herv.ai password also disconnects every app you approved (your API keys survive, and you get an email listing them).

Connecting with an API key

Use an API key for a script or headless agent that cannot open a browser.

1. Open Connected apps & keys → Create an API key (you may be asked to sign in again).
2. Give it a name (up to 60 characters), choose the access (read; read + write; or

read + write + destructive, which needs an extra confirmation box) and a lifetime: 7, 30, 90 (default), 180 or 365 days. Every key expires; there is no "never".

1. Copy the key now. It starts with hrv_k_ and is shown once only. Herv.ai stores only a

keyed hash of it.

1. Give it to your agent as an environment variable, never in a file you commit or share:

export HERV_API_KEY='<paste the hrv_k_ key here>'

1. Send it on every request as Authorization: Bearer <key>. Never put it in a URL: a key in

the query string is refused (400).

Each member can hold at most 10 active keys. A key keeps the scopes it was created with; to change them, create a new key and revoke the old one.

Client set-up with a key (all not yet verified on production):

• Claude Code: the shell expands the variable when the command runs, and Claude Code then

stores the key in its own config file on your computer:

claude mcp add --transport http herv-ai https://app.herv.ai/mcp \
  --header "Authorization: Bearer $HERV_API_KEY"

• Cursor (~/.cursor/mcp.json, reading the variable at start-up):

{
  "mcpServers": {
    "herv-ai": {
      "url": "https://app.herv.ai/mcp",
      "headers": { "Authorization": "Bearer ${env:HERV_API_KEY}" }
    }
  }
}

• Any MCP client library: connect with the "Streamable HTTP" transport to

https://app.herv.ai/mcp and set the Authorization header above. The server is stateless and answers in JSON (no server-sent events).

To revoke a key: Connected apps & keys → Revoke. It stops working on its next request.

Scopes and what happens when one is missing

The only valid sets are read, read write and read write destructive. Any other set is refused when a key is created or an app is approved, never silently changed.

• An agent only sees the tools its scopes and the member's permissions allow

(tools/list is filtered).

• Calling a tool anyway returns the error SCOPE_REQUIRED with the requiredScope. For an

OAuth app, the server answers 403 with WWW-Authenticate: Bearer error="insufficient_scope", so a capable client asks you to approve the wider access. An API key cannot step up: create a new key with the access you need.

• Permissions still apply inside a scope. A Staff member's agent sees the clients that member

manages, exactly as on the firm page; reports follow the report pages' rule. A client the member cannot open is NOT_FOUND, the same answer as an id that does not exist.

Tool errors come back as a tool result with isError: true and {"error": {"code": ..., "message": ...}}. The codes are VALIDATION, NOT_FOUND, FORBIDDEN, SCOPE_REQUIRED, PAYMENT_REQUIRED, RATE_LIMITED (with retryAfterSeconds), CONFLICT, REQUIRES_CONFIGURATION (with a webUrl to finish set-up in the web app), UNSUPPORTED_FOR_CHECK, UPSTREAM_UNAVAILABLE (QuickBooks Online or Xero down or disconnected), AUDIT_UNAVAILABLE and INTERNAL (with a ref support can look up).

Tool reference

29 tools: 15 read, 10 write, 4 destructive. This table is generated from the server's tool registry and a test fails when it drifts, so it is always the list the server actually serves. "Untrusted text" = the output carries fields marked untrusted (see above). Ids are Herv.ai ids, given as strings. Lists are paged: pass the next_cursor you got back as cursor, with the same filters.

Limits

Limits are per member unless they say otherwise, so a second key or app does not double them. A refused call returns RATE_LIMITED with retryAfterSeconds (or HTTP 429 with Retry-After before the call reaches a tool).

Security notes for admins

• Who can connect. Only members of a firm whose owner turned AI agent access on. The agent

acts as that member, with that member's permissions at the moment of each request: removing a member, deactivating them, changing their role or deleting the firm revokes their keys and apps immediately.

• Emails. Every new key and every newly approved app is emailed to the member and to every

Super Admin, with the app name, the redirect host, the scopes (with destructive called out) and the expiry. Never the key itself.

• Connected apps & keys page (/settings/ai-agents/keys/). Everyone sees and can revoke

their own keys and apps. Super Admins and Admins also see Everyone's connections in the firm. An Admin can revoke an Admin's or a Staff member's connection, never the owner's (shown as "Owner only"); the owner can revoke anyone's. The member is not emailed when an admin revokes their connection.

• Agent activity (/settings/ai-agents/activity/). Every tool call, newest first: who,

which key or app, which tool, the outcome and a redacted summary of the arguments (ids, numbers and choices only; free text is shown as [redacted:<length>]). Members see their own agents' calls; Super Admins and Admins see the whole firm. Filter by key or app, tool and outcome. Activity is kept for 400 days.

• "By agent" badges. A problem resolved, reopened or dismissed by an agent shows "by agent"

on the check result page, and its history entry links to the exact call in Agent activity. Dismissals always carry the agent's reason (10 to 1000 characters).

• The emergency stop. Settings → AI Agents → Turn off and revoke everything (owner only)

cuts every agent in the firm off on its next request.

• What to watch for. An unfamiliar app name or redirect host in an email; a burst of

dismissals (you are emailed at 50 in a day); destructive access you did not expect. Revoke first, then ask.

Troubleshooting