MCP
The Alpaco MCP gateway exposes a standardized connection layer that allows compliant AI clients to natively understand and operate your email workspace.
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.
Only users with role Admin can create and manage OAuth keys.
Log into your Alpaco platform and go to Organization Settings
Create an MCP connection > give it a name and change the redirect URI(optional) > note down the Client secret and Client ID.
Open your preferred Ai LLM and type in the following info: Remote MCP server URL:
https://platform.alpaco.email/api/mcp/v1/gatewayOAuth Client ID:*Your Client IDfrom the above step*OAuth Client Secret:*Your Client secret from the above step*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.
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:
Grab your JWT(Jason Web token) token from user profile > click Generate token
Remote MCP server URL:
https://platform.alpaco.email/api/mcp/v1/gateway
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.
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.
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.
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:
"What email templates do I have access to right now?"
Invokes the templates tool to pull your workspace design rules directory.
The AI prints a clean list of available template names and IDs, the structural block components they allow, and their input field requirements.
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.
"Create a new email campaign called 'Summer Product Update' using My template"
Executes the assemble tool, passing the required name and conditional template_id.
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.
If the AI forgets to pass global layout metadata, your validation loop rejects the request with a 422 Unprocessable Entity listing missing fields (e.g., design.settings.subjectline is required).
"Insert Block type Article after Hero Block and write a teaser article about our summer products"
Runs get_details to fetch the canvas state, appends a new block object to the blocks array with key: "article", populates the nested values object with the generated summer teaser text, and hits assemble.
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.
If the AI makes a typo and maps text to a non-existent key (like teaser_text instead of body_text), the compilation engine throws a 422 validation error detailing the allowed keys for the article block, forcing the model to instantly self-correct the payload parameters.
"Find our standard company logo from the media library to use for the header"
Executes the assets tool, passing a targeted query string (e.g., {"search": "logo"}).
The AI locates the graphic inside your asset library and extracts its secure, optimization-ready CDN URL to pass to your layout blocks.
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.
"Change the main headline text on the last block read 'Summer Sale Now On'"
First executes get_details to read the current layout JSON state. It safely modifies the text inside the targeted block, wrapping it strictly inside the block's values object, and shoots the entire payload back to assemble.
The existing email draft record is overwritten and re-compiled on the server. Your chat preview frame instantly flashes to display the text update.
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.
"Export the email to our Hubspot"
Runs the connections tool to verify linked platforms, then executes the export tool passing the target email_id and esp_connection_id.
The engine compiles your layout into fully inline-styled, responsive HTML/AMP markup and syncs the template directly to your live HubSpot dashboard.
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.
Last updated