Traackr API MCP Server

An MCP server for the Traackr API v1, built with FastMCP directly from the API's OpenAPI spec. Use it either way — the tools are the same:

• Hosted (pilot) at https://api.mcp.traackr.ai/mcp: nothing to install; your MCP client sends your API key with each request. It is rolling out to pilot customers now — check with your Traackr contact that it is live before relying on it. See Hosted server.
• Local via uvx traackr-api-mcp from PyPI: runs on your machine with your key in the client's env block. See Run it locally.

Tools

Tool names, summaries, and descriptions are derived entirely from the OpenAPI spec (each operation's operationId / summary / description) — nothing is hardcoded, so new endpoints appear automatically as the spec evolves.

The table below reflects the spec at the time of writing — treat the live spec as the source of truth, since the server generates its tools from it at startup.

Tool	Method / Path	Description
listCampaigns	GET /v1/campaigns	List campaigns
getCampaign	GET /v1/campaigns/{campaignId}	Get a campaign
listCampaignCreators	GET /v1/campaigns/{campaignId}/creators	List creators on a campaign
listCampaignPosts	GET /v1/campaigns/{campaignId}/posts	List posts on a campaign
getCampaignSpend	GET /v1/campaigns/{campaignId}/spend	Get campaign spend totals
listCampaignCreatorsSpend	GET /v1/campaigns/{campaignId}/creators/spend	List per-creator spend on a campaign
getCreatorSpend	GET /v1/campaigns/{campaignId}/creators/{creatorId}/spend	Get a creator's spend on a campaign
listCampaignCreatorDeliverables	GET /v1/campaigns/{campaignId}/creators/{creatorId}/deliverables	List a creator's deliverable line items on a campaign
listCampaignCreatorProducts	GET /v1/campaigns/{campaignId}/creators/{creatorId}/products	List products sent to a creator
getCreator	GET /v1/creators/{creatorId}	Get a creator
getCreatorSegments	GET /v1/creators/{creatorId}/segments	Get a creator's segments

Hosted server

The hosted server is in pilot. It may not be reachable yet; if the URL below does not answer, use the local install and ask your Traackr contact when it goes live. Any API key that works against the Traackr API works against it — there is no separate enablement. It speaks MCP over streamable HTTP at:

https://api.mcp.traackr.ai/mcp

Authenticate with your Traackr API key on every request, sent as an X-Api-Key header (Authorization: Bearer <key> is accepted too). Replace your-api-key-here below with your key.

Claude Code

claude mcp add --transport http --header "X-Api-Key: your-api-key-here" \
  traackr https://api.mcp.traackr.ai/mcp

Claude.ai and Claude Desktop (custom connector)

1. Open Customize → Connectors (Team and Enterprise owners: Organization settings → Connectors) and choose Add custom connector.
2. Enter https://api.mcp.traackr.ai/mcp as the server URL.
3. Under Authentication choose No sign-in, then add a Request header named x-api-key with your key as its value.
4. Click Add.

Request headers are rolling out in beta. If that section is missing from your dialog, use the local install, or ask your Traackr contact about the URL form.

Cursor

In ~/.cursor/mcp.json (or a project's .cursor/mcp.json):

{
  "mcpServers": {
    "traackr": {
      "url": "https://api.mcp.traackr.ai/mcp",
      "headers": { "X-Api-Key": "your-api-key-here" }
    }
  }
}

Any other client

Use the streamable HTTP transport with the URL above and a custom request header X-Api-Key: your-api-key-here.

Clients that cannot send headers

A deployment can be configured to also accept the key on the URL:

https://api.mcp.traackr.ai/mcp?api_key=your-api-key-here

It is off by default, and it is a setting of the whole deployment rather than of your account: when it is on, it is on for every caller, and the key then travels in the URL, which proxies and access logs record. Prefer a header wherever your client offers one, and ask your Traackr contact before relying on the URL form.

Run it locally

The same server, installed from PyPI and run by your MCP client on your machine.

Prerequisites

• uv (provides uvx). Install with:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• A Traackr API key (provisioned by Traackr; sent as the X-Api-Key header).

uvx fetches and runs the published package in one step — there is nothing else to install.

Quick start

Pick your client. In every case, replace your-api-key-here with your key.

Claude Code

claude mcp add traackr \
  --env TRAACKR_API_KEY=your-api-key-here \
  -- uvx traackr-api-mcp

Claude Desktop

Edit the config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json) and add:

{
  "mcpServers": {
    "traackr": {
      "command": "uvx",
      "args": ["traackr-api-mcp"],
      "env": { "TRAACKR_API_KEY": "your-api-key-here" }
    }
  }
}

Restart Claude Desktop afterward.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.traackr]
command = "uvx"
args = ["traackr-api-mcp"]
env = { TRAACKR_API_KEY = "your-api-key-here" }

Any other MCP client

Use the same command and args:

command: uvx
args:    traackr-api-mcp
env:     TRAACKR_API_KEY=your-api-key-here

Versioning

uvx traackr-api-mcp runs the latest published release. To pin a specific version, append @<version>:

claude mcp add traackr \
  --env TRAACKR_API_KEY=your-api-key-here \
  -- uvx traackr-api-mcp@1.2.0

uvx caches builds, so if a new version has been published and you want it immediately, force a refresh:

uvx --refresh traackr-api-mcp

A full client restart after refreshing ensures the MCP server process is relaunched against the new build.

Configuration

All configuration is via environment variables (set them in your client's env block):

Variable	Required	Default	Purpose
TRAACKR_API_KEY	yes	—	API key, sent as the X-Api-Key header
TRAACKR_API_BASE_URL	no	first servers entry in the spec	Override the API base URL (e.g. a pilot host)
TRAACKR_OPENAPI_URL	no	https://api.traackr.ai/api/openapi/v1	Load the OpenAPI spec from this URL (e.g. a staging spec)

To host the server yourself instead of running it per user, three more apply:

Variable	Default	Purpose
MCP_TRANSPORT	stdio	http serves streamable HTTP at /mcp; callers then send their own key per request, TRAACKR_API_KEY must be unset, only the process environment is read, and the live spec is required
MCP_HTTP_PORT	8080	Listen port in http mode
MCP_ALLOW_QUERY_API_KEY	false	In http mode, also accept ?api_key= on the URL for every caller (URLs get logged — leave off unless a client needs it)

Staying in sync with the API

By default the server fetches the live OpenAPI spec from https://api.traackr.ai/api/openapi/v1 at startup and builds its tools from it — so new endpoints, fields, and description changes show up automatically with no package update. The local server also ships a bundled copy (src/traackr_mcp/traackrapi.json) that is used only as an offline fallback if the live URL can't be reached; the hosted server never falls back, so all of its replicas serve the same tools.

If Traackr provides you with an alternate spec URL, point the server at it with TRAACKR_OPENAPI_URL.

Authentication

The Traackr API authenticates with an X-Api-Key header. The hosted server forwards the key you send with each request; the local server sends the key from TRAACKR_API_KEY. In both cases the key is checked by Traackr's API, so the tools see exactly what that key is allowed to see. OAuth is planned for a future release; when it lands, it replaces the key forwarding in src/traackr_mcp/api_key.py without changing the tool surface.

Troubleshooting

• ERROR: TRAACKR_API_KEY is not set (local) — the server exits at startup rather than running and failing every call. Add the key to your client's env block (see Quick start) and restart the client.
• 401 {"error":"missing_api_key", ...} (hosted) — the request reached the server without a key. Configure the X-Api-Key request header in your client (see Hosted server); the env block only applies to the local install.
• 403 {"message":"Forbidden"} (AWS ForbiddenException) — the request is fine, but the gateway is rejecting the key. Check the key is activated for the target environment. Reproduce outside MCP with:

  curl -i -H "X-Api-Key: $TRAACKR_API_KEY" "https://api.traackr.ai/api/v1/campaigns?limit=3"
  

• Output validation error — handled: the server runs with output-schema validation disabled, since the API returns null for optional fields the OpenAPI 3.0.1 spec marks non-nullable.