MCP Server

Every Allegro tenant exposes a Model Context Protocol (MCP) server at https://<your-tenant>/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 authenticates requests with a Sanctum Personal Access Token (PAT) the same way as the REST API.

Include the token as a Bearer header on every request:

Authorization: Bearer <your-token>

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

Connecting a Client

Claude Desktop / Cursor / MCP Inspector

Add the following entry to your client's MCP server configuration, replacing <your-tenant> and <your-token> with your actual values:

{
    "mcpServers": {
        "allegro": {
            "url": "https://<your-tenant>/mcp",
            "headers": {
                "Authorization": "Bearer <your-token>"
            }
        }
    }
}

CLI (Laravel Artisan)

For local development or scripting, you can start a stdio-based MCP session directly:

php artisan allegro:mcp:start --tenant=<slug-or-id>

Pass --user=<email-or-uuid> to authorize write operations as a specific admin user. In production, either --user or the ALLEGRO_MCP_ACTOR environment variable (also accepts an email address or UUID) must be provided — the command refuses to start without one to prevent privilege escalation via shell access.

Available Tools

Read-only

Tool	Description
search-audience-members	Cursor-paginated search by name or email
get-audience-member	Fetch a member by ID or email; optionally include entitlements, purchases, events, meta, external_profiles, foreign_keys, sync_status, or sessions
list-products	List all products
list-plans	List all plans
list-offers	List all offers
list-templates	Cursor-paginated list of template summaries
get-template	Fetch a template; optionally include HTML, CSS, JS, fields, or revision history
get-embed-snippet	Fetch the current embed snippet content and updated_at; pass include: ["revisions"] to include revision history
get-settings	Fetch tenant configuration grouped into sections; pass sections to choose groups (omit for all lightweight sections — preview_css and embed_snippet are opt-in)

Write (admin role required)

Tool	Description
update-audience-member	Update member profile fields
grant-entitlement	Grant a product entitlement to a member
revoke-entitlement	Revoke an active entitlement from a member
create-product	Create a new product
update-product	Update an existing product
create-template	Create a new template
update-template	Update an existing template
update-embed-snippet	Update the embed snippet content; accepts an optional note field (defaults to "Saved via MCP")

note

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

get-audience-member includes

get-audience-member 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 sections

get-settings 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	Configured (enabled) login_providers, in display order	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
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 only provider names, never their stored credentials. Use get-embed-snippet when you need embed snippet revision history.

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 require the authenticated user to have the admin role on the tenant. Read-only tools are available to all authenticated tenant members. A non-admin token attempting a write operation receives a 403 Forbidden response.

Related

• API Authentication — Generating the PAT used to authenticate MCP requests