",
"message": ""
}
}
```
Common failure scenarios:
* **Builder not ready** — the editor has not finished initializing.
* **API error** — the server-side session creation request failed.
## API-Managed Session
{% hint style="warning" %}
Use this path when [**co-editing**](/beefree-sdk/other-customizations/collaborative-editing.md) **is enabled on your account**.
{% endhint %}
Your host application controls the full session lifecycle: you create the template, connect the agent, and optionally connect the editor — all independently.
### Step 1: Create a Template
Call the template creation endpoint to initialize a new editing session server-side. You receive a `templateId` that you will pass to the agent in the next step.
**Endpoint**
```
POST https://api.getbee.io/v2/sdk/mcp/template
```
**Request body**
| Field | Type | Description |
| --------- | ------ | ----------------------------------------------------------- |
| template | object | Optional. The JSON template to initialize the session with. |
| mergeTags | object | Optional. Merge tags to be resolved within the template. |
```json
{
"template": { ... },
"mergeTags": { ... }
}
```
**Response**
Returns a templateId. You must pass this as the `x-bee-template-id` header (or `_meta` field) when connecting to the MCP endpoint.
### Step 2: Connect Your Agent
Point your MCP client at the v2 endpoint and provide the `templateId` you received in Step 1. You can pass it in one of two ways:
**Option A — HTTP header (recommended)**
x-bee-template-id: <templateId>
**Option B — `_meta` field in the MCP `initialize` request**
```json
{
"method": "initialize",
"params": {
"_meta": {
"x-bee-template-id": ""
}
}
}
```
Use `_meta` strictly for routing metadata, not for tool arguments.
### Step 3: Connect the Editor (Optional)
The editor can join the same session for [real-time collaboration](/beefree-sdk/other-customizations/collaborative-editing.md) alongside the agent. To configure this, use the `join` method in the editor configuration.
```
bee.join(templateId);
```
### Step 4: Retrieve the Final Template
After the agent has finished its work, fetch the modified template from the server:
```
GET https://api.getbee.io/v2/sdk/mcp/template/:templateId
```
This returns the current state of the template with all agent modifications applied.
### Agent Locking Behavior
When an agent shares a session with human users, module locks — the mechanism that prevents two users from editing the same module simultaneously — interact with the agent differently depending on whether it has an assigned owner.
The agent's owner is determined by the `x-bee-user-handle` header passed when the agent connects to the MCP server. If that value matches an existing `userHandle` value in the session, that user becomes the agent's owner.
**Agent without an owner** (`x-bee-user-handle` is absent or does not match any session user):
* The agent ignores all locks and can override any module regardless of who is currently editing it.
**Agent with an owner** (`x-bee-user-handle` matches a session user's `userHandle`):
* The agent can replace locks held by its owner — it acts on behalf of that user.
* The agent honors locks held by other users and will not override modules they are editing.
Assigning an owner is recommended in sessions with multiple real users. It ensures the agent respects the collaborative editing boundaries of other participants.
## Editor Configuration
For the full `editorConfig` reference and co-editing setup, see the [Co-Editing Integration Guide](/beefree-sdk/other-customizations/collaborative-editing.md).
The following fields are relevant to MCP sessions across both integration paths:
```
{
"username": "Display name shown for this user in the editor",
"userHandle": "Unique identifier for this user",
"userColor": "#hex color for the user's presence indicator"
}
```
`userHandle` behavior
* If `userHandle` is provided, it is used as the user's identity in the co-editing session.
* If `userHandle` is omitted in an editor-managed session, the editor auto-generates one as `mcp-{randomUUID}`, ensuring a unique identity without requiring the host to manage it.
* In an API-managed session, `userHandle` is also used to match an agent's owner via the `x-bee-user-handle header` (see [Agent locking behavior](#agent-locking-behavior)).
## Host Callbacks: `onMcpSessionChange`
The **editor-managed session** exposes a set of callbacks that serve as the co-editing equivalents of `onSessionChange` and `onSessionStarted`.
Event Payload When it fires SESSION_STARTED{ type, templateId }Connection successfully established USER_JOINED{ type, change, sessionData }A new user enters the session USER_LEFT{ type, change, sessionData }A user leaves the session SESSION_ENDED{ type, templateId }The session stops
## Server-Side Session TTL
These values define how long session data persists on the backend, independently of any client-side timeouts.
**API-managed session**
| Users still active | 33h, reset on every keep-alive or write | Never, as long as keep-alives arrive |
| ------------------------------- | --------------------------------------- | ------------------------------------ |
| Last user leaves | Set to 24h | 24h after last user disconnects |
| Idle (no writes or keep-alives) | Last set value (up to 33h) | At TTL expiry |
**Editor-managed session**
| Users still active | 1h, reset on every keep-alive | Never, as long as keep-alives arrive |
| ------------------------------- | ----------------------------- | ------------------------------------ |
| Last user leaves | Set to 5 min | 5 min after last user disconnects |
| Idle (no writes or keep-alives) | Last set value (up to 1h) | At TTL expiry |
{% hint style="info" %}
The editor-managed session also enforces a hard **10-minute client-side timeout** that disconnects the editor regardless of server-side TTL. This is the most common expiry path in practice.
{% endhint %}
### Security
* **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.
* **Validation**: Ensure your MCP client correctly handles the `_meta` field and authentication headers.
We strongly recommend reviewing the official [MCP Client documentation](https://modelcontextprotocol.io/docs/learn/client-concepts) for guidance on transport, lifecycle, and security.
## Code Examples
In the [Beefree SDK MCP v2 demo repository](https://github.com/BeefreeSDK/beefree-sdk-mcp-v2-example-demo), you can find:
* An example of an editor-managed session
* An example of an API-managed session
* A Code Mode example
## Code Mode (Research Preview)
{% hint style="info" icon="gear-complex" %}
*Code Mode is an experimental feature currently in research preview.*
Code Mode is an alternative way to interact with the Beefree SDK MCP Server that significantly reduces token consumption.
Instead of exposing 33 individual tools — each with a full parameter schema sent on every turn — Code Mode exposes a single tool that accepts a TypeScript script. Your agent writes one script that performs all operations in a single round trip: creating sections, adding content, and setting styles.
### Code Mode Endpoint
```
https://api.getbee.io/v2/sdk/mcp/codemode
```
In internal benchmarks across five models and three email complexity levels, Code Mode reduced total token consumption by 67–97%, with most results in the 85–95% range.
Use Code Mode when your agent makes many sequential tool calls to reduce API costs and latency. The same CSAPI key and authentication apply — no additional credentials are required.
**Please note**: Code Mode requires your agent to generate valid TypeScript. Implement error handling to gracefully handle partial failures.
{% endhint %}
## Migrating from v1
The v1 approach used `mcpEditorClient.enabled = true` in the `beeConfig` object to expose the editor to the MCP server, combined with the `/v1/sdk/mcp` endpoint and `x-bee-uid / x-bee-mcp-session-id` headers for routing.
In the current MCP server version (v2), the session is identified by a `templateId` rather than a `uid` + session pair, and the endpoint has moved to `/v2/sdk/mcp`. The same CSAPI key credentials continue to work — no new credentials are required.
**Key changes**
| | v1 (deprecated) | Current MCP (v2) |
| ---------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Architecture | Requires a running Beefree SDK Editor in the browser | Session can be created via the Headless API or by the editor via `startMcpSession()` |
| Session identity | `client_id` + `uid` + optional `session_id` | `templateId` |
| Endpoint | `https://api.getbee.io/v1/sdk/mcp` | `https://api.getbee.io/v2/sdk/mcp` |
| Routing header | `x-bee-uid, x-bee-mcp-session-id` | `x-bee-template-id` |
| Editor config | `mcpEditorClient: { enabled: true }` | Not required for agent connection |
| Select element | `beefree_get_selected` | `onSelectElement` callback ([more details here](https://app.gitbook.com/o/2zoWGxtV7bjhbwBdjGPS/s/8c7XIQHfAtM23Dp3ozIC/~/edit/~/changes/572/mcp-server/tools-and-capabilities#get-the-context-of-selected-element)) |
Remove the mcpEditorClient block from your beeConfig, update your MCP endpoint URL, and switch to x-bee-template-id for routing. Then choose the integration path that fits your account setup.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.beefree.io/beefree-sdk/mcp-server/installation-and-setup.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.