# MCP Server

Every Allegro tenant exposes a [Model Context Protocol](https://modelcontextprotocol.io) (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[​](#authentication "Direct link to Authentication")

The MCP server authenticates requests with a Sanctum Personal Access Token (PAT) the same way as the [REST API](/developer/api/authentication.md).

Include the token as a Bearer header on every request:

```http
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[​](#connecting-a-client "Direct link to Connecting a Client")

### Claude Desktop / Cursor / MCP Inspector[​](#claude-desktop--cursor--mcp-inspector "Direct link to 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:

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

```

### CLI (Laravel Artisan)[​](#cli-laravel-artisan "Direct link to CLI (Laravel Artisan)")

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

```bash
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[​](#available-tools "Direct link to Available Tools")

### Read-only[​](#read-only "Direct link to 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, or meta                          |
| `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 |

### Write (admin role required)[​](#write-admin-role-required "Direct link to 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.

## Built-in Prompts[​](#built-in-prompts "Direct link to 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[​](#permissions "Direct link to 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[​](#related "Direct link to Related")

* [API Authentication](/developer/api/authentication.md) — Generating the PAT used to authenticate MCP requests