Unlayer MCP

Unlayer MCP connects AI assistants and coding agents (Claude, Claude Code, Cursor, Codex, VS Code, and other MCP clients) to Unlayer. With it, an agent can:

• Build email, page, and document templates as code with Unlayer Elements, returning @unlayer/react-elements source you can keep in your repo. Documents (invoices, reports, proposals) render to print-ready HTML for PDF.
• Generate or refine designs from a prompt with the AI Assistant.
• Turn existing HTML into an editable Unlayer design.
• Render and export designs to HTML, PDF, or PNG, and check templates for common issues.
• Answer Unlayer questions from the current docs.

Every design opens in the Unlayer visual builder, so teammates can edit what an agent created.

Unlayer MCP is a hosted Streamable HTTP server, listed in the official MCP Registry as com.unlayer/mcp:

https://api.unlayer.com/mcp

The Model Context Protocol (MCP) is an open standard for connecting AI clients to external tools and data sources.

Connect to Unlayer MCP

Browser sign-in with OAuth (recommended)

Use this path with any MCP client that supports OAuth. The client discovers Unlayer's authorization server, opens a browser, and manages access-token refreshes for you.

1. Add a custom MCP server in your client. Name it Unlayer MCP and enter:

   https://api.unlayer.com/mcp

2. Select Connect or Sign in. Your browser opens the Unlayer authorization flow.

3. Sign in, choose the project the client can access, and approve the requested permissions. Don't have an Unlayer account? Sign up free.

4. Return to your client. The 14 Unlayer tools are ready to use.

The flow uses OAuth 2.1 with PKCE (S256), Dynamic Client Registration, authorization codes, and rotating refresh tokens. You don't need to create or paste a token.

In Claude Desktop, open Settings → Connectors → Add custom connector, enter the URL above, save, and select Connect. Other OAuth-capable clients use the same server URL and browser flow.

Manual bearer token setup

If your client doesn't offer browser sign-in, configure a bearer token manually:

1. Open Console and choose the project you want to use. Don't have an account? Sign up free.

2. Create either an API Key (unlayer_sk_*, scoped to one project) or a Personal Access Token (unlayer_pat_*, works across your projects).

3. Add the server URL and token using your client's configuration format. For clients such as Cursor that use mcpServers JSON:

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

4. Restart or reconnect the client. It discovers the available tools automatically with tools/list.

Which token, and do I need a projectId?

An API Key (unlayer_sk_*) and an OAuth connection are bound to one project, so both can omit projectId. With a Personal Access Token (unlayer_pat_*), call list_workspaces first, then pass the project ID as a string to each project-scoped tool.

Authentication

MCP POST requests must carry a Bearer token in the Authorization header. Use an API Key (unlayer_sk_*) for CI and single-project automation, a Personal Access Token (unlayer_pat_*) for developer tools that span projects, or OAuth 2.1 for interactive clients such as Claude and ChatGPT. OAuth uses PKCE and Dynamic Client Registration; the client token is accepted only by the MCP resource and is never forwarded to the Cloud API.

OAuth connections are bound to the project selected during consent. Clients can request these permissions:

Scope	Permission
templates:read	List and read templates in the selected project.
designs:write	Generate, import, and edit temporary designs.
render:execute	Render designs to HTML, PDF, or images.

See Authentication for the full token and OAuth details.

Testing your connection

Send a JSON-RPC request to POST /mcp. With a PAT, call list_workspaces first to find a project ID. Replace <project-id> below with that ID. With an API Key or project-bound OAuth token, omit projectId.

curl https://api.unlayer.com/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_templates",
      "arguments": { "projectId": "<project-id>", "limit": 2 }
    }
  }'

A successful call returns your templates; an invalid token returns an authentication error. Depending on the token shape, that may be an HTTP 401 response or an MCP tool result with isError: true.

Available tools

The server includes 14 tools, grouped by what they do:

Templates

Tool	What it does
diagnose_template	Check for common design issues, missing alt text, low contrast, oversized images, and malformed merge tags.
get_template	Fetch one template by ID, including its design JSON.
list_templates	List templates in a project (cursor-paginated).

AI generation

Tool	What it does
ai_generate_design	Generate a design or refine an inline/saved design with the AI Assistant.
import_html_to_design	Turn an existing HTML email or page into an editable Unlayer design.

Render & export

Tool	What it does
export_design	Export a saved template to HTML, PNG, or PDF.
render_email	Render an email design (HTML output tuned for email clients).
render_preview_image	Render a design to a PNG preview image (S3-hosted URL).

Unlayer Elements

Tool	What it does
get_elements_schema	Get the supported Unlayer Elements component and property schema.
render_elements	Render an Elements tree to source code, HTML, and design JSON, with an editor link and preview when available.

Workspace & account

Tool	What it does
get_my_subscription	Look up the caller's plan, customer-facing features, and usage limits.
list_recent_releases	Get a link to Unlayer's official changelog — point users there for what's new and what changed.
list_workspaces	List accessible workspaces and projects. OAuth returns the consented project; API keys cannot list workspaces.

Discovery

Tool	What it does
search_documentation	Full-text search over docs.unlayer.com — useful for grounding an AI client's answers in our docs.

tools/list describes each tool and its typed inputs. Tool results contain JSON in text content. diagnose_template checks common issues; it is not a full accessibility audit.

Which tool for which job

The server sends the same guidance to MCP clients in its instructions, so agents pick the right tool:

The user wants…	Use
Templates as code: emails for their app (welcome, receipt, password reset), PDF documents (invoices, reports, proposals), templates kept in a repo, React/Next.js	get_elements_schema, then render_elements with an Email, Page, or Document root. In the project, install @unlayer/react-elements: renderToHtml() gives send-ready or print-ready HTML and renderToJson() gives design JSON that opens in the builder.
A design from a prompt, with no code involved	ai_generate_design (displayMode: "document" for documents)
Existing HTML (an email or page) made editable	import_html_to_design
A saved template exported to HTML, PNG, or PDF	export_design
Help embedding the Unlayer builder in their app	search_documentation, plus the Unlayer Skills for their coding agent (npx skills add unlayer/unlayer-skills)

Example: generate a design and preview it

A typical agent flow chains a few tools. Here's "make me a product-launch email and show me what it looks like".

1. Establish the project context. OAuth uses the project selected during consent, and an API Key embeds its project, so both can skip this step. With a PAT, call list_workspaces with no arguments to discover the projectId required by project-scoped tools:

{
  "data": [
    {
      "id": 1,
      "name": "Acme",
      "projects": [{ "id": 12345, "name": "Marketing" }]
    }
  ]
}

With a PAT, include "projectId": "12345" in each project-scoped call below, using your actual project ID.

2. Generate the design. Call ai_generate_design with a prompt. The result opens in a temporary editor session without creating a project template:

{
  "prompt": "Product launch newsletter for Nova Pro, dark theme",
  "displayMode": "email"
}

It returns an editor URL and design JSON. previewImageUrl is included when preview rendering succeeds. The examples below abbreviate the design as { "body": {} }; use the full returned design in actual calls.

{
  "editorUrl": "https://api.unlayer.com/editor-sessions/<session-token>/edit",
  "previewImageUrl": "https://s3.../preview.png",
  "displayMode": "email",
  "design": { "body": {} }
}

Show previewImageUrl when present and link to editorUrl to open the design.

3. Refine without saving. Pass the returned design and displayMode back into ai_generate_design with the next prompt. The refinement starts from that exact design and opens another temporary editor session:

{
  "prompt": "Make the call-to-action button red",
  "design": { "body": {} },
  "displayMode": "email"
}

Use templateId instead of design when the starting point is already saved as a project template. Do not pass both.

4. Preview. Pass the current design straight into render_preview_image (no save needed) to regenerate the PNG after a change:

{
  "design": { "body": {} },
  "displayMode": "email"
}

It returns the new image URL:

{ "data": { "url": "https://s3.../preview.png" } }

Editor sessions are temporary

Generation, import, rendering, and export tools do not change project templates. Save updates the temporary editor session. Use Download design or Download HTML before it expires to keep a copy.

Limits and security

• Origins — browser requests must use an allowed origin. Non-browser clients can omit Origin.
• Requests — 1 MiB body limit, per-credential rate limits, and a shared concurrency limit per server instance.
• Timeouts — upstream calls have a 240-second timeout by default.
• Large results — text beyond 140,000 characters is replaced with a truncation notice.
• Header redaction — Authorization, Cookie, and X-Unlayer-Project-Id are redacted from server logs.

Related

• Cloud API — REST endpoints for projects, templates, generation, and rendering.
• Skills — packaged context for AI coding agents that work alongside MCP.
• SDK — typed access to supported Cloud API operations from server-side code.
• CLI — terminal tool for managing templates and projects.
• Model Context Protocol specification — upstream protocol docs.