MCP server

Server URL#

The server speaks Streamable HTTP and is read-only. It is available on every Origin plan.

https://mcp.originattribution.com/mcp

Every tool returns data for the one store the connected credential belongs to. No other store can be queried.

Authentication#

Access is through an Origin API key, created in the Origin app under Settings → Connect your AI (or Settings → API keys). Keys start with org_, are shown once on creation, and a store can hold up to 10 active keys. Revoking a key in Origin cuts off every client using it on its next request.

There are two ways to present the key, depending on the client:

Bearer key

Clients that let you set headers (Claude Code, Cursor, scripts and agents you build yourself) pass the key directly:

Authorization: Bearer org_...

OAuth 2.1

Hosted assistants (claude.ai, ChatGPT) connect through OAuth 2.1 with dynamic client registration. When you connect, Origin’s consent page opens; paste your API key and approve. The assistant then holds a token tied to that key. Discovery metadata is published at the standard locations:

https://mcp.originattribution.com/.well-known/oauth-authorization-server
https://mcp.originattribution.com/.well-known/oauth-protected-resource/mcp

Connecting a client#

Claude Code

claude mcp add --transport http origin https://mcp.originattribution.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Then run /mcp inside Claude Code. Origin should show as connected with its tools listed.

Cursor

Add this to .cursor/mcp.json in your project, or as a global server under Cursor Settings → MCP:

{
  "mcpServers": {
    "origin": {
      "url": "https://mcp.originattribution.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

claude.ai

Open Settings → Connectors, click Add custom connector, name it Origin and paste the server URL. Click Connect, paste your API key on the consent page and approve. Switch Origin on from the + menu in a chat.

ChatGPT

Requires a paid plan with Developer mode enabled under Settings → Apps & Connectors → Advanced settings. Click Create, name it Origin, set authentication to OAuth and paste the server URL. Approve with your API key when the consent page opens.

How tools respond#

Every tool returns plain JSON, both as structuredContent and as a single text block, so clients that ignore structured output still receive every field. Rows carry the same column names as the corresponding Origin table or page, unrounded.

Every response includes the store’s currency. Time-windowed responses include date_from and date_to (calendar days ending today, in the store’s timezone), and attributed responses include the model version used, e.g. LT_30D. Rates such as conversion_rate, ctr and profit_margin are fractions between 0 and 1, not percentages.

Attribution parameters

Every attributed tool accepts these two optional inputs. Without them a call uses last-touch attribution over a 30-day window, the Origin dashboard’s default. How each model assigns credit is described in Attribution models.

Tools#

Fourteen read-only tools. Call get_shop_overviewfirst for the store’s currency, timezone, connected ad platforms and how far back its attribution data goes.

get_shop_overview

Grounding context for the connected store. No inputs.

{
  "shop": "example.myshopify.com",
  "name": "Example Store",
  "currency": "USD",
  "timezone": "America/New_York",
  "attribution_defaults": {
    "model": "LAST_TOUCH",
    "window_days": 30,
    "model_version": "LT_30D"
  },
  "connected_ad_platforms": [
    {
      "platform": "meta",
      "status": "OK",
      "syncing": false,
      "last_synced_at": "2026-09-18T06:12:40.000Z"
    }
  ],
  "attribution_data_since": "2025-03-14"
}

get_store_metrics

The store-wide metrics at the top of the Origin dashboard: orders, revenue, sessions, conversion rate and AOV, tracked revenue, blended marketing spend, blended CAC, MER, and the repeat-purchase summary. These are whole-store totals, so this tool takes no attribution parameters. Sessions exclude traffic Origin identifies as bots (crawlers, link previewers and headless browsers, by user agent), and the conversion rate is computed over those sessions.

get_channels

Every marketing channel (Paid Social, Paid Search, Organic Search, Email, Direct, ...) with the full metrics of the Origin channels table. Unclassified traffic is excluded, as in the app.

get_top_utm_sets

The top performing UTM sets (full combinations of utm_source, utm_medium, utm_campaign, utm_content and utm_term) with every column of the Origin UTM sets table, including reorder rates and CAC payback.

get_top_utm_parameters

The best performing values of each of the five UTM parameters independently, ranked by attributed revenue, as shown on the dashboard’s top-values cards. The top 5 per parameter, plus how many distinct values exist.

get_utm_set_metrics

Full performance metrics for one exact UTM combination, as shown on its Origin UTM set page. Omitted parameters are treated as empty.

get_utm_parameter_metrics

Full performance metrics for a single UTM parameter value across all sets that carry it, e.g. all traffic where utm_source is facebook.

get_top_ads

The best performing ad campaigns, ad sets or individual ads with every column of the Origin ads tables. Each item carries its numeric id for get_ad_metrics.

get_ad_metrics

Full performance metrics for one ad campaign, ad set or ad, as shown on its Origin page, including platform-reported metrics. An ID that does not belong to the store is an error.

get_top_ad_platforms

Paid performance broken down by ad platform (Meta, Google, TikTok, ...) plus the totals across platforms: the dashboard’s “Performance by ad platform” table.

get_order_touchpoints

The order (name, date, amount, status, customer) and, oldest first, every marketing visit Origin credits it to, each with its timestamp, landing page and traffic source: a paid ad (with platform, ad set and campaign), a UTM-tagged link, or a plain link. Journey tools take no attribution parameters.

get_order_customer_events

The customer journey behind an order: every storefront session and event (page views, product views, add to carts, checkout steps) of the browser that placed it, up to the moment it was placed, newest first. This is the order page’s timeline in Origin. Orders placed before the Origin pixel was installed have no journey.

get_customer_touchpoints

The customer (Shopify ID, name, their orders) and, newest first, every marketing visit Origin credited to any of their orders. This is the “Touches” card on the customer page in Origin.

get_customer_events

The full journey of a customer across the browsers behind their orders, newest first, with each converting session’s checkout marked. This is the “Customer journey” on the customer page in Origin.

Limits and errors#

Each API key may make 60 calls per minute, shared between MCP tool calls and the REST API. Over the limit, a tool call returns an error asking the client to retry in a moment.

Errors are returned as MCP tool errors with a short, human-readable message, never a stack trace:

invalid input        Input validation error: Invalid arguments for tool get_top_utm_sets: ...
rate limited         Rate limit exceeded, retry in a moment.
window not on plan   A 365-day attribution window is not available on this store's plan. Available windows: 1, 7, 14, 30 days.
subscription         This store's Origin subscription is inactive. Reactivate it in the Origin app to query its data.
not found            No order named #1234 was found for this store.
analytics outage     Origin's analytics service could not answer this query. Please try again in a moment.