Install the MCP server

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.

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 to have it added, or use an API key where your app supports one.

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.

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.

Connect with your Traceten account

In your AI app, add a connector pointing at:

https://api.traceten.com/mcp

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

You sign in with your normal Traceten account. The connection acts as you, so it can only ever see what you can see.
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.
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.

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.

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.

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

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.

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.

Name it and enter the server URL

Name it Traceten, enter the URL below, and select Continue.

https://api.traceten.com/mcp

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.

Add it and sign in

Select Add. Your browser opens for the sign-in above, and all three steps there apply.

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.

Claude Code

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

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.

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:

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:

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

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, Codex or VS Code, which have no such restriction.

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.

Create the app

Go to Settings, then Apps, then Create. Admins and owners can also start from Workspace settings, then Apps, then Create.

Enter the server URL

Name it Traceten and enter the URL below as a Streamable HTTP endpoint.

https://api.traceten.com/mcp

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.

Scan tools and sign in

Select Scan Tools. Your browser opens for the sign-in above. 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.

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.

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.

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.

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:

codex mcp add traceten --url https://api.traceten.com/mcp

Then sign in:

codex mcp login traceten

Your browser opens for the sign-in described above. 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:

[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

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

{
  "servers": {
    "traceten": {
      "type": "http",
      "url": "https://api.traceten.com/mcp"
    }
  }
}

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.

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

{
  "mcpServers": {
    "traceten": {
      "url": "https://api.traceten.com/mcp",
      "headers": {
        "Authorization": "Bearer tk_live_your_key_here"
      }
    }
  }
}

Reload Cursor. Traceten appears under Settings, then MCP.

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.

Any stdio-only client

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

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

Tools reference
Safety and permissions
CLI, the same surface for a script rather than an assistant

​What this lets you do

​Connect with your Traceten account

​What happens when you sign in

​Turning it off

​Paste an API key

​Claude

​Claude Code

​Claude Code with an API key instead

​Claude Desktop

​ChatGPT

​Codex

​Codex with an API key instead

​VS Code

​Cursor

​Any stdio-only client

​Verify it worked

​Troubleshooting

​Next

What this lets you do

Connect with your Traceten account

What happens when you sign in

Turning it off

Paste an API key

Claude

Claude Code

Claude Code with an API key instead

Claude Desktop

ChatGPT

Codex

Codex with an API key instead

VS Code

Cursor

Any stdio-only client

Verify it worked

Troubleshooting

Next