MCP Server v2 | Headless

The new Beefree SDK MCP Server v2 introduces a fully headless architecture. While v1 relies on an active browser-based editor session, v2 handles operations entirely server-side. By removing the dependency on a live editor instance, v2 enables more robust, automated workflows.

The MCP Server v2 is at the moment optimized only for headless use cases. For any implementations requiring a frontend, browser-based editor UI, please continue to use the MCP Server v1. We are actively developing v2 to support all use cases—including frontend integrations—in the near future.

Beefree SDK MCP v2 is currently in an invite-only Closed Beta. Access is restricted to selected partners at this time. If you are interested in joining the waitlist or learning more about the roadmap, please fill in this form or reach out to your CSM.

Use Cases

By shifting to a server-side, headless architecture, Beefree SDK MCP v2 enables high-scale automation and seamless integration with your existing DevOps or marketing stack. Key use cases include:

• Bulk Generation: Programmatically generate unique email variants simultaneously. This is ideal for large-scale campaigns where manual intervention in a browser is not feasible.

• Iterative Variation: Automatically produce a series of design or layout variations based on a single master template. This allows for rapid A/B testing or content experimentation powered entirely by backend scripts or AI agents.

• External Ecosystems: Seamlessly trigger template modifications via third-party automation platforms. By removing the frontend dependency, you can now integrate Beefree SDK actions directly into workflows in tools like n8n, Zapier, Make, Retool, Tines and others.

Try the MCP Server v2 with our Sample Project

See yourself a real-world, fully functioning example with this Beefree SDK MCP v2 sample agent. Simply plug in your preferred provider whether you're team Gemini, OpenAI, or Anthropic, and test 5 different use cases.

Using an email building agent can generate LLM API costs, and it's important to be aware of this. We've included a token counter in the sample project to help you keep track of usage and spending.

You can visit the Beefree SDK MCP v2 example demo GitHub repository to clone and run the sample project.

Comparison v1 vs v2

	v1 (Front-End Editor)	v2 (Headless)
Architecture	Requires a running Beefree SDK Editor in the browser	Fully server-side, doesn't require a running SDK Editor
Session initialization	Editor connects via mcpEditorClient in bee config	Host application provides the Template ID
Session identity	client_id + uid + optional session_id	Template ID
Required client params	client_id, uid (from CSAPI key + headers)	Template ID (x-bee-template-id)
Endpoint	<https://api.getbee.io/v1/editor/mcp>	<https://api.getbee.io/v2/sdk/mcp>
Transport	Streamable HTTP (stateless)	Streamable HTTP (stateful, with session management)
Total tools	40	33

Installation & Setup

CSAPI Integration

MCP v2 continues to use CSAPI as the public API layer for all host application connections. To ensure a seamless transition, the API keys for the MCP v2 endpoint are identical to those used in v1. No action is required from existing beta participants to update or replace their current credentials.

Since the Beefree SDK MCP Server relies on Beefree's CSAPI, it is subjected to the same rate limits. Learn more here.

Getting Started

Authentication

Authentication is handled at the API gateway layer. All requests to the MCP v2 endpoints must include a valid CSAPI key in the authorization header.

Template Management

Before connecting to the MCP, clients need to create a template and obtain a template ID. You can use two endpoints for template lifecycle management:

Create Template Endpoint

POST https://api.getbee.io/v2/sdk/mcp/template

Request body:

{
  "template": { ... },
  "mergeTags": { ... }
}

template	object	Optional. The JSON template to initialize the editing session.
mergeTags	object	Optional. Merge tags to be resolved within the template.

Response: Returns a templateId in the response payload. You must pass this as the x-bee-template-id parameter when connecting to the MCP headless endpoint.

Retrieve Template Endpoint

Fetches the current state of the template. Call this after the MCP session to get the final template with all modifications applied by the AI agent.

GET https://api.getbee.io/v2/sdk/mcp/template/:templateId

MCP Server Implementation

MCP Endpoint

The Beefree SDK MCP v2 server utilizes a Streamable HTTP transport and is accessible via the Beefree API Gateway at:

https://api.getbee.io/v2/sdk/mcp

Required Parameters

To successfully initialize a session, the client must provide a templateId. You can provide the templateId in one of two ways:

1. HTTP Header (recommended)

x-bee-template-id: <template-id>

2. _meta field in the MCP initialize request:

{
  "method": "initialize",
  "params": {
    "_meta": {
      "x-bee-template-id": "<template-id>"
    }
  }
}

End-to-End Workflow

1. Create a template via POST /v2/sdk/mcp/template and receive a templateId

2. Connect to the MCP at /v2/sdk/mcp passing the templateId via x-bee-template-id

3. Use MCP tools to modify the template through the agent

4. Retrieve the final template via GET /v2/sdk/mcp/template/:templateId

Client Compatibility & Security

To ensure a stable and secure connection with the Beefree SDK MCP v2 server, we suggest you use use a supported MCP client.

We strongly recommend reviewing the official MCP Client documentation to understand how clients manage transport, lifecycle, and security.

Security Best Practices:

• Key Protection: Never expose your CSAPI keys in client-side code or public repositories.

• Secure Transport: Always use the provided HTTPS gateway for all MCP interactions to ensure end-to-end encryption.

• Validation: Ensure your chosen client correctly handles the _meta field and authentication headers.

Available Tools

Tool	Category	v1	v2
beefree_add_section	Layout & Structure	✅	✅
beefree_delete_element	Layout & Structure	✅	✅
beefree_update_section_style	Layout & Structure	✅	✅
beefree_update_column_style	Layout & Structure	✅	✅
beefree_get_selected	Editor Sync	✅	replaced*
beefree_get_content_hierarchy	Content Analysis	✅	✅
beefree_get_element_details	Content Analysis	✅	✅
beefree_add_paragraph	Text Content	✅	✅
beefree_update_paragraph	Text Content	✅	✅
beefree_add_title	Text Content	✅	✅
beefree_update_title	Text Content	✅	✅
beefree_add_list	Text Content	✅	✅
beefree_update_list	Text Content	✅	✅
beefree_add_menu	Text Content	✅	✅
beefree_update_menu	Text Content	✅	✅
beefree_add_image	Media & Interactive	✅	✅
beefree_update_image	Media & Interactive	✅	✅
beefree_add_button	Media & Interactive	✅	✅
beefree_update_button	Media & Interactive	✅	✅
beefree_add_social	Media & Interactive	✅	✅
beefree_update_social	Media & Interactive	✅	✅
beefree_add_icon	Media & Interactive	✅	✅
beefree_update_icon	Media & Interactive	✅	✅
beefree_add_spacer	Separators	✅	✅
beefree_update_spacer	Separators	✅	✅
beefree_add_divider	Separators	✅	✅
beefree_update_divider	Separators	✅	✅
beefree_add_table	Tables	✅	✅
beefree_update_table	Tables	✅	✅
beefree_set_email_metadata	Email Settings	✅	✅
beefree_set_email_default_styles	Email Settings	✅	✅
beefree_check_template	Validation & QA	✅	✅
beefree_check_section	Validation & QA	✅	✅
beefree_retrieve_template_facets	Template Catalog	✅	deprecated
beefree_list_templates	Template Catalog	✅	deprecated
beefree_clone_template	Template Catalog	✅	deprecated
beefree_search_stock_images	External Services	✅	✅

*The beefree_get_selected tool has been replaced by a new event callback onSelectElement. This callback is triggered when a user selects either a row or a module in the SDK interface. It is called with an object parameter that contains:

• a type field, which can be either module or row

• a uuid field, which contains the ID of the selected element

This information is meant to be forwarded to your AI Agent that can proactively leverage them in MCP-powered content creation.