--- url: /mcp.md description: >- How to use the Model Context Protocol (MCP) to interact with the Stampix Business Platform. --- # MCP (Model Context Protocol) The Stampix MCP server lets AI assistants — such as **Claude** — query and manage dashboard data on your behalf. Every tool call runs with **your permissions**: you only see organizations and data you are allowed to access in the dashboard. ::: warning Internal documentation This page is for the **Stampix internal team** (account managers, customer support, developers). Client users do not have MCP access. ::: ## Getting access ### MCP permissions MCP access is gated by two special scopes: | Scope | Purpose | | ----------- | ------------------------------------------------------------------------------------------------- | | `read:mcp` | Required for **all** tools (read and write) | | `write:mcp` | Required for **write** tools (`create_organization`, `create_campaign`, `campaign_product_setup`) | These scopes are **not** included in the Read-Only dashboard role. Super Admin and Account Manager receive them automatically. Read-Only Super Admin receives `read:mcp` and the domain read scopes, and does not receive `write:mcp`. Other roles need MCP scopes assigned manually in Auth0. In addition to MCP scopes, each tool requires the same **domain permissions** you would need in the dashboard UI (for example `read:campaigns` or `read:billing`). ### Role cheat sheet | Role | MCP access by default | | --------------------- | ------------------------------------------------- | | Super Admin | All scopes, including MCP | | Read-Only Super Admin | Read scopes, including `read:mcp`. No `write:mcp` | | Account Manager | All scopes, including MCP | | Customer Support | Limited — MCP must be granted manually | | Read-Only | No access | ### Connecting Claude.ai **Claude MCP must be set up by a developer.** Contact **Jaro** or **Casper** before connecting. They will: 1. Confirm your Auth0 user has `read:mcp` (and `write:mcp` if you need write tools) 2. Ensure your role includes the domain permissions you need (e.g. `read:campaigns`, `read:billing`) 3. Help you add the Stampix MCP server in Claude (remote MCP via OAuth) Once set up, add the MCP URL in Claude or Cursor and complete the OAuth login flow. The connector URL must match the advertised protected resource (`…/api/mcp`), not the Auth0 API identifier. `dashboard.b2b.stampix.com` is a redirect alias — do not use it. * Production: `https://dashboard.stampix.com/api/mcp` * Staging: `https://dashboard.qa.b2b.stampix.com/api/mcp` The server speaks **Streamable HTTP** (MCP protocol **2026-07-28**, with a **2025** fallback for older clients). SSE transport is not supported. ### Staging smoke checklist (before production) Validate against `https://dashboard.qa.b2b.stampix.com/api/mcp` after deploying the dashboard staging build: 1. Connect Claude remote MCP and complete OAuth 2. Confirm `tools/list` shows the expected tools 3. Call `user` and one org-scoped read tool 4. Confirm a missing-scope call fails cleanly 5. Optional: one write tool against a known QA org 6. Watch Sentry tags `stampix.mcp.error` after promoting to production ### Scopes explained Every tool enforces a two-layer permission model: 1. **MCP gateway scopes** — `read:mcp` is always required; write tools also require `write:mcp` 2. **Domain scopes** — the same permissions as the dashboard (e.g. `read:campaigns`, `write:campaigns`) If a tool returns **"Missing required scopes"**, ask Jaro or Casper to add the missing permission to your Auth0 user. `list_recent_logins` also requires a Super Admin, Read-Only Super Admin or Account Manager role. The result is global: every non-Stampix login and pending invitation, including organizations the caller is not assigned to. Other roles with `read:mcp` are not allowed to use this tool. ## Read tools These tools are read-only and safe to use for analysis and reporting. ### Tool reference | Tool | Required scopes | Inputs | | ------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `user` | `read:mcp` | — | | `list_user_organizations` | `read:mcp`, `read:organization` | — | | `list_organization_webapps` | `read:mcp`, `read:campaigns` | `organizationId` | | `get_client_invoice_statements` | `read:mcp`, `read:billing` | `organizationId` | | `get_client_report` | `read:mcp`, `read:billing` | `organizationId` | | `list_product_catalog` | `read:mcp` | — | | `get_organization_onboarding_status` | `read:mcp` | `organizationId` | | `list_organization_content` | `read:mcp` | `organizationId` | | `list_organization_branding` | `read:mcp`, `read:campaigns` | `organizationId` | | `list_schemas` | `read:mcp` | — | | `get_schema` | `read:mcp` | `schemaName` | | `list_organization_campaigns` | `read:mcp`, `read:campaigns` | `organizationId` | | `list_organization_theme_sets` | `read:mcp`, `read:campaigns` | `organizationId` | | `get_webapp_google_analytics_report` | `read:mcp`, `read:campaigns` | `webappId`, optional `funnelType`, `startDate`, `endDate`, `breakdownDimension` | | `get_organization_campaign_performance` | `read:mcp`, `read:campaigns` | `organizationId` | | `get_campaign_monthly_order_count` | `read:mcp`, `read:campaigns` | `campaignId` | | `get_campaign_funnel` | `read:mcp`, `read:campaigns` | `campaignId`, optional `startDate`, `endDate`, `groupBy`, `breakdown` | | `get_organization_campaign_optin_breakdown` | `read:mcp`, `read:campaigns` | `organizationId`, optional `startDate`, `endDate` | | `get_campaign_feedback_breakdown` | `read:mcp`, `read:campaigns` | `campaignId`, optional `year` | | `get_organization_feedback_breakdown` | `read:mcp`, `read:campaigns` | `organizationId`, optional `year` | | `get_campaign_survey_answers` | `read:mcp`, `read:campaigns` | `campaignId`, optional `startDate`, `endDate` | | `list_recent_logins` | `read:mcp`. Super Admin, Read-Only Super Admin or Account Manager | `window`: `7d`, `30d`, or `max` | ### `get_campaign_funnel` counts * The result is a flat array: one zero-filled total row per period (`language: null`) and, with `breakdown: language`, one row per order language after it. Code activations have no order language, so `codesActivated` is null on language rows. Demo, test-code and discarded orders are excluded. * Each step counts orders that reached at least that step: its own data or data of any later step, so a field cleared afterwards still counts. The step order follows the webapp's **current** flow, not the flow an order was placed in. * Orders are bucketed (UTC) on the day they were started. An order started in October and completed in November counts in October, so `ordersCompleted` differs from completed-order counts by completion date. * Anonymized orders are recognised by their photo count and kept postal code. Orders anonymized before the anonymization fix got a placeholder email even when none was entered, so their email only counts for `personalDetails` itself. That is why `personalDetails` can be higher than the step before it. * Generic codes are never marked activated, so `codesActivated` is 0 for them and `ordersStarted` is the top of the funnel. * `customersCompleted` (after `ordersCompleted`) counts unique customers with a completed order, by normalized email. A customer who orders in two languages counts once in the total row and once in each language row. It is only roughly comparable to unique visitors in GA. Completed orders are anonymized after 183 days and each gets a unique placeholder email, so for older periods `customersCompleted` approaches `ordersCompleted`. ### `get_webapp_google_analytics_report` breakdown * With `breakdownDimension`, GA4 returns up to 15 distinct values of that dimension plus a total row per step with `RESERVED_TOTAL` as the dimension value. Don't add the total to the value rows. ### Example prompts Copy and adapt these prompts when talking to your AI assistant: | Tool | Example prompt | | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `user` | Who am I logged in as on Stampix? | | `list_user_organizations` | List all organizations I have access to. | | `list_organization_webapps` | List webapps for organization `{orgId}`. | | `get_client_invoice_statements` | Show invoice statements for `{orgName}` this year. | | `get_client_report` | Give me the client budget report for `{orgName}` for the current year. | | `list_product_catalog` | What products are available in the Stampix catalog? | | `get_organization_onboarding_status` | What is the onboarding checklist status for `{orgName}`? | | `list_organization_content` | List all content profiles for organization `{orgId}`. | | `list_organization_branding` | List branding/themes for organization `{orgId}`. | | `list_schemas` | What JSON schemas are available via MCP? | | `get_schema` | Show me the `webappTheme` schema so I can understand theme fields. | | `list_organization_campaigns` | List campaigns for `{orgName}` with their webapp and country settings. | | `list_organization_theme_sets` | List theme sets (artwork) for `{orgName}`. | | `get_webapp_google_analytics_report` | GA funnel for webapp `{webappId}` last month split by channel. | | `get_organization_campaign_performance` | How are campaigns performing for `{orgName}` this year? | | `get_campaign_monthly_order_count` | Completed orders per month this year for campaign `{campaignId}`. | | `get_campaign_funnel` | Where do people drop off in campaign `{campaignId}`? Show the funnel per week since 1 September, split by language. | | `get_organization_campaign_optin_breakdown` | Opt-in breakdown by campaign and country for `{orgName}` in March 2026. | | `get_campaign_feedback_breakdown` | NPS/star feedback breakdown for campaign `{campaignId}` this year. | | `get_organization_feedback_breakdown` | NPS/star feedback breakdown for `{orgName}` this year. | | `get_campaign_survey_answers` | Survey (data questions) results for campaign `{campaignId}` in March. | | `list_recent_logins` | Which non-Stampix users logged in during the last 7 days, which organizations they can access, and whether they accepted their invite? | ## Write tools ::: warning Destructive tools Write tools create real data in the dashboard. Use with care and only if you have `write:mcp` plus the required domain scope. ::: | Tool | Required scopes | Purpose | | ------------------------ | ---------------------------------------------- | --------------------------------------------------- | | `create_organization` | `read:mcp`, `write:mcp`, `create:organization` | Create a new organization (name, currency, contact) | | `create_campaign` | `read:mcp`, `write:mcp`, `write:campaigns` | Create a campaign and webapp (new or link existing) | | `campaign_product_setup` | `read:mcp`, `write:mcp`, `write:campaigns` | Link products to a campaign and theme set | ## Recommended workflows ### New client onboarding workflow Typical sequence for onboarding a new client via MCP: 1. **`create_organization`** — returns the new `organizationId` 2. **`create_campaign`** — use `webapp.mode: "create"` for new clients (creates branding, content, and webapp with Stampix defaults) 3. **`list_organization_campaigns`** + **`list_organization_theme_sets`** + **`list_product_catalog`** — gather IDs for the next step 4. **`campaign_product_setup`** — link products to the campaign and theme set ### Client health check Use this when reviewing how a client is doing: 1. "List all organizations I have access to." 2. "What is the onboarding checklist status for `{orgName}`?" 3. "How are campaigns performing for `{orgName}` this year?" 4. "Completed orders per month this year for campaign `{campaignId}`." ### Billing review 1. "List all organizations I have access to." 2. "Show invoice statements for `{orgName}` this year." 3. "Give me the client budget report for `{orgName}` for the current year." ### Campaign and webapp analysis 1. "List campaigns for `{orgName}` with their webapp and country settings." 2. "List webapps for organization `{orgId}`." 3. "Show the GA funnel for webapp `{webappId}` for the last 30 days." 4. "GA funnel for webapp `{webappId}` last month split by channel." 5. "Opt-in breakdown by campaign and country for `{orgName}` in the last month." 6. "Survey answer counts for campaign `{campaignId}` between 2026-03-01 and 2026-03-31." ## Troubleshooting | Symptom | Likely cause | Fix | | ----------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- | | MCP server won't connect (Claude) | Not set up by a developer | Contact Jaro or Casper | | "Missing required scopes" | Token lacks `read:mcp`, `write:mcp`, or a domain scope | Request a permission update in Auth0 | | "Organization not found" | Wrong ID or no access to that org | Run `list_user_organizations` | | "Campaign not found" | Wrong campaign ID or org mismatch | Run `list_organization_campaigns` for the org | | "No survey linked to this campaign" | Campaign has no data-questions survey assigned | Assign a survey in the campaign, or pick a campaign with `surveyId` | | Tool not visible in client | Client hasn't refreshed tools after connecting | Refresh tools list in "Customize" Claude Settings | | Empty or unexpected data | Date range defaults may not match your intent | Specify `startDate` and `endDate` explicitly (format: `yyyy-MM-dd`) |