--- 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. Other roles need them 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 | | 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. ## 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` | | `get_organization_campaign_performance` | `read:mcp`, `read:campaigns` | `organizationId` | | `get_campaign_daily_order_count` | `read:mcp`, `read:campaigns` | `campaignId`, optional `startDate`, `endDate` | | `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` | ### 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` | Show the GA funnel for webapp `{webappId}` for the last 30 days. | | `get_organization_campaign_performance` | How are campaigns performing for `{orgName}` this year? | | `get_campaign_daily_order_count` | Daily order counts for campaign `{campaignId}` over the last 7 days. | | `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. | ## 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. "Daily order counts for campaign `{campaignId}` over the last 7 days." ### 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. "Opt-in breakdown by campaign and country for `{orgName}` in the last month." 5. "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`) |