> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.truvo.com/guides/agent-setup/llms.txt. # Agent setup A coding agent can build your Truvo integration, run sandbox quotes while it works, and read the errors that come back. Give it two things: [truvo.md](/guides/truvo), one Markdown file that explains the whole API, and access to the API itself, through the Truvo MCP server or over plain HTTP. Everything on this page uses a sandbox key, and a sandbox key never reads a live record or causes a live effect. ## Keep the key out of the prompt You need a sandbox key, which starts with `trv_sandbox_`. Create one on the [Developer sandbox](https://partners.truvo.com/developers) page of the portal. Put it in an environment variable and nowhere else: not in a prompt, not in a chat, and not in 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. The agent can then call the API without the key ever appearing in the conversation. ## Give your agent truvo.md [truvo.md](/guides/truvo) covers the concepts, every operation, keys, the sandbox scenarios, errors and retries, polling, and request keys in one file. Point your agent at its Markdown copy before it writes any code. A prompt like this one works, and it holds no secret: ```text wordWrap Read https://docs.truvo.com/guides/truvo.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 every page 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. Each `POST` gets a JSON answer, and the server keeps no session. | | Authentication | Your key as a bearer token, the same key the HTTP API takes | ### 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 Add the server to `.cursor/mcp.json` in your project, or to `~/.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}" } } } } ``` ### Other MCP clients Any client that speaks Streamable HTTP and can send a header can connect. Point it at `https://api.truvo.com/v1/mcp` and send your key in the `Authorization` header as a bearer token. The server takes a key only. It doesn't offer an OAuth sign-in, so a client that connects only through OAuth can't use it. 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 lists the tools in the next section. A `GET` to the endpoint gets `405`, because the server doesn't open an event stream. ### Tools | Tool | What it does | HTTP route | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | | `get_insurance_capabilities` | Shows what your key can quote for one `line`: the states, the facts a quote request needs with their JSON Schema, and the actions a quote can offer. | `GET /v1/capabilities` | | `request_insurance_quotes` | Starts one quote request for one person and one line, and returns at once with the request `queued`. It requires a `request_key`. In the sandbox, an optional `scenario` picks the outcome. | `POST /v1/quote-requests` | | `get_quote_request` | Reads a quote request, with each quote's terms and next actions inline. `wait_seconds`, from 0 to 20, holds the answer while the request is `queued` or `running`. | `GET /v1/quote-requests/{id}` | | `list_quote_requests` | Lists your quote requests, newest first. It filters by `status`, `line`, `created_after`, `created_before`, or `updated_since`, and pages with `limit` and `cursor`. | `GET /v1/quote-requests` | | `get_insurance_quote` | Reads one quote. Leave out `version` to read the latest version. | `GET /v1/quotes/{id}` | | `send_feedback` | Tells Truvo about a missing feature, a bug, an unclear error, or unclear docs. The server lists it only while Truvo accepts feedback. | `POST /v1/feedback` | | `list_recent_requests` | Lists your integration's recent requests, newest first, with each one's status, error code, and request ID, so an agent can debug a failed call. The server lists it only while the request log is on. | `GET /v1/requests` | | `send_test_event` | Sends a test event to one of your webhook subscriptions, to check that your endpoint gets it and verifies its signature. It requires a `request_key`. | `POST /v1/event-subscriptions/{id}/test` | | `list_event_deliveries` | Lists the deliveries of one webhook subscription from the last 30 days, newest first. | `GET /v1/event-subscriptions/{id}/deliveries` | | `get_event_delivery` | Reads one delivery, with its attempts and the HTTP status your endpoint answered. | `GET /v1/event-subscriptions/{id}/deliveries/{event_id}` | | `replay_event_delivery` | Sends an event from the delivery log again, with the same event ID. It requires a `request_key`. | `POST /v1/event-subscriptions/{id}/replay` | | `get_event_subscription_health` | Shows whether delivery to one webhook subscription works. | `GET /v1/event-subscriptions/{id}/health` | The server lists the five webhook tools only while webhooks are on. [Webhooks](/guides/webhooks) covers subscriptions and deliveries. A few things work differently from HTTP: * `request_key` is the MCP form of the `Idempotency-Key` header, and it shares the replay scope with HTTP. A key you used over HTTP replays over MCP, and the other way round. A key replays for at least 24 hours. * 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. * Canceling a quote request and the sandbox controls have no tool. Use HTTP for those. ## Use the API over HTTP An agent doesn't need MCP to call Truvo. With the key in `TRUVO_API_KEY`, it can send the same requests the [Quickstart](/guides/quickstart) shows, with curl or your HTTP client. That's also how the code your agent writes will call Truvo from your product. 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/truvo.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 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 queued. Read GET /v1/quote-requests/{id} with Prefer: wait=20 until the status is no longer queued or running. - On an error, branch on error.code and error.retry_action.type, never on the message. Report the request_id with any failure. - A quote is a price offer, not coverage. One carrier's quote isn't a market comparison, and an unknown value stays unknown. ``` ## Next steps #### [truvo.md](/guides/truvo) The whole API in one Markdown file. #### [Quickstart](/guides/quickstart) Price your first sandbox quote with curl. #### [Errors](/guides/errors) Read the error envelope and its retry action. > Connect Claude Code, Cursor, Codex, or any MCP client to the Truvo API with a sandbox key.