MCP Server

Plan Feature

This feature is only available on Growth and Scale plans.

The Templatical MCP Server lets AI agents interact with your email templates programmatically using the Model Context Protocol. Instead of building custom API integrations, your AI agents can discover and call structured tools for template management, media handling, and AI-powered content generation.

How It Works

The MCP Server exposes a standard MCP endpoint that AI agents connect to over HTTP. The agent authenticates with a dedicated MCP API key and specifies the target project and tenant via request headers. All operations are scoped to the specified project and tenant.

The server speaks JSON-RPC 2.0 with the MCP transport layer, so any MCP-compatible client can connect without additional configuration.

Prerequisites

Before setting up the MCP Server, ensure you have:

1. A Templatical account on a Growth or Scale plan
2. An MCP API key — see Creating MCP API Keys
3. Your project UUID and tenant slug

Creating MCP API Keys

MCP API keys are managed from the Templatical dashboard under MCP Keys in the sidebar.

1. Navigate to MCP Keys in the dashboard sidebar
2. Click Create MCP Key
3. Enter a descriptive name (e.g., "Claude Desktop - Production")
4. Optionally set an expiration date
5. Choose project access scope:
   • All projects (default) — the key can access any project in your team
   • Specific projects — select which projects the key can access
6. Click Create

After creation, you will see the full API key once. Copy it and store it securely — it cannot be retrieved again. If lost, you can regenerate the secret from the key's card in the dashboard.

Each team can have up to 10 MCP API keys.

Endpoint

POST https://templatical.com/api/v1/mcp

All requests must include the following headers:

Header	Description
Authorization	Bearer {mcp_api_key} — your MCP API key from the dashboard
X-Project-Id	Your project UUID (from the Templatical dashboard)
X-Tenant	The tenant slug for data scoping

Rate Limiting

The MCP endpoint enforces rate limits per API key (or IP address if no key is provided):

Limit	Window
120 requests	Per minute
2,000 requests	Per hour

When a rate limit is exceeded, the server responds with HTTP 429 Too Many Requests. The Retry-After header indicates how many seconds to wait before retrying.

Connecting an AI Agent

Claude Desktop

Add the following to your Claude Desktop MCP configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "templatical": {
      "type": "streamable-http",
      "url": "https://templatical.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer {mcp_api_key}",
        "X-Project-Id": "{project_id}",
        "X-Tenant": "{tenant_slug}"
      }
    }
  }
}

Replace {mcp_api_key}, {project_id}, and {tenant_slug} with your actual values.

Custom MCP Clients

Any MCP client that supports the Streamable HTTP transport can connect. Point it to the endpoint URL and include the Authorization, X-Project-Id, and X-Tenant headers.

Available Tools

Once connected, the AI agent can discover all available tools via the MCP tools/list method. Tools are grouped by domain:

Project Configuration

Tool	Description
get-project-config	Get project configuration including features, limits, plan, media settings, and storage usage

Templates

Tool	Description
list-templates	List templates for the current tenant with optional name search. Returns paginated results (25 per page) with cursor-based pagination
get-template	Get a template by ID, including its full content
create-template	Create a new email template
update-template	Update a template's name, content, or both
delete-template	Permanently delete a template
export-template	Export a template as HTML (and optionally MJML)

Snapshots

Tool	Description
list-snapshots	List snapshot history for a template (up to 50, newest first)
get-snapshot	Get a specific snapshot with its full content
create-snapshot	Create a manual snapshot of the current template content
restore-snapshot	Restore a template to a previous snapshot state

Comments

These tools require the Commenting feature to be enabled on your plan.

Tool	Description
list-comments	List all root comments for a template, including replies
create-comment	Create a comment or reply on a template
update-comment	Update a comment's body
delete-comment	Permanently delete a comment
resolve-comment	Resolve or unresolve a comment thread

Media

Tool	Description
browse-media	Browse media files with folder filtering, search, and sorting
import-media-from-url	Import a media file from a URL
delete-media	Permanently delete one or more media files

Media Folders

These tools require the Media Folders feature to be enabled on your plan.

Tool	Description
list-media-folders	List all media folders as a tree structure
create-media-folder	Create a new media folder
update-media-folder	Rename a media folder
delete-media-folder	Permanently delete a media folder

AI

These tools require the AI Generation feature to be enabled on your plan.

Tool	Description
generate-template	Generate or modify an email template using AI from a text prompt
score-template	Score a template for quality across spam, readability, accessibility, and best practices
rewrite-text	Rewrite text content using AI with a custom instruction

Available Resources

Resources provide static or semi-static content that AI agents can read for context. Use the MCP resources/list and resources/read methods to access them.

Resource	URI	Description
block-schema	templatical://schema/blocks	TypeScript type definitions for all email template block interfaces, types, and enums

Available Prompts

Prompts are reusable prompt templates that guide AI agents through common workflows. Use the MCP prompts/list and prompts/get methods to access them.

design-template

Guide through designing a new email template based on purpose, audience, and tone. The prompt instructs the agent to read the project config and block schema, then generate a template that follows brand guidelines and email best practices.

Argument	Required	Description
purpose	Yes	The purpose of the email template (e.g., welcome email, newsletter, promotional campaign)
audience	No	The target audience for the email (e.g., new users, existing customers)
tone	No	The desired tone (e.g., formal, casual, friendly, professional)

review-template

Review an existing template for quality, accessibility, and best practices. The prompt instructs the agent to fetch the template, score it, and provide a structured review with strengths, areas for improvement, and priority fixes.

Argument	Required	Description
template_id	Yes	The ID of the template to review

Example Interaction

Here is what a typical AI agent session looks like over the MCP protocol:

1. List templates

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "list-templates",
    "arguments": {}
  }
}

2. Generate a template with AI

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "generate-template",
    "arguments": {
      "prompt": "Create a welcome email for new subscribers with a hero image, greeting, and CTA button"
    }
  }
}

3. Export the result

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "tools/call",
  "params": {
    "name": "export-template",
    "arguments": {
      "template_id": "01234567-89ab-cdef-0123-456789abcdef"
    }
  }
}

Error Handling

MCP tool errors follow a consistent format:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "MCP Server is not available on your current plan."
      }
    ],
    "isError": true
  }
}

Common error scenarios:

Error	Cause
HTTP 400 Bad Request	Missing X-Project-Id or X-Tenant header
HTTP 401 Unauthorized	Missing, invalid, or expired MCP API key
HTTP 403 Forbidden	MCP Server feature not available on your plan, or the key does not have access to the specified project
HTTP 404 Not Found	Invalid project UUID, or tenant slug not found within the project
HTTP 429 Too Many Requests	Rate limit exceeded — check the Retry-After header
Feature 'commenting' is not available on your current plan.	A specific feature is not included in the current plan
Template not found.	The template ID does not exist or belongs to a different tenant