API reference

MCP server

Connect Claude, Cursor and other AI assistants to Metrixed with the Model Context Protocol, for staff, partners and advertisers.

Metrixed ships a Model Context Protocol server, so an AI assistant can run reports, look up offers and conversions, check caps and billing, and (with write scopes) approve applications, pause offers or create tracking links. It serves three audiences from one endpoint:

The audience is decided by the credential, not by the client. The full tool list per audience is on the MCP tool reference page, generated from the server.

Endpoint

The endpoint is /v1/mcp on the same address you use for your portal, for example https://partners.example.com/v1/mcp for the partner portal or https://app.example.com/v1/mcp for the admin console. Each portal shows its own endpoint under AI & MCP (admin: Settings → AI & MCP; partner and advertiser portals: AI & MCP in the account menu).

• Transport: MCP Streamable HTTP, stateless, JSON responses (POST only; GET returns 405, there is no server-initiated stream).
• Local clients that only speak stdio can use the dtrackier-mcp bridge (below).
• Every response carries permissive CORS headers: the endpoint accepts bearer tokens only, never cookies.

Connect Claude (OAuth)

Claude.ai, Claude Desktop and Claude Code can connect without copying a token:

1. In Claude, open Settings → Connectors → Add custom connector and paste the endpoint.
2. Claude discovers the authorization server, registers itself and opens a consent page on your portal. Sign in if asked.
3. Pick the scopes to grant (your role caps what you can grant) and click Allow.

The grant appears as an MCP token named OAuth: <client> on the AI & MCP page, where you can revoke it. Access tokens last one hour and are refreshed with a rotating refresh token (30 days).

Discovery follows the MCP authorization spec: a 401 from /v1/mcp carries WWW-Authenticate: Bearer resource_metadata="…/v1/mcp/.well-known/oauth-protected-resource"; that document names the authorization server …/v1/mcp/oauth, whose metadata is served at …/v1/mcp/oauth/.well-known/oauth-authorization-server, at the OIDC location …/v1/mcp/oauth/.well-known/openid-configuration and at the root path-insertion locations (/.well-known/oauth-authorization-server/v1/mcp/oauth, /.well-known/oauth-protected-resource/v1/mcp). Clients register with dynamic client registration (POST /v1/mcp/oauth/register, public clients only), use authorization code with PKCE S256 (mandatory) and exchange the code at POST /v1/mcp/oauth/token.

Connect with a token

Create a token under AI & MCP → MCP tokens: give it a name, tick the scopes and pick an expiry (7 to 365 days). The token (dtm_…) is shown once. The page fills it into ready-to-paste configurations:

Claude Code:

claude mcp add --transport http dtrackier https://app.example.com/v1/mcp \
  --header "Authorization: Bearer dtm_…"

Cursor (~/.cursor/mcp.json):

{ "mcpServers": { "metrixed": { "url": "https://app.example.com/v1/mcp", "headers": { "Authorization": "Bearer dtm_…" } } } }

Claude Desktop (claude_desktop_config.json, through mcp-remote):

{ "mcpServers": { "metrixed": { "command": "npx", "args": ["-y", "mcp-remote", "https://app.example.com/v1/mcp", "--header", "Authorization:${AUTH_HEADER}"], "env": { "AUTH_HEADER": "Bearer dtm_…" } } } }

stdio bridge

dtrackier-mcp (built from services/api/cmd/dtrackier-mcp) speaks MCP over stdio and relays every message to the HTTP endpoint, for clients that only start local servers:

{ "mcpServers": { "metrixed": { "command": "dtrackier-mcp", "env": { "DT_MCP_URL": "https://app.example.com/v1/mcp", "DT_MCP_TOKEN": "dtm_…" } } } }

Scopes

Tokens carry tool-group scopes; a tool is listed and callable only when the token has its scope (a :write scope includes the matching :read).

You can only grant what your own role allows: a staff viewer cannot grant offers:write, a partner viewer cannot grant links:write, an advertiser member needs the API keys permission to create tokens at all.

How tools behave

• Your identity, your current role. A token acts as the person who created (or approved) it, with that person's role at the time of each call. Demote them and the token loses those rights; remove or disable them and the token stops working.
• Same data as the portal. Every tool runs the portal's own API route, so masking, filters and permissions are exactly those of the portal. On top of that, the MCP layer removes revenue, profit and margin from partner results and payout, profit and margin from advertiser results.
• Destructive tools ask first. set_offer_status, decide_partner_application, set_conversion_status and dispute_conversion refuse to act unless called with confirm: true; assistants are told to ask you before repeating the call.
• Typed and paged. Tools publish JSON schemas for their input and output, annotations (read-only, destructive, idempotent), return structured results, page lists with page / next_page and log searches with cursor / next_cursor, and answer validation problems with a clear error the model can fix.
• run_report is the report builder query: from, to, dimensions, metrics, filters, compare (previous_period, previous_year), sort, limit, cursor, currency, timezone. Rows come back as objects keyed by column, with totals and the currency; the numbers are those of POST /v1/reports/query (or the partner / advertiser report routes).

Resources: metrixed://reports/catalog (the report catalogue) and metrixed://offers/{id} (one offer). Prompts: weekly performance review, why did a metric drop, find fraud (network) and partner earnings summary.

Actions in the in-app assistant

The assistant inside the portals (Ask AI, ⌘J) uses the same tool layer, including the write tools: pause or resume an offer, approve or reject a conversion or a partner application, create a tracking link and (admin) create an offer; partners can apply to offers and test postbacks, advertisers can dispute conversions. A write tool never runs when the assistant calls it. It shows a confirmation card with exactly what will happen; nothing changes until you press Confirm, which runs the action as you, through the same API route the portal uses, so your role, the account-manager restriction and portal masks apply. Cancel discards it, and an unconfirmed action expires after an hour.

Only the write tools your role could use are offered at all (a viewer gets none). Proposals, confirmations, cancellations and results are written to the audit log (assistant.action_proposed, assistant.action_executed, assistant.action_failed, assistant.action_cancelled); GET /assistant/actions lists your own, POST /assistant/actions/{id}/confirm and /cancel decide one.

Limits, audit and security

• Rate limit: 120 requests per minute per token by default (DT_MCP_RATE_PER_MINUTE); beyond it the endpoint answers 429 with Retry-After.
• Audit: every tool call is written to the audit log (mcp.call: token, tool, argument summary, result size, status, duration). The AI & MCP page shows calls per tool, per token and the latest calls; staff see the full trail in the audit log. Changes made by a tool appear under the actor MCP: <token name> (<email>).
• Tokens: stored as SHA-256 hashes, shown once, always expire (at most 365 days), revocable at any time; staff with the API keys permission see and revoke every MCP token of the workspace.
• Only at /v1/mcp: MCP tokens are refused by the REST API, and API keys and session cookies are refused by the MCP endpoint.
• No minting from borrowed sessions: API keys, MCP tokens and "view as partner" (impersonated) sessions cannot create tokens or approve OAuth connections.
• Public URL: set DT_MCP_PUBLIC_URL when the API sits behind a proxy that does not forward X-Forwarded-Host, so the metadata advertises the right origin.