Connect an agent to trvrse

Mint a key at Settings → Agent access. The full key (trv_ + 43 characters, 47 in total) is shown once; every snippet on that page is pre-filled with it. Below, replace trv_YOUR_KEY_HERE with yours.

Endpoint: https://www.trvrse.com/api/mcp/mcp · Health: https://www.trvrse.com/api/mcp/health (send the same bearer) · Keyed URL for header-less clients: https://www.trvrse.com/api/mcp/k/trv_YOUR_KEY_HERE/mcp

A malformed, unknown or revoked key is refused at initialize with HTTP 401, so a bad paste shows up as a failed connection immediately, not at the first tool call. Being throttled is not that — see below.

Claude Code

One command registers the server for your user (all projects) and sends the key as a bearer header. A bad key now shows ✗ in claude mcp list immediately.

claude mcp add --transport http --scope user trvrse https://www.trvrse.com/api/mcp/mcp -H "Authorization: Bearer trv_YOUR_KEY_HERE"

Check the key is valid

curl -sS https://www.trvrse.com/api/mcp/health -H "Authorization: Bearer trv_YOUR_KEY_HERE"

200 with ok:true means the key is valid (with your spend cap and remaining credits); confirm the registration itself with claude mcp list. 401 names why a key is refused (malformed / unknown / revoked).

Claude.ai

Settings → Customize → Connectors → Add custom connector. If the connector form lets you set a header, use the endpoint plus the Authorization header; otherwise use the keyed URL with authentication set to None.

1. Open claude.ai → Settings → Customize → Connectors → Add custom connector (https://claude.ai/settings/customize).
2. Remote MCP server URL: https://www.trvrse.com/api/mcp/mcp
3. Header: Authorization: Bearer trv_YOUR_KEY_HERE
4. No header field? Paste the keyed URL below instead and leave authentication as None.

https://www.trvrse.com/api/mcp/mcp
Authorization: Bearer trv_YOUR_KEY_HERE

Keyed URL (for connectors that cannot set a header)

https://www.trvrse.com/api/mcp/k/trv_YOUR_KEY_HERE/mcp

This URL is the credential. Treat it like a password; prefer a spend-capped key per connector; revoke it here if it leaks.

ChatGPT

ChatGPT custom connectors (developer mode) accept OAuth or no authentication only, so use the keyed URL with authentication None.

1. ChatGPT → Settings → Connectors → Create (developer mode must be on).
2. MCP server URL: paste the keyed URL below.
3. Authentication: None → Create.

https://www.trvrse.com/api/mcp/k/trv_YOUR_KEY_HERE/mcp

Check the URL works (opens in a browser too)

https://www.trvrse.com/api/mcp/k/trv_YOUR_KEY_HERE/health

Returns {ok:true, keyName, spendCap, spent, remaining, lastSeen} for a good key.

Cursor

Add the server block to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project), or use the one-click deeplink.

1. Cursor → Settings → MCP → Add new global MCP server (opens mcp.json).
2. Paste the JSON below, save, and toggle the server on.

{
  "mcpServers": {
    "trvrse": {
      "url": "https://www.trvrse.com/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer trv_YOUR_KEY_HERE"
      }
    }
  }
}

One-click install link

cursor://anysphere.cursor-deeplink/mcp/install?name=trvrse&config=eyJ1cmwiOiJodHRwczovL3d3dy50cnZyc2UuY29tL2FwaS9tY3AvbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIHRydl9ZT1VSX0tFWV9IRVJFIn19

Open in a browser on the machine running Cursor.

mcpServers JSON

Any client with a streamable-HTTP MCP transport and custom headers (Claude Desktop, Windsurf, agent runtimes). Key names vary slightly by client.

{
  "mcpServers": {
    "trvrse": {
      "url": "https://www.trvrse.com/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer trv_YOUR_KEY_HERE"
      }
    }
  }
}

Health check

curl -sS https://www.trvrse.com/api/mcp/health -H "Authorization: Bearer trv_YOUR_KEY_HERE"

200 = connected; 401 tells you why (malformed / unknown / revoked).

Verify

curl -sS https://www.trvrse.com/api/mcp/health -H "Authorization: Bearer trv_YOUR_KEY_HERE"

{ "ok": true, "keyName": "…", "spendCap": 500, "spent": 0, "remaining": 500, "lastSeen": null, "lastSeenClient": null }

ok:false carries reason: malformed (paste is not 47 chars / wrong prefix), unknown (never minted), revoked, or rate-limited. Only rate-limited also carries retryAfterMs — the other three are not fixed by waiting.

If you get rate limited (HTTP 429)

Calls are limited per key to 60/min with a burst of 10, so a fan-out of parallel tool calls (a batch of edit_image, say) can drain the bucket. That refusal is not an auth failure and your key is fine:

HTTP/1.1 429 Too Many Requests
Retry-After: 3

{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32029,
  "message": "BRIDGE_RATE_LIMITED: too many bridge calls for this API key …",
  "data": { "code": "BRIDGE_RATE_LIMITED", "retryAfterSeconds": 3,
            "retryable": true, "idempotent": true } } }

What to do: wait the Retry-After interval, then reissue the same call. The request was refused at the door — nothing was dispatched and no credits were reserved or spent — so retrying cannot double-charge. If you passed an idempotencyKey, reuse the same key on the retry; that keeps it safe even if you are wrong about which call was refused.

What not to do: do not re-mint or replace the key. Telling the two apart is exactly why a throttle answers 429 with Retry-After and no WWW-Authenticate challenge, while a genuine credential failure answers 401 with one. Before 2026-09-07 a throttle was reported as BRIDGE_AUTH_FAILED on a 401, which sent agents off to replace a working key; if you have retry logic that keys on that, it can go.

To lower the chance of hitting it, cap your own concurrency (≤10 in flight per key) rather than retrying into the limit.

Full tool catalog and workflow: https://www.trvrse.com/docs/agents.