> For the complete documentation index, see [llms.txt](https://documentation.alpaco.email/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.alpaco.email/account-settings/mcp.md).

# MCP

### Connect

Alpaco supports two integration tracks. Choose the method that best fits your workspace environment.

#### method 1# OAuth Authentication

This is the automated, zero-token track managed directly through our secure authentication bridge.

{% hint style="info" %}
Only users with role **Admin** can create and manage OAuth keys.
{% endhint %}

1. Log into your Alpaco platform and go to **Organization Settings**
2. Create an MCP connection > give it a name and change the redirect URI(optional) > note down the *Client secret* and *Client ID*.
3. Open your preferred Ai LLM and type in the following info:\
   **Remote MCP server URL:** <mark style="color:$warning;">`https://platform.alpaco.email/api/mcp/v1/gateway`</mark>\
   **OAuth Client ID:** *<mark style="color:$warning;">`*Your Client IDfrom the above step*`</mark>*\
   **OAuth Client Secret:** *<mark style="color:$warning;">`*Your Client secret from the above step*`</mark>*
4. *Because this method validates protocol commands through your live browser handshake, you must keep your Alpaco workspace open in an active browser tab while running your AI chat client to establish the gateway connection.*

<figure><img src="/files/gTLQGRyu7z6tYCILuFxV" alt=""><figcaption><p>Example of MCP connection creation from Organization settings in Alpaco</p></figcaption></figure>

<figure><img src="/files/2NqGiQkFMEGhGmgKQRE1" alt=""><figcaption><p>Example of how setting up a MCP connector from the Claude Ai LLM interface</p></figcaption></figure>

#### Method #2 Manual setup (Advanced / Headless Agents)

If you are building custom background scripts, persistent automated workflows, or using an AI client that doesn't support our OAuth bridge, you can connect manually using raw data variables.

To hook up a client manually via Streamable HTTP (Server-Sent Events / SSE), your environment will ask you for two foundational values:

1. Grab your JWT(Jason Web token) token from user profile > click Generate token
2. **Remote MCP server URL:** <mark style="color:$warning;">`https://platform.alpaco.email/api/mcp/v1/gateway`</mark>

{% hint style="info" %}
Every LLM client (Claude Desktop, Cursor, Gemini, etc.) expects these two data points in completely different syntax structures—some require the JWT passed as an environment variable (`ALPACO_JWT_TOKEN`), some as a standard HTTP Bearer header (`Authorization: Bearer YOUR_JWT`), and others via local JSON config files. Refer directly to your specific AI tool's developer docs to see how it prefers to ingest an SSE endpoint and authorization token.
{% endhint %}

<figure><img src="/files/7RJNKCSGH504iMinPmk8" alt=""><figcaption><p>An example of a JWT token generated on the user profile page</p></figcaption></figure>

### Capabilities

With your AI client securely authenticated, you are ready to access and command your Alpaco organization directly through natural language chat. Your model functions as an active, context-aware operator of your workspace, transforming conversation into verified, production-ready design elements.

{% embed url="<https://youtu.be/mWVFYX0eLT8>" %}

{% hint style="info" %}
For some LLM's we'll be able to render a preview directly in the Chat window for you to review. While this is not supported by every Ai chat, you will get a link to the campaign you're prompting on.
{% endhint %}

The matrix below outlines some examples of what you can prompt, what to expect during execution, and how the platform handles edge-case errors behind the scenes:

<table data-search="true"><thead><tr><th width="249">Prompt examples</th><th>What it executes under the hood</th><th>The Outcome inside Alpaco</th><th>Error / Guardrail Behavior</th></tr></thead><tbody><tr><td><strong>"What email templates do I have access to right now?"</strong></td><td>Invokes the <code>templates</code> tool to pull your workspace design rules directory.</td><td>The AI prints a clean list of available template names and IDs, the structural block components they allow, and their input field requirements.</td><td>If your workspace has no templates created, the engine responds with an empty array, and the AI will prompt you to build a template in the dashboard.</td></tr><tr><td><strong>"Create a new email campaign called 'Summer Product Update' using My template"</strong></td><td>Executes the <code>assemble</code> tool, passing the required <code>name</code> and conditional <code>template_id</code>.</td><td>A brand-new, fresh email draft asset is initialized in your database. Supported chat clients will instantly pop open a native visual preview window rendering your template.</td><td>If the AI forgets to pass global layout metadata, your validation loop rejects the request with a <code>422 Unprocessable Entity</code> listing missing fields (e.g., <code>design.settings.subjectline is required</code>).</td></tr><tr><td><strong>"Insert Block type Article after Hero Block and write a teaser article about our summer products"</strong></td><td>Runs <code>get_details</code> to fetch the canvas state, appends a new block object to the <code>blocks</code> array with <code>key: "article"</code>, populates the nested <code>values</code> object with the generated summer teaser text, and hits <code>assemble</code>.</td><td>A new component block is placed into your email layout. The core layout updates on the server, and the real-time chat preview window instantly shifts to render the new summer article.</td><td>If the AI makes a typo and maps text to a non-existent key (like <code>teaser_text</code> instead of <code>body_text</code>), the compilation engine throws a <code>422</code> validation error detailing the allowed keys for the <code>article</code> block, forcing the model to instantly self-correct the payload parameters.</td></tr><tr><td><strong>"Find our standard company logo from the media library to use for the header"</strong></td><td>Executes the <code>assets</code> tool, passing a targeted query string (e.g., <code>{"search": "logo"}</code>).</td><td>The AI locates the graphic inside your asset library and extracts its secure, optimization-ready CDN URL to pass to your layout blocks.</td><td>If the AI attempts to pull your entire database without a keyword, your token safeguard forces a search filter requirement to prevent context window exhaustion.</td></tr><tr><td><strong>"Change the main headline text on the last block read 'Summer Sale Now On'"</strong></td><td>First executes <code>get_details</code> to read the current layout JSON state. It safely modifies the text inside the targeted block, wrapping it strictly inside the block's <code>values</code> object, and shoots the entire payload back to <code>assemble</code>.</td><td>The existing email draft record is overwritten and re-compiled on the server. Your chat preview frame instantly flashes to display the text update.</td><td>The protocol strictly blocks partial or empty array updates. If the AI fails to run a state-fetch first, the platform prevents the save command to ensure your existing design blocks are never accidentally wiped out.</td></tr><tr><td><strong>"Export the email to our Hubspot"</strong></td><td>Runs the <code>connections</code> tool to verify linked platforms, then executes the <code>export</code> tool passing the target <code>email_id</code> and <code>esp_connection_id</code>.</td><td>The engine compiles your layout into fully inline-styled, responsive HTML/AMP markup and syncs the template directly to your live HubSpot dashboard.</td><td>If your AI specifies an invalid integration ID or the platform connection has expired, the engine rejects the request with an authentication failure error, and the AI provides your workspace settings link.</td></tr></tbody></table>