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, 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 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:

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 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:

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.

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

Add the server to .cursor/mcp.json in your project, or to ~/.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}"
      }
    }
  }
}

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:

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

The server lists the five webhook tools only while webhooks are on. 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 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 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:

## 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