Try it outBook a demoCookbookRequest a Tutorial

Beefree SDK MCP Server (Beta)

Join the Beta program and get early access to the Beefree SDK MCP Server

Our MCP Server is currently in Beta and only accessible to a selected number of early access customers. If you're interested in joining the Beta, or if you'd like us to notify you when the tool is available to everyone, please let us know.

I'd love to join the Beta → Beefree SDK Team

Introduction

The Beefree SDK MCP Server allows you to connect your AI Agents with the Beefree SDK. It makes key functionality of the Beefree SDK — the Editor, our Templates, or the Check API — accessible for AI agents, opening up new ways to bring agentic design directly into your application. For example, you can build agents to…

  • Create designs from scratch (so your users don’t have to)

  • Edit and improve existing designs with the power of AI

  • Build AI-powered QA workflows

…and so much more!

Important:

  • The MCP requires a live and correctly configured editor session to function properly. Ensure your Beefree SDK editor is running with MCP enabled before attempting to use any tools.

  • We’re providing access to the MCP server that makes key Beefree SDK functionality accessible to AI agents. However, providing the agent is the responsibility of the Host Application. If you don’t have your own agent yet, consider this sample application using a PydanticAI agent that you can get up and running in under 5 minutes.

How MCP Works

Model Context Protocol (MCP) is an open protocol that standardizes how clients (like IDEs and agent runtimes) connect to servers that expose "tools," "resources," and "prompts." Think of it as a USB-C for AI: one way to plug many tools into many agents without bespoke integrations.

At a protocol level:

  • Base protocol & lifecycle. Clients and servers speak JSON-RPC 2.0, negotiate capabilities, and then exchange requests until shutdown. Initialization (initialize → initialized) must happen first.

  • Tools. Servers list tools via tools/list and invoke them via tools/call. Each tool has a name and JSON Schema for inputs (and optionally outputs).

  • Metadata (_meta). A reserved envelope for passing extra routing/context (not tool args), namespaced as the spec requires. We'll use it to pass Beefree session routing when not using HTTP headers.

  • HTTP transport & auth. MCP commonly runs over Streamable HTTP; authorization (when used) relies on standard HTTP bearer tokens (OAuth-style). Clients must send Authorization: Bearer and may also send the negotiated MCP-Protocol-Version header; SDKs typically handle this for you.

Core Architecture and Components

  • CSAPI – Public API entry point for agents. Authorizes requests and forwards them to the MCP server.

  • MCP Server – Implements MCP and exposes tools that operate on SDK editor instances.

  • Beefree SDK Ecosystem – Editor, Template Catalog API, Check API.

Technical Diagram

AI Agent → MCP Client → CSAPI → MCP Server → Beefree SDK Ecosystem
    ↓           ↓         ↓         ↓              ↓
  Natural    JSON-RPC   Auth &   Tool Calls    Editor
 Language   Protocol   Routing   Processing   Instance

Key Capabilities

The Beefree SDK MCP Server provides dozens of tools that are divided into different categories. These tools allow agents to build, modify, and validate email designs in Beefree.

Structure and Layout Tools

These tools control the foundational architecture of your email, allowing you to create sections, manage layouts, configure columns, and set global styles.

  • beefree_add_section - Add new email sections with column structure

  • beefree_delete_element - Delete elements from email templates

  • beefree_update_section_style - Modify section styling

  • beefree_update_column_style - Modify column styling

  • beefree_get_content_hierarchy - Retrieve design structure

  • beefree_get_element_details - Get element information

  • beefree_get_selected - Get currently selected element

  • beefree_set_email_metadata - Set email subject and preheader

  • beefree_set_email_default_styles - Set default email styles

Content Block Tools

These tools add and modify individual content elements within your email, including text, images, buttons, and other interactive components.

  • Text blocks: beefree_add_title, beefree_add_paragraph, beefree_add_list

  • Media blocks: beefree_add_image, beefree_add_icon

  • Interactive blocks: beefree_add_button, beefree_add_social

  • Structural blocks: beefree_add_spacer, beefree_add_divider

  • Each with corresponding update tools

Template Catalog

These tools provide access to Beefree's library of 1,500+ pre-built email templates, enabling you to browse, search, and clone professional designs as starting points.

  • beefree_list_templates - Search and filter templates

  • beefree_retrieve_template_facets - Get template categories and tags

  • beefree_clone_template - Clone existing templates

Validation & QA Tools (Checker)

These tools verify email quality by checking for accessibility issues, missing alt text, color contrast problems, broken links, and other best practice violations.

  • beefree_check_template - Template validation

  • beefree_check_section - Section validation

External Services

These tools integrate with third-party services to enhance your email designs with external resources and assets.

The Beefree SDK MCP server uses the Pexels API.

  • beefree_search_stock_images - Retrieve stock images via Pexels API integration. Search for high-quality, royalty-free images to use in your email designs. Returns image URLs, descriptions, and attribution information.

With each of the tools in the categories above, agents can build complete workflows: from inserting content, to structuring layouts, to validating designs against accessibility and best practices.

Reference Sample Project

Reference the following sample implementation we made showcasing an mcp agent example. You can use this for inspirational and implementation purposes. The following image shows the UI of the sample project when you run it locally.

Reference the Beefree SDK MCP example demo repository to clone and run the sample project. A complete working implementation is available in this repository. The sample showcases:

  • PydanticAI agent integration with MCP

  • Real-time streaming chat interface

  • Beefree SDK editor with MCP enabled

  • WebSocket-based communication

See the project's README.md for setup instructions and implementation details.

Setup

This section discusses three key steps you need to take to successfully set up the Beefree SDK MCP Server.

These steps are:

  1. Enable the MCP editor client in the Beefree SDK Editor

  2. Plug the MCP Server into your agent

  3. Route requests to the right editor instance

Step 1: Enable the MCP editor client in the Beefree SDK Editor

What this is: A configuration step in your host app that initializes a Beefree SDK editor instance with MCP enabled.

How it works: The editor exposes itself to the MCP server by setting mcpEditorClient.enabled = true. Optionally, sessionId helps distinguish multiple editor instances for the same user.

How to use: Add mcpEditorClient to your existing beeConfig object before mounting the editor.

// Beefree SDK Editor configuration
const beeConfig = {
  container: "beefree-sdk-editor",
  mcpEditorClient: {
    enabled: true,                 // Must be true to enable MCP
    sessionId: "custom_session_id" // default: "default_session_id"
  }
};

Tip: Every editor instance is identified by the Client_id and UID pair. Use sessionId to ensure the right editor instance receives tool calls when the same user has multiple editor instances open (for example, you could have two editor instances tied to the same UID and Client ID but on two different browsers or PCs).

Step 2: Plug the MCP Server into your Agent

What this is: Point your MCP-capable client at the Beefree MCP endpoint with valid auth.

How it works: Your client performs MCP's initialize/initialized handshake over HTTP, then calls tools.

How to use: Send requests to the endpoint below; ensure you use an MCP-compatible CSAPI key.

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

Use the HTTP header:

Authorization: Bearer <MCP-compatible CSAPI key>

Note: A normal CSAPI key will not work. There won't be any self-service for the duration of the closed beta, so the only way to get access is to ask us to enable MCP access on an existing key or to give you a new MCP-enabled one.

Step 3: Route requests to the right editor instance (UID/session)

What this is: Targeting information so the server knows which user's editor session to control.

How it works: Provide UID (required) and sessionId (optional) either via HTTP headers or in the MCP _meta envelope.

How to use: Pick one of the two options below.

Option A — HTTP headers

x-bee-uid: <USER_UID>
x-bee-mcp-session-id: <SESSION_ID> (optional)

Option B — _meta object in the tool call

{
  "_meta": {
    "x-bee-uid": "<USER_UID>",
    "x-bee-mcp-session-id": "<SESSION_ID>"
  }
}

Note: Use _meta strictly for metadata/routing, not for tool arguments.

What the MCP Actually Does

This section discusses what the MCP actually does, and provides a deeper look into what it looks like under the hood.

  • Initialize – sends initialize with its protocol version and capabilities; server responds with its capabilities. Client then emits notifications/initialized.

  • Discover tools – calls tools/list to see what the Beefree server offers (e.g., beefree_add_section, beefree_list_templates).

  • Call tools – uses tools/call { name, arguments } to perform an operation. Results return as text/structured content per spec.

  • Auth and headers – keeps the Bearer token on each request; Beefree SDK may add MCP-Protocol-Version automatically.

Security and Requirements Recap

  • Endpoint: https://api.getbee.io/v1/sdk/mcp

  • Auth: Bearer token (MCP-compatible CSAPI key) in Authorization header. Tokens must be sent on every HTTP request.

  • Routing: Provide x-bee-uid and optional x-bee-mcp-session-id either as headers or inside _meta. Use _meta only for metadata.

  • Editor setup: mcpEditorClient.enabled = true (and optional sessionId).

  • MCP handshake: Clients must complete initialize/initialized before calling tools; clients handle capability negotiation and protocol versioning.

  • Tool calls: Use tools/call with the Beefree tool name + arguments (per tool schema).

Content Services API MCP Endpoint

MCP Protocol Endpoint

post

Main endpoint for Model Context Protocol communication. Supports initialize, tools/list, and tools/call methods.

Authorizations
Header parameters
x-bee-uidstringRequired

User identifier for routing requests to the correct editor instance

x-bee-mcp-session-idstringOptional

Optional session identifier for distinguishing multiple editor instances

Body
jsonrpcstring · enumRequired

JSON-RPC version

Possible values:
idone ofRequired

Request identifier

stringOptional
or
integerOptional
methodstringRequired

Method name

paramsobjectOptional

Method parameters

Responses
200

Successful JSON-RPC response

application/json
post
POST /v1/sdk/mcp HTTP/1.1
Host: api.getbee.io
Authorization: Bearer YOUR_SECRET_TOKEN
x-bee-uid: text
Content-Type: application/json
Accept: */*
Content-Length: 177

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "clientInfo": {
      "name": "beefree-mcp-client",
      "version": "1.0.0"
    }
  }
}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "beefree-mcp-server",
      "version": "1.0.0"
    }
  }
}

Troubleshooting

  • 401 Unauthorized: Ensure you're using an MCP-compatible CSAPI key (not a normal key) and the Authorization header is attached.

  • Wrong editor session: Make sure x-bee-uid is present; add x-bee-mcp-session-id if multiple editor instances are open for the same user.

  • Client can't discover tools: Confirm the client completed initialization; tools/list should work afterward.

Beefree SDK MCP - Frequently Asked Questions

What is the Beefree SDK MCP Server?

It's an adapter that lets AI agents (via the Model Context Protocol) create, modify, and validate email designs using the Beefree SDK ecosystem (Editor, Template Catalog API, Check API). It exposes a set of tools agents can call.

What is MCP in one sentence?

MCP is an open protocol (think "USB-C for AI") that standardizes how clients connect to servers, exposing tools, resources, and prompts over JSON-RPC.

What is the purpose of the Beefree SDK MCP Server beta?

This will let teams explore how AI agents can integrate directly with the Beefree SDK ecosystem, designing, customizing, and validating emails programmatically, while we gather feedback and refine the experience.

Which plans can access the MCP?

At this stage, access to the MCP is invite-only as part of the early access beta. It's open to all plans, excluding free. Customers interested in joining can ask their Customer Success Manager (CSM) or fill out the waitlist form. We'll review requests and grant access to selected customers. Broader availability and plan-based access will be announced after the beta concludes.

What happens to my access if I'm not selected for the beta?

If you're not granted access right away, you'll remain on the waitlist, and we'll notify you as soon as spots open or the program expands.

Who should participate in this beta?

  • Product teams exploring AI-driven content workflows

  • Developers building MCP-capable clients (e.g., IDEs, agents, assistants)

  • Teams that want to streamline design inside automated pipelines

Can I use the Beefree SDK MCP in production?

We recommend testing and prototyping only during the beta. While stable, APIs and access policies may change before general availability, and this version of the MCP server may differ from the final release.

Is the MCP feature complete? What are the current limitations?

The MCP integration is still a work in progress, and access is limited to selected customers in our early access program. While you can already use MCP to perform many email builder operations, there are some important limitations to keep in mind:

  • Not all content blocks are supported yet

  • Some block properties and advanced configuration options are not covered

  • Functionality may change as we iterate during the beta

We encourage you to explore the available tools and share your feedback—your input will help us prioritize and close gaps as we continue to expand the MCP's capabilities.

What kind of feedback are you looking for?

We're looking for all sorts of feedback, including design capabilities and implementation:

  • How easy it is to discover, understand, and use the tools available in the MCP catalog: For example, whether tool names are clear, the arguments make sense, and the set of tools feels complete for your workflow

  • Coverage (are there tools you need that aren't exposed yet?)

  • Performance of Template Catalog + Check API in real workflows

  • Gaps in documentation or developer experience

If you have any feedback, please share it with your CSM or email [email protected].

Does the MCP also support the Landing Page Builder or the Popup Builder?

The beta currently focuses on the Beefree SDK Email Builder. Support for the Landing Page and Popup Builder is limited, but it will be considered for future updates.

What is the applicable use policy?

During the beta, you may use the MCP Server and its tools for development, prototyping, and evaluation. Access is subject to Beefree SDK's standard Terms of Service. Abuse or production-scale misuse will result in suspension of access.

Is my data secure when using MCP?

Yes. MCP calls are authenticated with secure keys, tied to your user/session, and handled in accordance with Beefree SDK's security and data policies.

I have questions, feedback, or a bug to report. Who should I contact?

Please contact your Beefree SDK Customer Success Manager (CSM) or email [email protected]. We encourage feedback during beta, and your input directly shapes product improvements.

Are the MCP calls free of charge?

Yes. Calls to the MCP Server and temporary free access to the Template Catalog API and Check API are free of charge during the beta. After the beta period, normal pricing and entitlements may apply. Pricing information will be announced prior to general availability.

PreviousCreate a Custom Form Builder in Beefree SDK

Last updated

Was this helpful?