---
title: "Connect Tracwell to your agent"
description: "Connect Codex, Claude Code, Cursor, or VS Code to Tracwell's MCP server for analytics and scoped goal/funnel writes."
documentation: "https://tracwell.app/docs/agents"
markdown: "https://tracwell.app/docs/agents.md"
---

# Connect Tracwell to your agent

> Connect Codex, Claude Code, Cursor, or VS Code to Tracwell's MCP server for analytics and scoped goal/funnel writes.

## Connection details

Create a key in **Settings → MCP**.

| Field | Value |
| --- | --- |
| Transport | Streamable HTTP |
| Server URL | `https://tracwell.app/mcp` |
| Authorization | `Bearer YOUR_MCP_KEY` |

Keys default to read access. A definition-write key must be scoped to one website and can also create/update its goals and funnels. Keys are secret and rate-limited. Never put a real key in source control or client-side code.

## Codex

```toml
[mcp_servers.tracwell]
url = "https://tracwell.app/mcp"
bearer_token_env_var = "TRACWELL_MCP_KEY"
```

Set `TRACWELL_MCP_KEY` before starting Codex.

## Claude Code

```bash
claude mcp add --transport http --scope user tracwell \
  https://tracwell.app/mcp \
  --header "Authorization: Bearer YOUR_READ_ONLY_KEY"
```

Run `claude mcp get tracwell` to verify the connection.

## Cursor

Save this as `~/.cursor/mcp.json` for every project or `.cursor/mcp.json` for one workspace.

```json
{
  "mcpServers": {
    "tracwell": {
      "url": "https://tracwell.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_READ_ONLY_KEY"
      }
    }
  }
}
```

## VS Code and GitHub Copilot

Add this to `.vscode/mcp.json`, or use **MCP: Open User Configuration** for global setup.

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "tracwell-mcp-key",
      "description": "Tracwell MCP read-only key",
      "password": true
    }
  ],
  "servers": {
    "tracwell": {
      "type": "http",
      "url": "https://tracwell.app/mcp",
      "headers": {
        "Authorization": "Bearer ${input:tracwell-mcp-key}"
      }
    }
  }
}
```

## Agent workflow

Start with analytics_projects, then analytics_events with view=definitions. Follow nextDefinitionCursor using definitionCursor. Inspect analytics_event_detail for typed property values, and analytics_goals or analytics_funnels for saved IDs, filters and revisions. Follow nextCursor until null; names are not unique IDs.

Use analytics_goal_preview or analytics_funnel_preview to evaluate a proposed definition. Write keys expose goal_create, goal_update, funnel_create and funnel_update. Each command requires a UUID requestId: reuse the same ID and input after a timeout. Updates also require expectedRevision from a fresh definition read. On REVISION_CONFLICT, read again and reconsider the edit. Keys cannot delete data, modify tracking settings or change billing.

Goal/funnel reports include the evaluated definition and calculation meaning. appUrl opens the same website and definition; report links preserve the exact time window and timezone. Goal conversion counts anonymous visitors with a match divided by visitors with any recorded activity. Funnel conversion counts visitors reaching the final ordered step within its window divided by first-step entrants. Average completion uses each converted visitor's shortest valid attempt. Private mode estimates visitors daily; Product mode uses anonymous browser/device identities without cross-device merging. Journeys are recorded sessions, not inferred causal paths.

## Example questions

- Compare visitors and conversion over the last 7 days.
- Which acquisition sources bring the most engaged visits?
- Inspect a recorded signup session.
- Preview a pricing-to-signup funnel, then save it with my write key.