MCP Server

Every Allegro tenant exposes a Model Context Protocol (MCP) server at https://acme.allegrocdp.com/mcp, on the tenant's platform subdomain. Custom domains and per-property hostnames don't serve MCP. This lets AI clients — Claude Desktop, Cursor, custom agents, or any MCP-compatible tool — interact with your audience data, templates, and products through a structured, authenticated interface.

Authentication

The MCP server accepts two kinds of credentials:

Credential	Best for	Acts as
OAuth	AI clients such as Claude, Cursor, and VS Code used by a person	The person who signed in
API key	Scripts, servers, and agents without a person signing in	The organization that owns the key

For OAuth, add the MCP URL to your client and sign in when it asks. There is no key to paste. See Connecting an MCP client with OAuth.

An API key authenticates the same way as the REST API. Include it as a Bearer header on every request:

Authorization: Bearer <your-token>

The key must grant read access (*:read) or full access (*). A key limited to individual resource scopes (for example products:read or events:write) is rejected with a 403 Forbidden — MCP tools read across every resource, so a narrowly-scoped key can't be used here. Write tools and admin reads still require a full-access (*) key on top of this, as described under Permissions.

A token or key from one tenant cannot be used against a different tenant's MCP endpoint — the server checks the tenant on every request.

Connecting a Client

Claude Desktop / Cursor / MCP Inspector

To use an API key, add the following entry to your client's MCP server configuration, replacing acme and <your-token> with your actual values:

{
    "mcpServers": {
        "allegro": {
            "url": "https://acme.allegrocdp.com/mcp",
            "headers": {
                "Authorization": "Bearer <your-token>"
            }
        }
    }
}

Opening the URL in a browser

The /mcp URL is meant for AI assistants, not browsers, but opening it in a browser while signed in to the dashboard shows a Connect your assistant page with copy-paste setup instructions for the common clients. An MCP client that requests the URL directly still gets the transport responses it expects, so the page never interferes with a real connection.

Finding and Calling Tools

The server lists two tools, no matter how many tenant tools exist:

Tool	Input	Returns
`search_tools`	`query` (search terms; empty browses the catalog), `limit` (1–50, default 10)	Matching tools with their exact names, descriptions, and full input schemas
`execute_tools`	`calls`: up to 10 `{ "name": "<tool>", "arguments": { ... } }` objects	Each call's result, in order

Search for what you want to do, then call the tool by the exact name the search returned:

{ "query": "export purchases", "limit": 3 }

{
    "calls": [
        {
            "name": "create-export-tool",
            "arguments": {
                "type": "purchases",
                "filters": { "status": "completed" }
            }
        }
    ]
}

Calls in one execute_tools request run one after another and stop at the first error. Each call is checked on its own, so a write in the batch still needs the admin role. A response is capped at 64 KB.

Available Tools

Tools marked admin below require the admin role even to read, because they expose access control, delivery, or export data. Every write tool requires the admin role.

Area	Read	Write
Audience members	`search-audience-members-tool`, `get-audience-member-tool`, `list-audience-member-events-tool`, `get-audience-member-attributes-tool`	`create-audience-member-tool`, `update-audience-member-tool`, `delete-audience-member-tool`, `trigger-audience-member-sync-tool`, `set-audience-member-attribute-tool`
Entitlements and purchases	`list-purchases-tool`, `get-purchase-tool`	`grant-entitlement-tool`, `revoke-entitlement-tool`, `refund-purchase-tool`
Catalog	`list-products-tool`, `get-product-tool`, `list-plans-tool`, `get-plan-tool`, `list-offers-tool`, `get-offer-tool`, `list-plan-fields-tool`	`create-product-tool`, `update-product-tool`, `delete-product-tool`, `create-plan-tool`, `update-plan-tool`, `delete-plan-tool`, `create-offer-tool`, `update-offer-tool`, `delete-offer-tool`, `create-plan-field-tool`, `update-plan-field-tool`, `delete-plan-field-tool`
Forms	`list-forms-tool`, `get-form-tool`	`create-form-tool`, `update-form-tool`, `delete-form-tool`
Templates	`list-templates-tool`, `get-template-tool`, `list-template-revisions-tool`, `get-template-revision-tool`, `list-template-library-tool`	`create-template-tool`, `update-template-tool`, `duplicate-template-tool`, `delete-template-tool`, `restore-template-tool`, `restore-template-revision-tool`, `import-template-from-library-tool`
Email	`list-email-templates-tool`, `get-email-template-tool`, `list-email-template-revisions-tool`	`update-email-template-tool`, `reset-email-template-tool`, `restore-email-template-revision-tool`, `send-test-email-tool`
Recommendations	`list-recommendation-engines-tool`, `serve-recommendations-tool`, `preview-recommendations-tool`	`update-recommendation-engine-tool`, `delete-recommendation-engine-tool`
Branding and embed snippet	`get-branding-tool`, `list-branding-revisions-tool`, `get-embed-snippet-tool`, `list-embed-snippet-revisions-tool`	`update-branding-tool`, `rollback-branding-tool`, `update-embed-snippet-tool`, `rollback-embed-snippet-tool`
Properties	`list-properties-tool`, `get-property-tool`, `get-property-domain-health-tool` (admin)	`create-property-tool`, `update-property-tool`, `delete-property-tool`, `update-property-settings-tool`
Webhooks	`list-webhooks-tool` (admin), `get-webhook-tool` (admin), `list-webhook-deliveries-tool` (admin), `get-webhook-delivery-tool` (admin)	`create-webhook-tool`, `update-webhook-tool`, `delete-webhook-tool`, `ping-webhook-tool`, `retry-webhook-delivery-tool`, `regenerate-webhook-secret-tool`
User attributes	`list-user-attributes-tool`, `test-user-attribute-validation-tool`	`create-user-attribute-tool`, `update-user-attribute-tool`, `delete-user-attribute-tool`, `sync-user-attribute-tool`
Analytics	`get-analytics-schema-tool`, `get-analytics-realtime-tool`, `get-analytics-view-tool`, `query-analytics-tool`, `list-analytics-events-tool`, `get-content-analytics-tool`, `get-reader-analytics-tool`, `list-analytics-reports-tool`, `get-analytics-report-tool`, `list-analytics-report-subscriptions-tool`	`create-analytics-report-tool`, `update-analytics-report-tool`, `delete-analytics-report-tool`, `subscribe-analytics-report-tool`, `unsubscribe-analytics-report-tool`
Settings and operations	`get-settings-tool`, `get-dashboard-stats-tool`, `list-exports-tool`, `get-export-download-url-tool` (admin), `list-activity-log-tool` (admin)	`update-settings-tool`, `trigger-github-sync-tool`, `create-export-tool`
Interactions	`get-targeting-catalog-tool`, `get-component-attributes-tool`, `list-interactions-tool`, `get-interaction-tool`, `list-interaction-revisions-tool`, `get-interaction-revision-tool`, `get-interaction-report-tool`, `project-interaction-reach-tool`, `simulate-interaction-tool`, `get-interaction-preview-url-tool`	`create-interaction-tool`, `update-interaction-tool`, `duplicate-interaction-tool`, `unpublish-interaction-tool`, `delete-interaction-tool`, `restore-interaction-tool`, `force-delete-interaction-tool`, `restore-interaction-revision-tool`, `scan-page-selectors-tool`
Cohorts and meters	`list-cohorts-tool`, `get-cohort-tool`, `list-cohort-revisions-tool`, `get-cohort-revision-tool`, `list-meters-tool`	`create-cohort-tool`, `update-cohort-tool`, `delete-cohort-tool`, `restore-cohort-revision-tool`, `create-meter-tool`, `update-meter-tool`, `delete-meter-tool`
Segments	`list-segments-tool`, `get-segment-tool`, `sample-segment-members-tool`, `preview-segment-tool`	`create-segment-tool`, `update-segment-tool`, `duplicate-segment-tool`, `delete-segment-tool`
A/B tests	`list-experiments-tool`, `get-experiment-tool`, `get-experiment-results-tool`	`create-experiment-tool`, `update-experiment-tool`, `delete-experiment-tool`, `start-experiment-tool`, `end-experiment-tool`, `roll-out-experiment-variant-tool`
Access	`list-tenant-users-tool` (admin), `list-api-keys-tool` (admin)	`invite-tenant-user-tool`, `update-tenant-user-role-tool`, `remove-tenant-user-tool`, `resend-invitation-tool`
OAuth clients	`list-o-auth-clients-tool` (admin), `get-oauth-client-tool` (admin)	`create-oauth-client-tool`, `update-oauth-client-tool`, `regenerate-oauth-client-secret-tool`, `delete-oauth-client-tool`
Geo, GitHub, and content	`list-content-tool`, `get-geo-provider-settings-tool` (admin), `get-github-sync-log-tool` (admin), `list-github-repositories-tool` (admin)	`update-geo-provider-settings-tool`

search_tools returns each tool's description and input schema, so it is the reference for arguments. The analytics tools are covered in Analytics API and MCP.

The report-subscription tools — subscribe-analytics-report-tool and unsubscribe-analytics-report-tool — are the one exception to the admin-only rule for writes stated above and under Permissions. They follow the report's own access instead: anyone who can view a report may subscribe or unsubscribe their own address, and members and admins may manage other addresses. A write-access connection (OAuth with write access, or a full-access key) is still required.

Delete tools take a required confirm boolean. Without confirm: true they return an error naming what would be deleted and change nothing. delete-template-tool archives a template, and restore-template-tool brings it back. Permanent deletion stays in the dashboard.

note

GitHub-synced templates are read-only and cannot be modified through the MCP server.

Integration tools

These tools only appear in search_tools while their package is enabled for the tenant. Every one of them except get-property-edge-settings-tool requires the admin role. Connecting or disconnecting a Cloudflare, Fundraise Up, or SFMC account stays in the dashboard, and credentials are never returned.

Package	Read	Write
Allegro Edge	`get-edge-settings-tool` (admin), `get-property-edge-settings-tool`	`update-edge-settings-tool`, `update-property-edge-settings-tool`, `deploy-property-edge-tool`, `rollback-property-edge-tool`
Fundraise Up		`sync-fundraise-up-tool`
Marketing Cloud		`update-sfmc-settings-tool`, `update-property-sfmc-settings-tool`, `refresh-sfmc-columns-tool`

deploy-property-edge-tool and rollback-property-edge-tool take a required confirm boolean and queue nothing without confirm: true. sync-fundraise-up-tool shares the dashboard's limit of one sync every 15 minutes per connection. update-sfmc-settings-tool accepts the SFMC client id and secret but only reports whether each is set.

Building interactions

The interaction tools give a client the same abilities as the interaction builder in the dashboard: write interactions with their actions and journeys, save reusable cohorts, set up content meters, and run A/B tests. The recommended flow is:

Call get-targeting-catalog-tool to see the attributes, operators, segments, cohorts, meters, A/B tests, products, templates, and saved page areas you can target with.
Call create-interaction-tool or update-interaction-tool to save the interaction as a draft.
Check the audience with project-interaction-reach-tool, which estimates how many visitors the journeys would reach, and simulate-interaction-tool, which runs the journeys against visitor attributes you supply and shows which journey matched and why.
Use get-interaction-preview-url-tool for a 30-minute link that previews the draft on a page of your site.
Publish by calling update-interaction-tool with status set to published. Use unpublish-interaction-tool to take it back to a draft.

scan-page-selectors-tool suggests page areas for a public URL and a short description, and saves the verified ones so you can target them. Edits to interactions and cohorts record a revision, and update-interaction-tool and update-cohort-tool accept a revision_note. Use the revision tools to review history or restore an earlier version.

note

Interaction, cohort, meter, and A/B test writes need the admin role. Writes to an interaction or cohort are refused while someone else is editing it in the dashboard, the same as in the dashboard itself; try again once they finish. The server never takes over or releases a dashboard edit lock.

note

project-interaction-reach-tool, get-interaction-report-tool, and get-experiment-results-tool read from analytics. When analytics isn't configured for your tenant they return available: false with a reason instead of numbers. Reach projections also need the targeting projections feature turned on for your tenant.

`get-audience-member-tool` includes

get-audience-member-tool always returns the member's core profile, including last_seen_at (the ISO 8601 timestamp of their most recent event, or null when they have no events). Pass any of the following in include to expand the response:

Include	Adds
`entitlements`	The member's entitlements.
`purchases`	The member's purchases.
`events`	The member's recent events.
`meta`	The member's stored metadata.
`external_profiles`	Linked external profiles, each with `provider` and the raw `data` synced from that provider.
`foreign_keys`	The member's external identifiers as `key`/`value` pairs.
`sync_status`	Per-provider sync state: `last_synced_at`, `next_run_at`, `cadence`, `max_age_on_login`, and `is_fresh`.
`sessions`	The member's sessions, each with `is_authenticated`, `authenticated_at`, and `created_at`.

`get-settings-tool` sections

get-settings-tool returns tenant configuration grouped into sections so you only fetch what you need. Pass sections to choose which groups to return. When omitted, all lightweight sections are returned. The two heavy sections — preview_css and embed_snippet — are never returned by default and must be requested explicitly.

Section	Returns	In default response
`general`	Tenant `name` and `timezone`	Yes
`web`	`cors_allowed_origins` and `cookie_domain`	Yes
`email`	Email `provider` name and `mail_from_address` / `mail_from_name`	Yes
`auth`	Enabled `login_providers` in display order, plus each provider's configuration status — which fields are set, and non-secret values such as client IDs	Yes
`captcha`	The selected captcha `provider`, whether captcha is `enabled`, and each provider's configuration status and non-secret values	Yes
`branding`	Whether branding is `configured`, the `logo_url`, and the design `tokens` and per-component overrides	Yes
`payments`	The `active` payment provider and the list of `available` providers	Yes
`packages`	The `available` packages and the names of those `enabled`	Yes
`github_sync`	Whether templates sync with GitHub (`enabled`) and the `repository`	Yes
`sign_in_page`	The sign-in page `header_html` and `footer_html` (sanitized)	Yes
`preview_css`	The tenant preview CSS `content`	No (opt in)
`embed_snippet`	The current embed snippet `content` and `updated_at`	No (opt in)

The sections above are the core set. Installed packages may contribute additional sections, so the tool's input schema (its sections enum) is the authoritative list of what's available on a given tenant.

note

Secrets are never returned. The email section excludes the SES key, secret, and region; the auth section returns provider names and non-secret configuration such as client IDs, but never encrypted credentials. Use get-embed-snippet-tool when you need embed snippet revision history.

Writing settings

The update-settings-tool tool changes tenant configuration, mirroring the settings an admin can edit in the dashboard. It takes a section key and a values object, and returns the updated section in the same shape get-settings-tool would — so you can read the result back without a second call.

Only some sections are writable:

Section	Writable fields
`general`	`name`, `timezone`
`web`	`cors_allowed_origins`, `cookie_domain`
`email`	`mail_from_address`, `mail_from_name`
`auth`	`login_providers` — the display order, as a list of provider slugs
`captcha`	`provider` (a provider slug, or `none` to turn captcha off) and `providers` (`{ "recaptcha": { "site_key": "...", "min_score": 0.5 } }`)
`sign_in_page`	`header_html`, `footer_html`
`packages`	`enabled` — the full list of enabled package names, which replaces the current list
`preview_css`	`content`

Each writer runs the same validation rules as the matching admin form and persists the value the same way, so update-settings-tool can't put a tenant into a state the dashboard couldn't. Secrets stay in the dashboard: login provider credentials, the captcha secret key, and SES keys are rejected. A login provider counts as enabled once its credentials are complete, so turning one on also happens in the dashboard. payments, github_sync, and branding have no writer here; use update-branding-tool for branding.

Field names are the ones get-settings-tool returns, which are not always the admin form's labels. An unknown field is rejected with an error listing the accepted fields — so sending organization_name to the general section returns an error naming name rather than silently doing nothing.

note

update-settings-tool requires the admin role, like every other write tool.

Built-in Prompts

The server ships three prompts that instruct the AI on how to complete common workflows:

Prompt	Input	What it does
`summarize-member`	Email address	Fetches the full member profile and writes a summary
`grant-access`	Email + product name	Walks through lookup → check → grant with duplicate protection
`review-templates`	(none)	Lists all templates, groups by status, and flags issues

Permissions

Write tools, and the read tools marked admin above, require the authenticated user to have the admin role on the tenant, or a full-access organization or platform API key. Other read tools are available to all authenticated tenant members. A caller without the admin role gets a tool error ("You do not have admin permission to modify data in this tenant.") instead of the result.

When you sign in with OAuth, the client also needs the write access you can grant on the consent screen; a read-only connection gets an error from every write tool, even for an admin.

A tenant always keeps at least one admin: remove-tenant-user-tool and update-tenant-user-role-tool refuse to remove or demote the last one.

Landlord MCP

In addition to each tenant's own server, the platform exposes a landlord MCP server for managing tenants across the platform, at https://<platform-domain>/mcp. It's the same /mcp path as a tenant server, but on the platform domain instead of a tenant host — tenant hosts continue to reach their own tenant's server as described above.

Platform API Keys

The landlord MCP server accepts a super admin signed in with OAuth, or a platform API key created under Global Settings → API Keys in the landlord admin. Include a key as a Bearer header on every request:

Authorization: Bearer <platform-token>

Organization keys and user-owned API keys are rejected with a 403 Forbidden ("This endpoint requires a platform-owned API key or OAuth sign-in as a super admin."). The platform key must also grant read access (*:read) or full access (*); a platform key scoped to individual resources is rejected with a 403 Forbidden.

Connecting a Client

Add an entry to your client's MCP server configuration, replacing <platform-domain> and <platform-token> with your actual values:

{
    "mcpServers": {
        "allegro-landlord": {
            "url": "https://<platform-domain>/mcp",
            "headers": {
                "Authorization": "Bearer <platform-token>"
            }
        }
    }
}

Landlord Tools

Tool	Input	Returns
`list-tenants`	(none)	`items` — each tenant's `id`, `name`, `slug`, `domain`, and `created_at`, ordered by name — and `count`
`create-tenant`	`name` (required; letters, numbers, spaces, and dashes); `slug` (optional — derived from `name` when omitted, always slugified, minimum 3 characters, unique)	The created tenant's `id`, `name`, `slug`, `domain`, and `created_at`
`search-tenant-tools`	`tenant` (slug, required); `query` (optional — case-insensitive filter on tool name and description)	`items` — each matching tool's `name`, `title`, `description`, `inputSchema`, `outputSchema` (included when the tool defines one), and `annotations` — and `count`
`call-tenant-tool`	`tenant` (slug); `tool` (tenant tool name); `arguments` (object, optional)	The tenant tool's own result

list-tenants and search-tenant-tools are read-only. create-tenant always writes. Tools called through call-tenant-tool read or write depending on the tenant tool.

Workflow

The landlord tools are designed to be chained: call list-tenants to find a tenant's slug, search-tenant-tools with that slug to discover what the tenant's own server offers, then call-tenant-tool with the slug, tool name, and arguments to run it.

{
    "tenant": "example-tenant",
    "tool": "list-products-tool",
    "arguments": {
        "search": "digital"
    }
}

call-tenant-tool only runs tools that exist on the target tenant's own server. Landlord tool names and unknown tool names both return an error.

Landlord Permissions

create-tenant and any tenant write tool called through call-tenant-tool require a full-access (*) platform key, or an OAuth connection with write access. A read-only key or connection receives an error — for tenant writes, the tenant's own message: "You do not have admin permission to modify data in this tenant."

call-tenant-tool returns an error while the target tenant is in maintenance mode.

All platform keys share one MCP rate limit (120 requests per minute). Each signed-in user has their own.

Connecting an MCP client with OAuth — Signing in without an API key
API Authentication — Generating the PAT used to authenticate MCP requests

Authentication​

Connecting a Client​

Claude Desktop / Cursor / MCP Inspector​

Opening the URL in a browser​

Finding and Calling Tools​

Available Tools​

Integration tools​

Building interactions​

get-audience-member-tool includes​

get-settings-tool sections​

Writing settings​

Built-in Prompts​

Permissions​

Landlord MCP​

Platform API Keys​

Connecting a Client​

Landlord Tools​

Workflow​

Landlord Permissions​

Related​

Authentication

Connecting a Client

Claude Desktop / Cursor / MCP Inspector

Opening the URL in a browser

Finding and Calling Tools

Available Tools

Integration tools

Building interactions

`get-audience-member-tool` includes

`get-settings-tool` sections

Writing settings

Built-in Prompts

Permissions

Landlord MCP

Platform API Keys

Connecting a Client

Landlord Tools

Workflow

Landlord Permissions

Related