Connect your AI agent

Truvo’s MCP server is at:

https://api.truvo.com/v1/mcp

Add it to your AI app as a remote MCP server. The first time the app connects, it opens Truvo’s sign-in page in your browser. There’s no key to copy. A business that builds Truvo into its own product uses a key instead; see Use an API key instead and Keys and environments.

Add the server

• Claude (claude.ai and the desktop app): go to Customize › Connectors, select + Add, then Add custom connector. Paste the URL, and under Authentication choose Sign in now. Claude’s guide
• ChatGPT (on the web): go to chatgpt.com/plugins, select the plus button, then Add custom MCP server, and paste the URL as the server URL. OpenAI’s guide
• Claude Code: add the server, then run /mcp and finish sign-in in your browser. Claude Code’s guide

claude mcp add --transport http truvo https://api.truvo.com/v1/mcp

• Cursor: add the server to ~/.cursor/mcp.json. Cursor’s guide

{
  "mcpServers": {
    "truvo": {
      "url": "https://api.truvo.com/v1/mcp"
    }
  }
}

• VS Code: add the server to .vscode/mcp.json. The first time you use it, VS Code opens your browser to sign in. VS Code’s guide

{
  "servers": {
    "truvo": {
      "type": "http",
      "url": "https://api.truvo.com/v1/mcp"
    }
  }
}

Sign in

Enter your email, then the code Truvo emails you. To get the code by text instead, select Use your phone instead; text codes go to US mobile numbers only. If you don’t have a Truvo account, this creates one. Then check the app’s name and select Allow access.

Every call to the server needs a signed-in account or a key. A call with neither gets 401.

Tools

start_quote_request records your consent to be contacted by phone, text, and email. Truvo runs no credit check. For auto, carriers can order their own credit-based insurance score.

Quote requests you start while signed in belong to your Truvo account. Your app can list them and read them by ID from any chat.

Disconnect

Remove the Truvo connector in the AI app, or open Connected apps on truvo.com and select Disconnect. The app’s next call gets 401, and the app asks you to connect again.

Use an API key instead

A coding agent can build your Truvo integration, run sandbox quotes while it works, and read the errors that come back. Give it agents.md, one Markdown file that explains the whole API, and access to the API through the Truvo MCP server or over HTTP. Every setup in this section uses a sandbox key, which never reads a live record or causes a live effect.

Keep the key out of the prompt

Create a sandbox key on the Developer sandbox page of the portal. It starts with trv_sandbox_. Keep it in an environment variable or your agent’s private environment file, never in a prompt, a chat, an MCP config, or a file you commit. Every setup below reads it from TRUVO_API_KEY:

export TRUVO_API_KEY="trv_sandbox_..."

Start your agent from the same shell, or set the variable where your editor can read it, and the agent can call the API without the key appearing in the conversation.

Give your agent agents.md

agents.md covers the whole API in one file. Point your agent at its Markdown copy before it writes any code. This prompt works, and it holds no secret:

Read https://docs.truvo.com/guides/agents.md, then add Truvo quotes to this app.
Use the sandbox key in the TRUVO_API_KEY environment variable, and never print it.

Every page on this site has a Markdown copy too. Add .md to its URL, or send Accept: text/markdown. /llms.txt lists each page in the sidebar with a one-line summary, and the Copy page button at the top of each page copies it as Markdown for a chat.

Connect over MCP

The Truvo MCP server gives your agent the quote operations as tools. Each tool runs the same operation as its HTTP route, with the same key, rules, and errors.

Claude Code

Add the server to .mcp.json at the root of your project. Claude Code fills in ${TRUVO_API_KEY} from your environment when it connects, so the file holds no secret and you can commit it:

{
  "mcpServers": {
    "truvo": {
      "type": "http",
      "url": "https://api.truvo.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${TRUVO_API_KEY}"
      }
    }
  }
}

Claude Code asks you to approve a project server the first time it loads one. After that, run /mcp in a session to see the Truvo tools.

Cursor

To add Truvo to Cursor from a link, paste this one into your browser’s address bar. Cursor asks you to confirm, and the server it adds reads your key from TRUVO_API_KEY:

cursor://anysphere.cursor-deeplink/mcp/install?name=truvo&config=eyJ1cmwiOiJodHRwczovL2FwaS50cnV2by5jb20vdjEvbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyICR7ZW52OlRSVVZPX0FQSV9LRVl9In19

To add the server yourself, put it in .cursor/mcp.json in your project, or in ~/.cursor/mcp.json to use it in every project:

{
  "mcpServers": {
    "truvo": {
      "url": "https://api.truvo.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TRUVO_API_KEY}"
      }
    }
  }
}

Cursor resolves ${env:TRUVO_API_KEY} from its own environment, so set the variable in your shell profile or your system environment, then restart Cursor.

Codex

Add the server to ~/.codex/config.toml. The Codex CLI and the IDE extension share this file:

[mcp_servers.truvo]
url = "https://api.truvo.com/v1/mcp"
bearer_token_env_var = "TRUVO_API_KEY"

Codex sends the value of TRUVO_API_KEY as the bearer token. Run codex mcp list to check that truvo is there.

VS Code

Add the server to .vscode/mcp.json. VS Code asks for the key the first time the server starts and stores it securely, so the key stays out of the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "truvo-api-key",
      "description": "Truvo sandbox key",
      "password": true
    }
  ],
  "servers": {
    "truvo": {
      "type": "http",
      "url": "https://api.truvo.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:truvo-api-key}"
      }
    }
  }
}

OpenClaw

OpenClaw reads MCP servers from ~/.openclaw/openclaw.json on the machine that runs your Gateway. Keep the key out of that file and put it in ~/.openclaw/.env, one of the files OpenClaw reads environment variables from:

TRUVO_API_KEY=trv_sandbox_...

Then add Truvo under mcp.servers. OpenClaw fills in ${TRUVO_API_KEY} from its environment:

{
  mcp: {
    servers: {
      truvo: {
        url: "https://api.truvo.com/v1/mcp",
        transport: "streamable-http",
        headers: {
          Authorization: "Bearer ${TRUVO_API_KEY}",
        },
      },
    },
  },
}

The Gateway watches the file and applies the change. To check that it can reach Truvo and list the tools, run:

openclaw mcp doctor truvo --probe

Hermes Agent

Hermes reads MCP servers from ~/.hermes/config.yaml. Put the key in ~/.hermes/.env, so the config file holds only a reference to it:

TRUVO_API_KEY=trv_sandbox_...

Then add Truvo under mcp_servers:

mcp_servers:
  truvo:
    url: "https://api.truvo.com/v1/mcp"
    headers:
      Authorization: "Bearer ${TRUVO_API_KEY}"

Start a new session, or run /reload-mcp in the one you have open. Hermes adds mcp__truvo__ to the front of each tool name, so start_quote_request shows up as mcp__truvo__start_quote_request.

Other MCP clients

Any client that speaks Streamable HTTP can connect to https://api.truvo.com/v1/mcp. A client that can send a header sends your key in the Authorization header as a bearer token. A client that connects only through OAuth signs in with a Truvo account; see Add the server.

To check the connection without a client, list the tools with curl:

curl https://api.truvo.com/v1/mcp \
  -H "Authorization: Bearer $TRUVO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

The answer is an event stream with one message event, whose data line is the JSON-RPC answer. It lists the tools that your key can call. A GET to the endpoint gets 405, because the server keeps no session.

Differences from HTTP

MCP tools lists each tool. Each tool’s page has its inputs, its result, its HTTP route, and the callers that see it.

A few things work differently from HTTP:

• request_key is the MCP form of the Idempotency-Key header. Send a new random UUID for each new quote, and resend the same value only when you retry the same call. With a partner key, it shares the replay scope with HTTP: a key you used over HTTP replays over MCP, and the other way round, for at least 24 hours. A platform key and a call without a key replay a random UUID too, for 24 hours; see Read handles.
• The start_quote_request input lists application as an object with no fields, because each line has its own. Build the application from the required_facts_schema that get_capabilities returns for the line. Truvo checks it against the same schema as POST /v1/quote-requests, so a missing fact gets needs_information, and a wrong value gets invalid_input.
• A refused call comes back as a tool error that carries the same error envelope as HTTP, with its own request_id. Errors lists the codes.
• While Truvo accepts feedback, the server instructions ask the agent to offer the person a feedback report after a quote request finishes, when the person seems frustrated, or when a tool gives it trouble it can’t fix. The agent shows the person the report and calls send_feedback only if they agree, at most once per conversation unless they ask.
• The server always answers in the current revision of the contract, and it doesn’t need the Truvo-Version header. Code that needs a stable contract should call the HTTP API and send the header on every request to an API operation. See Versions and changes.

Read handles and the quote disclosure

The setups above use a partner key, which owns every request it makes and reads each one by ID. A platform key and a call without a key work differently on the MCP server.

Read handles

A platform key is a key that Truvo issues to an AI platform. It names the platform, not the person in the chat, and it works only on the MCP server. The HTTP routes answer it with 403 wrong_key_kind. Each request a platform key makes gets its own read handle, and only that handle reads the request.

• start_quote_request returns the handle in read_handle, with its expiry in read_handle_expires_at. Truvo keeps only a one-way digest of the handle, so save it.
• get_quote_request and get_quote take the handle in read_handle. A request ID without its handle reads nothing.
• A handle reads its request and that request’s quotes for 24 hours. After that, request quotes again to get a new handle.
• A retry of start_quote_request within 24 hours of the first call, with the same random request_key and the same input, returns the same request and the same handle. It counts as a read and starts no second quote. It gets the same authorization checks as a new request. Truvo doesn’t validate its input again, and capacity limits and outage refusals don’t apply to it. A retry that arrives while the first call is still being handled can get 409 conflict with the retry action retry. Send it again a few seconds later with the same request_key. The whole input must match: the facts, the line, and the disclosure fields. The same request_key with different input starts a new request instead of the 409 that a partner key gets. Only a random version 4 UUID replays, as Retry safely with request keys explains. Any other key, such as 1, a readable label, or a sample UUID from documentation, starts a new request on every call. After 24 hours, the same key starts a new request.
• A platform key can use get_capabilities, start_quote_request, get_quote_request, and get_quote when quoting is available, and send_feedback while Truvo accepts feedback. It doesn’t get list_quote_requests, list_api_requests, or the webhook tools.

Calls without a key

The MCP server has a mode for assistants that call without a key, which Truvo turns on separately. While it’s off, a call without a key gets 401 authentication_failed. In this mode, the caller reads by handle, as a platform key does.

A call without a key that carries an Origin header, or the Sec-Fetch-Site header that browsers add, gets 403 forbidden. Send it from a server or an MCP host, without an Origin header.

The quote disclosure

Every caller states the person’s consent the same way, with an API key or without a key. Truvo’s versioned quote disclosure takes the place of a consent receipt:

1. get_capabilities returns quote_disclosure, with the disclosure text, its version, its sha256, and the privacy_notice_url.
2. The assistant shows the person the text as written and asks whether they agree.
3. Only if they agree, start_quote_request sends the version in quote_disclosure_version and true in quote_disclosure_accepted. A missing or outdated version gets invalid_input, and so does any value other than true.
4. When Truvo accepts the request, it records the person’s consent itself. The answer names each receipt, with its receipt_id and the disclosure_version: quote_consent, contact_consent, and, for auto, credit_consent.

The person’s yes covers the quote, contact by phone, text, and email, and for auto a credit check. So every request needs the person’s email and a US phone number. The quote disclosure in agents.md lists the fields a request can’t send, and each refusal.

Use the API over HTTP

An agent can also call Truvo over HTTP, with the key in TRUVO_API_KEY, by sending the requests the Quickstart shows with curl or your HTTP client. The code your agent writes calls Truvo from your product the same way.

To keep a coding agent on the rules in every session, paste this block into the instructions file it reads, such as AGENTS.md:

## Truvo API
This project gets insurance quotes from the Truvo API.
- Read https://docs.truvo.com/guides/agents.md before you write code that calls Truvo.
- The key is in the TRUVO_API_KEY environment variable. Never print it, log it, or write it to a file.
- Use the sandbox. Sandbox keys start with trv_sandbox_.
- Send Truvo-Version: 2026-09-26 on every REST request. On 400 invalid_version, send a revision from error.field_errors[0].allowed_values.
- Before each quote request, show the person the quote_disclosure text from GET /v1/capabilities as written, and ask whether they agree. Send its version in quote_disclosure_version, and send quote_disclosure_accepted: true only if they agree.
- Send a new Idempotency-Key with each POST /v1/quote-requests. To retry the same request, send the same key and the same body.
- POST /v1/quote-requests answers 202 with the status in_progress. Read GET /v1/quote-requests/{id} with Prefer: wait=20 and since_version set to the version of the last answer, starting with the 202 answer, until the status is no longer in_progress. Each read answers when the request changes, and a request in progress lists the quotes so far.
- Switch on status. Show status_details.message to the person, and give any switch on status_details.reason a default branch, because Truvo can add reasons in any revision.
- On an error, branch on error.code and error.retry_action.type, never on the message. Report the request_id with any failure.
- While Truvo accepts feedback, if the Truvo API gives you trouble you can't fix, offer to report it to Truvo. Show the developer the report, and send POST /v1/feedback only if they agree. Leave out personal data.
- Ignore answer fields you don't know. Give each switch on error.code, line, or an event type a default branch, because Truvo can add values in any revision.
- A quote is a price offer, not coverage. One carrier's quote isn't a market comparison, and an unknown value stays unknown.

Privacy, terms, and support

• Privacy
• Terms
• Support: support@truvo.com