Knak MCP Server

The Knak MCP (Model Context Protocol) server gives AI assistants like Claude and ChatGPT direct access to your Knak platform.

Through a secure OAuth connection, your AI assistant can browse your brands, campaigns, and themes — then generate production-ready emails inside Knak on your behalf.

Typical workflow:

1. Connect — Link your AI assistant to Knak via MCP.

2. Authenticate — Sign in with your Knak credentials.

3. Browse — Discover your brands and campaigns (themes are optional and opt-in).

4. Generate — Create an email with a natural-language prompt.

5. Preview — A live progress widget polls until generation completes, then a rendered preview appears inline. Open the asset in Knak to refine or send.

All content is generated inside the Knak platform using your brand’s themes and design system. The AI assistant orchestrates the workflow — it does not write the email content itself.

Available Tools

The Knak MCP server exposes seven tools, typically used in this order:

Tool	Description
list-brands	List all brands (profiles) accessible to your account.
list-campaigns	List campaigns within a brand. Use after selecting a brand.
list-themes	Discover available themes for asset generation. Optional — use only when the user explicitly requests a theme. Supports filtering by name or published status.
generate-asset	Create a new email with AI. Accepts a creative prompt and optional parameters for theme, subject line, sender details, tags, and attachments. Generation is asynchronous — you receive a link to the asset immediately.
get-asset-preview	Return a rendered visual preview (screenshot) of a generated asset. Called automatically after generation completes to display the result inline, or any time the user asks to see an asset.
list-assets	Search and filter existing assets by brand, campaign, name, or type. Supports pagination.
get-asset	Fetch full metadata for a single asset by ID. Use after generating or listing assets to inspect details.

Prerequisites

Before connecting, ensure the following:

• Knak account — You need an active Knak account with access to at least one brand.
• MCP enabled — A Knak company administrator must enable the MCP integration for your organization.
• MCP-compatible AI client — You need an AI assistant that supports the Model Context Protocol (e.g., Claude Desktop, ChatGPT).

Note

Your data access through MCP is scoped to your account permissions. You will only see brands, campaigns, and assets that your Knak account has access to.

MCP Server URL

Environment	URL
Production	https://enterprise.knak.io/mcp/public

OAuth discovery endpoint: https://enterprise.knak.io/.well-known/oauth-authorization-server

Authentication

The Knak MCP server uses OAuth 2.1 Authorization Code flow with PKCE for secure authentication:

1. Your AI client registers itself automatically via Dynamic Client Registration (DCR).

2. You are redirected to Knak to sign in and authorize access.

3. The client receives an access token scoped to mcp:use.

4. All subsequent MCP requests use this token.

Tip

Most users do not need to configure authentication manually — MCP-compatible clients handle the OAuth flow automatically. If your client requires manual configuration, point it at the discovery URL — it returns the authorization, token, and registration endpoints.

Parameter	Value
Discovery URL	https://enterprise.knak.io/.well-known/oauth-authorization-server
Scope	mcp:use
PKCE	Required (S256)

Tool Reference

generate-asset

Creates a new email asset inside a campaign folder. The asset is generated asynchronously — you receive a URL to view it in Knak immediately.

Parameters:

Parameter	Type	Required	Description
prompt	string	Yes	Creative prompt describing the desired asset content
campaign_name	string	Yes	Name of the campaign folder to create the asset in
brand_name	string	No	Brand to scope the asset to. Required only when multiple campaigns across brands share the same name (to disambiguate).
asset_name	string	No	Display name for the asset. Auto-generated if omitted.
subject	string	No	Email subject line
theme_id	string	No	Theme ID from list-themes
from_name	string	No	Sender display name
from_email	string	No	Sender email address
reply_email	string	No	Reply-to email address
tags	array	No	List of tags to apply
images	array	No	Image attachments (max 10). Each: {url, filename}
files	array	No	File attachments (max 2). Each: {url, filename}

Response:

{
  "assetId": "abc-123",
  "status": "generating",
  "campaignUrl": "https://enterprise.knak.io/account/folder-studio/...",
  "assetUrl": "https://enterprise.knak.io/email/abc-123",
  "statusUrl": "https://enterprise.knak.io/api/v2/open/assets/abc-123/generation-status?signature=...",
  "message": "Knak AI is generating your asset..."
}

Generation is asynchronous. Supporting clients display a live progress widget that polls statusUrl until completion, then call get-asset-preview to render the result inline. campaignUrl opens the containing campaign folder in Knak; assetUrl opens the asset itself once generation finishes.

list-brands

Returns all brands accessible to the authenticated user.

Parameters: None

Response:

{
  "brands": [
    {
      "id": "abc-123",
      "name": "brand-slug",
      "display_name": "My Brand"
    }
  ]
}

list-campaigns

Returns campaigns accessible to the user, optionally filtered by brand.

Parameters:

Parameter	Type	Required	Description
brand_name	string	No	Brand name to filter by (use name from list-brands, not display_name)

Response:

{
  "campaigns": [
    {
      "id": "abc-123",
      "name": "Q1 Campaign",
      "brand_id": "def-456",
      "brand_name": "brand-slug"
    }
  ]
}

list-assets

Search and filter existing assets with pagination.

Parameters:

Parameter	Type	Required	Description
brand_name	string	No	Filter by brand name
campaign_name	string	No	Filter by campaign name
search	string	No	Search assets by name
type	string	No	email or landing
limit	integer	No	Results per page (1–25, default 10)
offset	integer	No	Pagination offset (default 0)

get-asset

Fetch full metadata for a single asset.

Parameters:

Parameter	Type	Required	Description
asset_id	string	Yes	The asset ID (from list-assets or generate-asset)

get-asset-preview

Return a rendered visual preview of a generated asset. Typically called automatically after generate-asset completes to display the result inline. Returns a PNG screenshot URL, or an inline HTML fallback (up to 100 KB) if screenshotting fails. Errors if the asset is still generating or if generation failed.

Parameters:

Parameter	Type	Required	Description
asset_id	string	Yes	The asset ID returned by generate-asset or list-assets

list-themes

Discover available themes for asset generation. Themes are optional — pass the returned theme_id to generate-asset only when the user explicitly requests a theme.

Parameters:

Parameter	Type	Required	Description
name	string	No	Exact theme name match
search	string	No	Partial name search
published	boolean	No	Filter by published status

Interactive Widgets

On clients that support MCP UI resources (for example, ChatGPT), the Knak server provides two interactive widgets:

Progress widget

ui://knak/asset-progress — appears automatically after generate-asset and polls the signed statusUrl until the asset is ready.

Preview widget

ui://knak/asset-preview — appears when get-asset-preview is called, rendering the screenshot (or HTML fallback) of the asset inline.

Clients that do not support widgets fall back to the structured text responses, which contain the same URLs.

Example Prompts

Once connected, try asking your AI assistant:

• “List my brands in Knak”
• “Show me all campaigns in my [brand name] brand”
• “Create a promotional email for our summer sale in the Q3 Marketing campaign”
• “List my recent emails”
• “Show me the details for asset [ID]”
• “What themes are available for my brand?”
• “Create a welcome email using the [theme name] theme with subject line ‘Welcome to our community‘“

Security

• OAuth 2.1 with PKCE — No client secrets are exposed; all authentication uses proof keys.
• User-scoped access — Every API call respects your Knak account permissions. You only see your company’s data.
• Dynamic Client Registration — AI clients register automatically; stale registrations are cleaned up after 30 days of inactivity.

Troubleshooting

”MCP server not available” or connection refused

Your company administrator needs to enable the MCP integration. Contact your Knak admin and ask them to enable the MCP server in company preferences.

”Authentication failed” or “Token expired”

Your OAuth session has expired. Disconnect and reconnect the MCP server in your AI client’s settings to re-authenticate.

”Brand not found” or “Campaign not found”

You may not have access to the requested brand or campaign. Run list-brands and list-campaigns to see what is available to your account. Check with your Knak admin if you expect to see additional brands.

Asset generation seems stuck

After calling generate-asset, supporting AI clients display a progress widget that polls until generation completes. Generation typically takes 1–2 minutes; the widget times out after about 5 minutes. If the widget has not finished within that window, open the campaignUrl returned by generate-asset to check status in Knak directly. If the asset still does not appear, try generating again.

Rate Limits

The Knak MCP server enforces several limits:

• Asset generation (per user) — Generating assets too quickly returns a rate-limit error. Wait a moment and retry.
• Asset generation (per company) — Each organization has a daily asset generation quota. Contact customer support if you need a higher limit.
• Dynamic Client Registration — Limited to 10 registrations per minute per IP to prevent abuse.
• Standard API rate limits apply to all other MCP requests. Wait briefly and retry if you exceed a limit.