Skip to content
Browse documentation

MCP server

Connect an AI agent or assistant to your tracking data through the read-only Model Context Protocol server at /api/mcp, authenticated with an API key.

Last updated 4 min read

On this page

TrackCrown exposes a read-only Model Context Protocol server so AI agents and assistants (Claude, ChatGPT connectors, IDE agents, your own tools) can answer questions about your tracking data: "Which offers made the most profit yesterday?", "Find the click for this gclid", "Build a tracking link for partner Acme".

Endpointhttps://app.trackcrown.com/api/mcp
TransportStreamable HTTP, POST only, stateless JSON responses (no SSE stream)
Protocol versions2025-06-18, 2025-03-26, 2024-11-05
AuthenticationAuthorization: Bearer atk_… — a REST API key
AccessRead-only. No tool creates, changes or deletes anything.

Every tool calls the same code as the matching REST endpoint, so the key's workspace, role (partner and advertiser restrictions), IP allowlist and rate limit (600 requests per minute, shared with the REST API) apply unchanged. Each tool call is written to the workspace audit log.

Connect a client#

  1. Create a key for the agent: Settings → API keys → Create API key, access Analyst (read-only is all the server needs). For a partner's or advertiser's own assistant, use their portal key instead.
  2. Optional: restrict the key with an IP allowlist if the agent runs from fixed addresses.
  3. Add the server to your client as a remote (HTTP) MCP server with the URL and an Authorization header.

Example client configuration (format varies by client):

JSON
{
  "mcpServers": {
    "TrackCrown": {
      "type": "http",
      "url": "https://app.trackcrown.com/api/mcp",
      "headers": { "Authorization": "Bearer atk_AbCd1234_…" }
    }
  }
}

Tools#

ToolTitleArgumentsSame as
whoamiWho am I—GET /me
run_reportRun a reportfrom, to, preset, tz, group_by[], metrics[], sort, limit (1–1000), currency, paramsGET /reports
list_offersList offersq, status, limit (1–200), cursor, paramsGET /offers
get_offerGet an offerid (id or code, required)GET /offers/{id}
list_affiliatesList partnersq, status, limit (1–200), cursor, params — staff keys onlyGET /affiliates
get_affiliateGet a partnerid (required) — staff keys onlyGET /affiliates/{id}
list_conversionsList conversionsfrom, to, preset, tz, status, event, click_id, limit (1–500), cursor, paramsGET /conversions
get_conversionGet a conversionid (UUID, required)GET /conversions/{id}
lookup_clicksLook up clicksclick_id; or gclid / gbraid / wbraid with from–to (≤ 90 days); or a range for the raw log; limit (1–1000)GET /clicks…
tracking_linkGenerate a tracking linkoffer (required), affiliate, type (affiliate | transparent), sub1, sub2, paramsGET /tracking-link

params is an object of extra REST query parameters (string values) for anything the tool does not list, for example {"filters": "country:in:US|CA"} on run_report or {"sub3": "x"} on tracking_link. Arrays such as group_by are sent comma-separated.

Tool results contain the REST response twice: as structuredContent (JSON) and as one text block. Errors come back as a tool result with isError: true and text such as invalid_parameter: … — the REST error codes from Rate limits & errors. Money is returned as decimal strings in the workspace currency unless noted.

Protocol details#

Send JSON-RPC 2.0 messages with POST. A batch (JSON array) may hold up to 20 messages; the body may be at most 1 MB.

Shell
curl -s https://app.trackcrown.com/api/mcp \
  -H "Authorization: Bearer $ATK" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"run_report","arguments":{"preset":"yesterday","group_by":["offer"],"metrics":["clicks","conversions","profit"],"sort":"-profit","limit":5}}}'
MethodAnswer
initializeProtocol version (yours if supported, else 2025-06-18), capabilities.tools, server info named after your workspace's brand (name = the brand's slug, title TrackCrown tracking data (read-only)) and instructions naming your workspace.
tools/listThe ten tools with JSON schemas; every tool is annotated readOnlyHint: true.
tools/call{content, structuredContent, isError}.
ping{}.
notifications (no id)No reply; a request with only notifications answers 202 with an empty body.

HTTP-level errors:

StatusWhen
401 / 403 / 429Key missing or invalid, IP not allowed or account inactive, rate limit — as a JSON-RPC error (code -32001) with the message.
400Body is not JSON (-32700 Parse error).
413Body larger than 1 MB.
405GET or DELETE — the server does not open SSE streams.

JSON-RPC errors in a 200 answer: -32600 invalid request, -32601 unknown method, -32602 unknown tool.

In-panel assistant#

Staff can also ask questions in Assistant (/app/assistant), which uses the same read-only tools with the signed-in user's role. It is available when the platform has an AI provider key configured.

See also: API overview · Authentication & API keys.

Something unclear or missing in this article?Tell us