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

Tool	Description
list-brands	List the brands (profiles) accessible to your account, searchable by name.
list-campaigns	List campaigns within a brand, searchable by name. 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.
list-brand-voices	Discover the brand voices assigned to a brand, including its default. Used to propose the default voice for confirmation before generating. One brand voice applies per generated asset.
list-color-kits	Discover the color kits assigned to a brand, including its default. Used to propose the default color kit for confirmation before generating. One color kit applies per generated asset.
list-font-kits	Discover the font kits assigned to a brand, including its default. Used to propose the default font kit for confirmation before generating. One font kit applies per generated asset.
search-modules	Find the published email modules available to a brand by words in their names, or browse them a page at a time. Returns up to 25 modules per call with the total count.
get-module-by-name	Fetch a single module by its exact name within a brand. Use after search-modules when you already know the module name.
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 campaign immediately. Clients that support MCP UI show a live preview when generation completes.
get-asset-preview	Return a rendered visual preview (screenshot) of a generated asset and a link to open it in Knak, whenever 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 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

list-brands

List the brands (profiles) accessible to your account, searchable by name.

Parameter	Type	Required	Description
search	string	No	Filter by brand name or display name. Max 191 characters.
limit	integer	No	Maximum brands to return, 1-25. Defaults to 25.
offset	integer	No	Brands to skip, for pagination. Defaults to 0.

Response:

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

The name field is the value to pass to list-campaigns and generate-asset; display_name is for presentation only.

list-campaigns

List campaigns within a brand, searchable by name. Use after selecting a brand.

Parameter	Type	Required	Description
brand_name	string	No	Filter by brand, as the `name` field from list-brands.
search	string	No	Filter by campaign name. Max 191 characters.
limit	integer	No	Maximum campaigns to return, 1-25. Defaults to 25.
offset	integer	No	Campaigns to skip, for pagination. Defaults to 0.

Response:

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

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.

Parameter	Type	Required	Description
brand_id	string	Yes	Brand to list themes for.
name	string	No	Filter by exact theme name.
search	string	No	Filter by partial theme name.
published	boolean	No	true returns published themes, false returns drafts. Defaults to published only.

list-brand-voices

Discover the brand voices assigned to a brand, including its default. Used to propose the default voice for confirmation before generating. One brand voice applies per generated asset.

Parameter	Type	Required	Description
brand_id	string	Yes	Exact brand ID whose brand voices should be returned.

list-color-kits

Discover the color kits assigned to a brand, including its default. Used to propose the default color kit for confirmation before generating. One color kit applies per generated asset.

Parameter	Type	Required	Description
brand_id	string	Yes	Exact brand ID whose color kits should be returned.

list-font-kits

Discover the font kits assigned to a brand, including its default. Used to propose the default font kit for confirmation before generating. One font kit applies per generated asset.

Parameter	Type	Required	Description
brand_id	string	Yes	Exact brand ID whose font kits should be returned.

search-modules

Find the published email modules available to a brand by words in their names, or browse them a page at a time. Returns up to 25 modules per call with the total count.

Parameter	Type	Required	Description
brand_id	string	Yes	Brand to search within.
search_term	string	No	Words matched against module names; every word must appear. Omit to browse all modules.
limit	integer	No	Maximum modules to return, 1-25. Defaults to 25.
offset	integer	No	Modules to skip, for pagination. Defaults to 0.

get-module-by-name

Fetch a single module by its exact name within a brand. Use after search-modules when you already know the module name.

Parameter	Type	Required	Description
name	string	Yes	Exact module name.
brand_id	string	Yes	Brand that owns the module.

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 campaign immediately. Clients that support MCP UI show a live preview when generation completes.

Parameter	Type	Required	Description
prompt	string	Yes	Creative prompt describing the desired content, followed by the full text of any attached copy document, unmodified. Pass any webpage URL verbatim; Knak extracts from it server-side.
campaign_name	string	Yes	Existing campaign to create the asset in, as the `name` field from list-campaigns.
brand_name	string	No	Brand to scope the asset to, as the `name` field from list-brands. Required only when several campaigns share the given name.
asset_name	string	No	Display name for the asset. Generated from the prompt if omitted.
subject	string	No	Email subject line. Generated from the prompt if omitted.
theme_id	string	No	Theme to apply, from list-themes. Cannot be combined with module_ids.
brand_voice_id	string	No	ID of the brand voice the user confirmed or chose via list-brand-voices. Omit to use the brand default.
color_kit_id	string	No	ID of the color kit the user confirmed or chose via list-color-kits. Omit to use the brand default. Pass "none" only when the user asks for no color kit or wants the email to take its look from a website. Cannot be combined with theme_id.
font_kit_id	string	No	ID of the font kit the user confirmed or chose via list-font-kits. Omit to use the brand default. Pass "none" only when the user asks for no font kit or wants the email to take its look from a website. Cannot be combined with theme_id.
module_ids	array of string	No	Modules to include, from search-modules. Cannot be combined with theme_id. Maximum 10.
enable_module_recommendation	boolean	No	Let Knak AI choose modules from the brand library. Defaults to false.
from_name	string	No	Sender display name.
from_email	string	No	Sender email address.
reply_email	string	No	Reply-to email address.
tags	array of string	No	Tags to apply to the asset.
images	array of object	No	Images to include. Each url must be publicly reachable; a conversation attachment cannot be used. Maximum 10. url (string, required) — Public URL of the image filename (string, required) — Filename for the image
files	array of object	No	Files supplying extra context for the generation. Each url must be publicly reachable. Maximum 2. url (string, required) — Public URL of the file filename (string, required) — Filename for the file

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.

get-asset-preview

Return a rendered visual preview (screenshot) of a generated asset and a link to open it in Knak, whenever the user asks to see an asset.

Parameter	Type	Required	Description
asset_id	string	Yes	Asset to preview, as returned by generate-asset.

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.

list-assets

Search and filter existing assets by brand, campaign, name, or type. Supports pagination.

Parameter	Type	Required	Description
brand_name	string	No	Filter by brand, as the `name` field from list-brands.
campaign_name	string	No	Filter by campaign name.
search	string	No	Filter by asset name.
type	string	No	Filter by type: email or landing.
limit	integer	No	Maximum assets to return, 1-25. Defaults to 10.
offset	integer	No	Assets to skip, for pagination. Defaults to 0.

get-asset

Fetch full metadata for a single asset by ID. Use after listing assets to inspect details.

Parameter	Type	Required	Description
asset_id	string	Yes	Asset to retrieve, from list-assets.

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.