MCP Server

Bannx exposes a Model Context Protocol (MCP) server so AI assistants (Cursor, the Cursor CLI agent, Claude Desktop, and other MCP clients) can find templates, create templates, and render pages on your behalf.

Unlike the Unsplash and AWS S3 integrations, MCP isn't connected from Settings → Space → Integrations. Instead, you configure it in your MCP client using a Bannx API key.

Authentication

The MCP server uses the same API keys as the REST API. Create one under Settings → Space → Developers, then pass it as a Bearer token on every MCP request.

No separate MCP credential is required.

Endpoint

POST https://your-app.bannx.app/mcp
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

The server uses stateless Streamable HTTP (MCP spec). Only POST is supported.

Client configuration

Cursor

Add to your MCP settings (.cursor/mcp.json or Cursor Settings → MCP):

{
  "mcpServers": {
    "bannx": {
      "url": "https://your-app.bannx.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "bannx": {
      "url": "http://127.0.0.1:3001/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor CLI agent

The Cursor CLI agent reads the same config files as the IDE: a global ~/.cursor/mcp.json and an optional project-level .cursor/mcp.json. Add bannx under mcpServers (use type: "http" for the remote transport):

{
  "mcpServers": {
    "bannx": {
      "type": "http",
      "url": "http://127.0.0.1:3001/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Start a new CLI session so the config reloads, then run /mcp to confirm bannx and its tools are listed. Swap the URL to https://your-app.bannx.app/mcp for production.

Claude Desktop (remote HTTP)

Use the same url and headers shape if your client supports remote Streamable HTTP MCP servers.

Tools

ToolDescription
whoamiAuthenticated space id, user id, and credit summary
list_public_templatesBrowse the public template gallery (search, category, page, perPage)
list_templatesList templates in your space
get_templateGet a template and its pages by templateId
create_templateCreate or update a template (optionally with pages)
update_templateUpdate an existing template by templateId (partial; include pages to replace all pages)
list_template_pagesList pages for a template
render_pageRender a pageId to png, svg, webp, or pdf with optional tweaks
list_brandsList brands in the space (find a brandId)
get_brandGet a brand by id including its tokens
create_brandCreate a brand with tokens (liveTokens, draftTokens, …)
update_brandUpdate a brand's tokens by brandId (partial; token objects replaced wholesale)
list_icon_collectionsList Iconify icon sets on the icon server
search_iconsSearch icon names by keyword (query, optional prefix / prefixes)
list_icon_collectionPaginated names within one set (prefix, optional search)

Icons in templates

For UI icons, use layer type svg with src set to an Iconify name (ph:house, mdi:email-outline). Do not use emoji in text layers or hand-written inline SVG when an Iconify name exists. Discover names with list_icon_collections, search_icons, or list_icon_collection — the MCP tools proxy the self-hosted icon server.

Brand tokens

Brands hold reusable design tokens (colors, typography, logos, images, icons, copy) that templates reference as brand.<group>.<key> (e.g. brand.colors.primary). Manage them with create_brand and update_brand; use list_brands to find a brandId and get_brand to read current values before merging.

Tokens are grouped objects, e.g. liveTokens: { "colors": { "primary": "#6366f1" }, "typography": { "heading": "Space Grotesk" } }. Rendering prefers liveTokens, then draftTokens, then tokens, so put render-ready values in liveTokens. Each token object passed to update_brand replaces the stored one wholesale, so fetch and merge first. External image URLs are re-hosted to the space automatically. Managing brands requires an API token associated with a user.

Example workflow

  1. Call list_templates or list_public_templates to find a template.
  2. Call get_template or list_template_pages to obtain a pageId.
  3. Call render_page with pageId, format, and optional variable tweaks.
  4. Use the returned file.url from the render response.

Renders consume credits from the API key's space, same as POST /api/render.

Security notes

  • Treat the API key like a password. Anything configured with it can read and render your space's templates and consume credits.
  • Avoid committing a real key in a project-level .cursor/mcp.json. Prefer the global ~/.cursor/mcp.json, or use a placeholder and fill it in locally.
  • Revoke a key anytime from Settings → Space → Developers.