MCP server

Malla runs a Model Context Protocol (MCP) server, so AI agents such as Claude can do everything you can do in the web app: edit pages and styles, manage the CMS, tables and forms, upload assets, run server workflows, publish and more. This page lists how to connect, what each tool does and the limits that apply.

Every document edit goes through the same operations as the editor. It is validated the same way, shows up live on the canvas for everyone who has the page open, and you can undo it in your editor.

Connect a client

The server speaks MCP over streamable HTTP at one endpoint:

POST https://<your MCP host>/mcp
Authorization: Bearer mk_…

There is no public MCP address yet: use the MCP host of your Malla installation, for example https://mcp.example.com/mcp. Each request is answered with JSON; the server never opens a stream, so GET /mcp answers 405.

In Claude Code:

claude mcp add --transport http malla https://mcp.example.com/mcp \
  --header "Authorization: Bearer mk_your_key"

In clients that read a JSON config:

{
  "mcpServers": {
    "malla": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer mk_your_key" }
    }
  }
}

The tutorial Build a page with an AI agent over MCP walks through a full session.

API keys and scopes

An agent signs in with a workspace API key. To create one, open a page in the editor, press Ask AI, then the key icon (API keys). Type a name, check Write if the agent should make changes, and press Create. The key starts with mk_ and is shown only once: press Copy and store it in your agent's secret settings.

A key without Write gets This API key is read-only (or the api error read_only_key) when it tries to change something.

• Only workspace owners and admins can create, list and revoke keys.
• A key belongs to one workspace. Sites of other workspaces answer “not found”, even if you are a member there.
• An agent can create keys with the api_keys tool, but only with scopes its own key has. A read key can never create a write key.
• Press Revoke in API keys to stop a key at once.

Roles

The agent can do what your role allows, on each site, exactly as in the web app. See Team and roles.

Tools

Tools come in six families. Ids (sites, pages, nodes, classes) always come from a read tool first: start with list_sites, then list_pages, get_site and get_page.

Read

High-level edits

The same tools as the AI panel. Page tools take siteId and pageId; site tools take siteId.

Editor commands

editor_command runs a command from the editor's menus and shortcuts on a page, with the same cleanup (for example, deleting a node also removes the interactions that target it). Input: { siteId, pageId, command, input }. Nodes are addressed by id.

The tool's input schema lists each command's input shape. A command with nothing to do (for example, deleting only locked nodes) is refused with an error instead of doing nothing silently.

Raw operations

For full control, send the document operations themselves. Each call is one batch of up to 500 operations, applied in order in one transaction. The whole batch is checked against the live document first: if one operation is invalid, nothing is applied and the error names its index.

• page_ops (siteId, pageId, ops): setProp, setStyle, setMeta, insert, insertSubtree, move, delete, setInteraction, setVariable, setQuery, setWorkflow, setStyleBinding.
• site_ops (siteId, ops): setClass, renameClass, setClassStyle, setColorToken, setFontToken, setSpacingToken, setBreakpoints, setSiteVariable, setFormula, addPage, removePage, setPageSeo, setPage.

Each operation has a t field with its type; the tool's input schema describes every field. See The page document for the model behind them.

Refactors

These change the site document and every page that uses the token or class, in one go.

kind is color, font or space.

Domain tools

Everything that is not a document edit is one tool per area, with an action argument. The arguments are { action, <ids>, query?, body? }: ids such as siteId or collectionId are top-level, query holds filters and paging, body holds what you create or change. workspaceId defaults to the key's workspace. Each action is one call of the HTTP API, with the same roles, plan limits and checks.

Notes on a few actions:

• pages create, update and delete also update the editor's page list, like the Pages panel. A component is a page with kind: "component" and no path.
• pages update with seo: null clears the SEO settings; access sets the visitor access rule of a page ({ rule: { $expr }, redirect? }, or null to remove it).
• pages update with a doc replaces the stored document and is refused while the page is open live; edit open pages with the tools above.
• cms update_item and server_workflows update take an optional version: if someone changed the record since, the call answers 409 instead of overwriting their work.
• billing set_workspace_plan and set_site_plan answer a checkout URL when payment is needed. Open it in a browser.
• workspace send_invite answers 501 while invite emails are not set up on the server.

Resources

The server also offers the live documents as MCP resources, as JSON:

resources/list lists every site the key can open and its pages. Subscriptions are not supported: read a resource again to see changes.

Undo

Changes an agent makes with your key reach your open editors as your own undoable steps. Press ⌘Z to take one back. Each change the agent sends is its own step and never merges with your typing. Nobody else can undo it, and your undo never overwrites a change someone made after it.

The agent itself has no undo tool: undo is part of your editor session. To revert a change from the agent, ask it to make the opposite change.

Errors

A tool that fails returns a result with isError: true and a message, so the agent can read it and try again.

• Document tools say what went wrong and, for batches, which operation: for example ops[3]: ….
• Domain tools also return structuredContent.error with the api's status, code, message and details. Common codes: not_found (404, also for sites you cannot open), forbidden (403, role too low), read_only_key (403), plan_limit (402), version_conflict (409, the record changed since you read it), live_document (409, the page is open live), asset_in_use (409), payload_too_large (413).

Problems with the request itself are JSON-RPC errors:

Limits

Plan limits, quotas and AI usage are the same as in the web app. See Plans and billing.

What is not available

A few api routes have no MCP tool on purpose:

• Account and session routes: sign up, log in and out, change password, email verification, password reset and accepting an invite. They manage a person's browser account, so an API key is refused there. Do these in the web app.
• The current user (/auth/me) and the editor's realtime token: a key already acts as you, and MCP writes to the live rooms directly.
• The Stripe webhook: only Stripe calls it.
• The live step stream of a workflow run: it is a WebSocket. server_workflows.test and get_run poll the run instead.
• Replacing a stored page document (PUT /pages/:id/doc): edit documents with the page tools.
• Editor-only commands: selection, zoom, panels, preview, copy, and undo or redo have no effect on a document.