# Connect an agent to trvrse

Mint a key at [Settings → Agent access](https://www.trvrse.com/settings/agent). 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`, so a bad
paste shows up as a failed connection immediately, not at the first tool
call.

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

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

**Or let the CLI do it and run the health check**

```
npx trvrse connect --key trv_YOUR_KEY_HERE
```

Honours CLAUDE_CONFIG_DIR; prints key name, spend cap and remaining credits on success.

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

```json
{
  "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.

```json
{
  "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

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

```json
{ "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`.

Full tool catalog and workflow: [https://www.trvrse.com/docs/agents](https://www.trvrse.com/docs/agents).