> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.truvo.com/llms.txt. # Connect your AI agent Truvo's MCP server is at: ```text 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](#use-an-api-key-instead) and [Keys and environments](/guides/authentication). ## 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](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) * **ChatGPT** (on the web): go to [chatgpt.com/plugins](https://chatgpt.com/plugins), select the plus button, then **Add custom MCP server**, and paste the URL as the server URL. [OpenAI's guide](https://developers.openai.com/api/docs/guides/custom-mcp-server) * **Claude Code:** add the server, then run `/mcp` and finish sign-in in your browser. [Claude Code's guide](https://code.claude.com/docs/en/mcp) ```bash claude mcp add --transport http truvo https://api.truvo.com/v1/mcp ``` * **Cursor:** add the server to `~/.cursor/mcp.json`. [Cursor's guide](https://cursor.com/docs/mcp) **`~/.cursor/mcp.json`** ```json title="~/.cursor/mcp.json" { "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](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) **`.vscode/mcp.json`** ```json title=".vscode/mcp.json" { "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 | Tool | What it does | | --------------------------------------------------------------- | ------------------------------------------------------------------- | | [`get_capabilities`](/api-reference/mcp/get-capabilities) | Returns what Truvo can quote for a line, and the quote disclosure. | | [`start_quote_request`](/api-reference/mcp/start-quote-request) | Starts a quote request, after you agree to the quote disclosure. | | [`get_quote_request`](/api-reference/mcp/get-quote-request) | Returns a quote request and its quotes. | | [`list_quote_requests`](/api-reference/mcp/list-quote-requests) | Lists the quote requests you started while signed in, newest first. | | [`get_quote`](/api-reference/mcp/get-quote) | Returns one quote. | | [`send_feedback`](/api-reference/mcp/send-feedback) | Sends Truvo a report, if you agree. | `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](https://www.truvo.com/dashboard?tab=settings#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](/guides/agents), 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](https://partners.truvo.com/developers) 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`: ```bash 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](/guides/agents) 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: ```text wordWrap 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. | Setting | Value | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Endpoint | `https://api.truvo.com/v1/mcp` | | Transport | Streamable HTTP, MCP 2026-07-28 and the 2025 revisions, with no session. A 2026-07-28 request gets a JSON answer, and an earlier request gets an event stream that holds one JSON-RPC message. | | Authentication | Your key as a bearer token, the same key the HTTP API takes, or OAuth sign-in with a Truvo account | #### 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: **`.mcp.json`** ```json title=".mcp.json" { "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`: ```text wordWrap 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: **`.cursor/mcp.json`** ```json title=".cursor/mcp.json" { "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: **`~/.codex/config.toml`** ```toml title="~/.codex/config.toml" [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: **`.vscode/mcp.json`** ```json title=".vscode/mcp.json" { "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: **`~/.openclaw/.env`** ```bash title="~/.openclaw/.env" TRUVO_API_KEY=trv_sandbox_... ``` Then add Truvo under `mcp.servers`. OpenClaw fills in `${TRUVO_API_KEY}` from its environment: **`~/.openclaw/openclaw.json`** ```json5 title="~/.openclaw/openclaw.json" { 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: ```bash 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: **`~/.hermes/.env`** ```bash title="~/.hermes/.env" TRUVO_API_KEY=trv_sandbox_... ``` Then add Truvo under `mcp_servers`: **`~/.hermes/config.yaml`** ```yaml title="~/.hermes/config.yaml" 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](#add-the-server). To check the connection without a client, list the tools with curl: ```bash 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](/api-reference/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](#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](/guides/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](/guides/versioning). ### 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](/guides/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](/guides/agents#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](/guides/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`: **`AGENTS.md`** ```markdown title="AGENTS.md" wordWrap ## 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](https://www.truvo.com/privacy) * [Terms](https://www.truvo.com/terms) * Support: [support@truvo.com](mailto:support@truvo.com)