> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traceten.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the MCP server

> Connect Claude, ChatGPT, Codex, VS Code, Claude Code or Cursor to Traceten, by signing in through your browser or with one line of config.

## What this lets you do

Add Traceten to your AI assistant so it can answer questions about your traffic and revenue. Takes about a minute.

There are two ways in, and which one you use depends on your app:

* **Connect with your Traceten account.** No key, no config file. Your browser opens, you sign in, and the connection acts as you. Available in **Claude** (web and desktop), **Claude Code**, **Codex**, **ChatGPT** and **VS Code**.
* **Paste an API key** into a config file. Works everywhere, and is the route for **Cursor** and for anything running without a browser.

<Note>
  **Apps have to be approved before they can connect.** We keep a list of the AI apps allowed to
  start a connection, so a link that looks like a Traceten sign-in but comes from an app we have not
  approved will not work. Claude, Claude Code, Codex, ChatGPT and VS Code are on it. If your app is
  not, the browser flow stops with a client error before the sign-in page loads. Contact
  [support@traceten.com](mailto:support@traceten.com) to have it added, or use an API key where your
  app supports one.
</Note>

<Note>
  Nothing below asks you for a client ID or a client secret. Every app on that list identifies
  itself with a metadata document it publishes, so the only thing you ever type is the server URL.
  If a setup form is asking you for OAuth client credentials, you are on a path we do not support.
  See [Troubleshooting](#troubleshooting).
</Note>

Both reach the same server and the same 83 tools, with one difference. A connection is refused `traceten_apikeys_list`, and cannot mint anything (`traceten_sites_create`, `traceten_apikeys_create`, `traceten_webhooks_create`, `traceten_webhooks_rotate_secret`). See [Safety and permissions](/mcp/safety#a-connection-can-never-issue-a-credential).

## Connect with your Traceten account

In your AI app, add a connector pointing at:

```
https://api.traceten.com/mcp
```

### What happens when you sign in

Your browser opens a Traceten sign-in page. Three things happen there, and all three matter:

1. **You sign in** with your normal Traceten account. The connection acts as *you*, so it can only ever see what you can see.
2. **You choose an organization.** If you belong to more than one, a selector appears. The connection is bound to the organization you pick and cannot read any other. There is no "current workspace" it falls back to. If you get this wrong, disconnect and reconnect.
3. **You approve the permissions.** Leave **access to your organization** ticked: it is what tells us which organization you chose, and without it the connection is refused on its first request.

That is the whole flow. No API key is created.

Your AI app holds two things afterwards: an access token that lasts up to a day, and a refresh token it uses to get new ones without asking you again. Every connection gets the refresh token: it is not optional and cannot be turned off. That is what keeps the connection working across sessions, and it is why the section below matters: **a connection does not run out on its own.**

<Note>
  If your teammate's access is limited to specific sites, their connection sees exactly those sites,
  the same restriction their dashboard has. Connecting an AI app never widens what someone can
  reach.
</Note>

### Turning it off

Removing the connector in your AI app stops that app using the connection. It does not withdraw the connection itself, and **there is no way to revoke it**: access tokens are JWTs, and a JWT cannot be revoked once issued.

**The one thing that stops it is removing the person from your organization.** Every request re-checks their membership, so the connection stops within about 30 seconds. Waiting is not an alternative: the app refreshes its own token, so a connection nobody touches keeps working indefinitely.

The 24-hour token lifetime bounds something different: an access token that has **leaked**, copied out of a log or a transcript, with no refresh token beside it. That one dies within a day. See [Turning a connection off](/mcp/safety#turning-a-connection-off).

## Paste an API key

Create an API key under **Settings, then API keys** in the dashboard and copy the plaintext value. It is shown exactly once.

Tick **Read analytics** (`stats:read`) only, unless you specifically want your assistant to create goals, funnels or webhooks. See [Safety and permissions](/mcp/safety).

Throughout the rest of this page, replace `tk_live_your_key_here` with your own key.

## Claude

Claude reaches Traceten as a **custom connector**. This works on Free, Pro, Max, Team and Enterprise plans. On Free you can have one custom connector in total.

<Steps>
  <Step title="Open your connectors">
    Go to **Settings**, then **Connectors**. On Team and Enterprise, an owner adds the connector
    once under **Organization settings, then Connectors**, and everyone else connects to it
    individually from their own **Connectors** page.
  </Step>

  <Step title="Add a custom connector">
    Select **Add custom connector**. You can also reach this from a chat: the **+** button, then **Add
    connector**, then **Add custom connector**.
  </Step>

  <Step title="Name it and enter the server URL">
    Name it `Traceten`, enter the URL below, and select **Continue**.

    ```
    https://api.traceten.com/mcp
    ```
  </Step>

  <Step title="Leave the detected settings alone">
    Claude probes the server and fills in the rest itself. Two settings appear, both marked
    **Detected**:

    * **Authentication: Always required.** Correct: every Traceten tool needs a credential.
    * **OAuth client: Use Anthropic's hosted client metadata.** Correct, and the reason you are
      never asked for a client ID. Leave it selected.

    If you open **Advanced**, transport is **Streamable HTTP**, which is also right: the server
    speaks `POST` only and has no event stream.
  </Step>

  <Step title="Add it and sign in">
    Select **Add**. Your browser opens for [the sign-in above](#what-happens-when-you-sign-in),
    and all three steps there apply.
  </Step>
</Steps>

<Warning>
  Do not switch **OAuth client** to a manually entered client ID, and do not put anything in the
  `Authorization` header field. Claude reserves that header for the connection it manages, and a
  hand-entered client ID is not on our approved list, so it is refused before the sign-in page
  loads.
</Warning>

## Claude Code

Claude Code connects with your Traceten account, so no key is involved. Add the server with no header:

```bash theme={null}
claude mcp add --transport http traceten https://api.traceten.com/mcp
```

Then authenticate. Run `/mcp` inside Claude Code, pick **traceten**, and it opens your browser for the sign-in described above. Your organization choice and permissions are approved there; nothing is stored in your project.

```bash theme={null}
claude mcp list
```

Traceten should appear with a connected status.

### Claude Code with an API key instead

The browser flow needs a browser. On a build agent, or anywhere you cannot open one, pass a key:

```bash theme={null}
claude mcp add --transport http traceten https://api.traceten.com/mcp \
  --header "Authorization: Bearer tk_live_your_key_here"
```

Use one or the other, not both.

## Claude Desktop

Use the custom connector above. **Settings, then Connectors** exists in the desktop app too, and it is the same connector list your account uses on the web.

If you would rather paste a key, open **Settings, then Developer, then Edit Config**, and add Traceten to `mcpServers`:

```json theme={null}
{
  "mcpServers": {
    "traceten": {
      "type": "http",
      "url": "https://api.traceten.com/mcp",
      "headers": {
        "Authorization": "Bearer tk_live_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. Traceten appears in the tools menu. Use one route or the other, not both.

## ChatGPT

ChatGPT reaches a custom MCP server through **developer mode**, on the web only. There is no MCP support in the mobile apps.

<Warning>
  **This needs a paid workspace plan, and which one decides what you get.** Business, Enterprise and
  Edu get full MCP, including the tools that write. Pro gets developer mode but read and fetch tools
  only, so Traceten's goal, funnel and webhook tools will not be available. Free, Go and Plus have
  no developer mode at all: the toggle is simply absent, and there is nothing to configure. Those
  are OpenAI's limits, not ours. On a plan without it, use [Claude](#claude), [Codex](#codex) or [VS
  Code](#vs-code), which have no such restriction.
</Warning>

<Steps>
  <Step title="Turn developer mode on">
    On **Business**, only admins and owners can, and each one turns it on for themselves in
    **Settings, then Apps, then Advanced settings**.

    On **Enterprise and Edu**, an admin first grants access under **Workspace settings, then
    Permissions and roles, then Connected data**. Each granted member then turns it on in the same
    **Settings, then Apps, then Advanced settings**.
  </Step>

  <Step title="Create the app">
    Go to **Settings, then Apps, then Create**. Admins and owners can also start from **Workspace
    settings, then Apps, then Create**.
  </Step>

  <Step title="Enter the server URL">
    Name it `Traceten` and enter the URL below as a **Streamable HTTP** endpoint.

    ```
    https://api.traceten.com/mcp
    ```
  </Step>

  <Step title="Choose OAuth">
    Do not paste a client ID or secret. ChatGPT publishes its own client metadata document, and that
    document is what is on our approved list.
  </Step>

  <Step title="Scan tools and sign in">
    Select **Scan Tools**. Your browser opens for [the sign-in
    above](#what-happens-when-you-sign-in). Approve it, then wait for the scan to finish listing
    the tools, and select **Create**.

    The app now appears under **Settings, then Apps** with a **Dev** label, and as a draft in
    **Workspace settings, then Apps, then Drafts**.
  </Step>

  <Step title="Publish it to your workspace">
    An admin or owner publishes it from **Workspace settings, then Apps, then Drafts, then
    Publish**. Until then only you can use it.
  </Step>
</Steps>

<Note>
  **ChatGPT freezes the tool list when the app is approved.** It does not pick up changes to our
  server on its own. When we add or change tools, an Enterprise or Edu admin refreshes them from
  **Workspace settings, then Apps**, then the app's **Action control**. On Business, an app cannot
  be updated after publishing, so recreate and republish it.
</Note>

<Warning>
  We have not run this end to end on a Business or Enterprise workspace. The authorization itself is
  configured and works; the publish and workspace-rollout steps above follow OpenAI's documentation
  rather than our own testing. Tell us what you see at
  [support@traceten.com](mailto:support@traceten.com).
</Warning>

## Codex

Codex signs in through your browser, the same as Claude Code. It identifies itself with a metadata document it publishes, so there is no client ID to enter.

Add the server:

```bash theme={null}
codex mcp add traceten --url https://api.traceten.com/mcp
```

Then sign in:

```bash theme={null}
codex mcp login traceten
```

Your browser opens for the sign-in described [above](#what-happens-when-you-sign-in). Afterwards, `codex mcp list` shows the server, and `/mcp` inside the Codex TUI lists it as connected.

The same configuration is shared by the Codex CLI, the ChatGPT desktop app and the IDE extension, so you only do this once. In the desktop app and the IDE extension it is **Settings, then MCP servers, then Add server**. Choose **Streamable HTTP**, enter the URL, save, restart, then select **Authenticate**.

If you would rather edit `~/.codex/config.toml` directly:

```toml theme={null}
[mcp_servers.traceten]
url = "https://api.traceten.com/mcp"
```

`auth` defaults to `oauth`, which is what you want. Run `codex mcp login traceten` afterwards.

### Codex with an API key instead

```toml theme={null}
[mcp_servers.traceten]
url = "https://api.traceten.com/mcp"
bearer_token_env_var = "TRACETEN_API_KEY"
```

Codex reads the key from that environment variable rather than storing it in the file.

## VS Code

VS Code handles the browser sign-in for you. There is no key and no `oauth` block. Leaving it out is what makes VS Code identify itself with its own published metadata document, which is on our approved list.

Run **MCP: Add Server** from the Command Palette, choose **HTTP**, enter:

```
https://api.traceten.com/mcp
```

Name it `traceten` and pick **Global** to use it everywhere, or **Workspace** to commit it with the project. Confirm the trust prompt when the server starts, then complete the sign-in in your browser.

Editing `mcp.json` by hand does the same thing. Use **MCP: Open User Configuration**, or `.vscode/mcp.json` in your workspace:

```json theme={null}
{
  "servers": {
    "traceten": {
      "type": "http",
      "url": "https://api.traceten.com/mcp"
    }
  }
}
```

<Note>
  Because there is no key in it, this file is safe to commit, unlike the Cursor config below. That
  is the practical argument for the browser flow on a shared project.
</Note>

Run **MCP: List Servers** to check the status or to sign out. Signing out there removes the token from your machine; see [Turning it off](#turning-it-off) for what that does and does not stop.

## Cursor

Create `.cursor/mcp.json` in your project, or edit the global config at `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "traceten": {
      "url": "https://api.traceten.com/mcp",
      "headers": {
        "Authorization": "Bearer tk_live_your_key_here"
      }
    }
  }
}
```

Reload Cursor. Traceten appears under **Settings, then MCP**.

<Warning>
  A project-level `.cursor/mcp.json` holds your key in plaintext. Add it to `.gitignore` before you
  commit anything, or use the global config instead.
</Warning>

## Any stdio-only client

Some clients speak only the local stdio transport. Bridge to the remote server with `mcp-remote`:

```json theme={null}
{
  "mcpServers": {
    "traceten": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.traceten.com/mcp",
        "--header",
        "Authorization: Bearer tk_live_your_key_here"
      ]
    }
  }
}
```

## Verify it worked

Ask your assistant:

> List my Traceten sites.

It should call `traceten_sites_list` and come back with your sites and their snippet keys. Then try the question the product exists to answer:

> Which AI assistant drove the most revenue on example.com last month?

## Troubleshooting

**"Unauthorized" or a 401 on every tool.** The key is wrong, revoked, or expired. Keys are shown once at creation and cannot be recovered, so mint a new one rather than looking for the old value. Check you copied the whole key including the `tk_live_` prefix.

**The browser flow fails before the sign-in page, with a client error.** Your AI app is not on our approved list. That list is the reason a random app cannot put a Traceten sign-in page in front of your team, so the fix is not on your side: contact [support@traceten.com](mailto:support@traceten.com) with the name of the app.

**The browser comes straight back with `error=invalid_scope`.** Something like *"The OAuth 2.0 Client is not allowed to request scope 'email'"*. Your app is on the approved list (it got that far), but it asked for a permission the entry does not grant it. That is ours to fix, not yours: send [support@traceten.com](mailto:support@traceten.com) the app name and the scope named in the message, and it is a one-line change on our side. Nothing is wrong with your account.

**Your app asks for an OAuth client ID and client secret.** Every app we approve identifies itself with a metadata document it publishes, so there is no client ID for you to enter and we do not issue one. In Claude, that means leaving **OAuth client** on **Use Anthropic's hosted client metadata**; in Codex and VS Code it means not setting a client ID at all. If your app cannot connect without one, use an API key instead.

**The sign-in works but the app cannot connect afterwards, or asks you to sign in again every day.** The connection needs a refresh token, which comes from `offline_access`. If your app lets you choose scopes, leave that one on. Everything on our approved list requests it by default.

**Tools are listed but every one fails with a permission error.** The key is missing `stats:read`. Permissions cannot be changed after a key is created: mint a replacement with the right boxes ticked, update your config, then revoke the old key.

**A tool says the site was not found.** Site arguments take the `ttid_` snippet key, not the UUID in your dashboard URL. Call `traceten_sites_list` first and use the `id` field it returns, which is the snippet key when you authenticate with an API key. The same value is also returned as `snippet_key` on every site, under either credential, if you want the unambiguous one.

**Write tools return a preview instead of doing anything.** That is the safety gate working. Twelve tools require explicit confirmation: anything that deletes, issues a credential, or changes how your numbers are measured. Tell your assistant to proceed and it will re-send with `confirm: true`. See [Safety and permissions](/mcp/safety).

**The client reports it cannot open a stream, or a GET returns 405.** Expected. This server is stateless and speaks `POST` only. Configure it as a streamable HTTP server, not as an SSE server.

**Nothing appears after editing a config file.** Most clients read MCP configuration at startup. Fully quit and reopen the app rather than reloading a window.

## Next

* [Tools](/mcp/tools) reference
* [Safety and permissions](/mcp/safety)
* [CLI](/cli/overview), the same surface for a script rather than an assistant