MCP Server

Overview

Bricks ships a built-in MCP (Model Context Protocol) server. Any MCP-capable AI assistant — Claude on claude.ai, Claude Code, MCP Inspector — can connect to your Bricks account and, from a chat, do everything the editor does:

Browse your workspace and organizations
Create folders, courses, microlearnings and question banks
Add, edit, move and delete lessons and all 44 brick types with their full configuration
Configure the content theme (colors, fonts, cover, custom CSS)
Export to SCORM, web or PDF, publish share links, manage snapshots, duplicate and translate

Authentication uses OAuth against your Bricks user: the assistant never sees your password and you can revoke access at any time. Everything the assistant does is limited to what your user can do — organization membership and roles are enforced on every call.

Connecting

The MCP endpoint lives at:

https://<your-bricks-host>/api/mcp

claude.ai

Go to Settings > Connectors > Add custom connector
Paste the endpoint URL
Complete the sign-in and authorize the access

Claude Code

claude mcp add --transport http bricks https://<your-bricks-host>/api/mcp

The first call opens the browser to sign in and authorize.

Clients register themselves automatically (OAuth dynamic client registration) — there is nothing to configure server-side.

How the tools work

The server exposes a curated set of top-level tools (workspace browsing, content/lesson CRUD, bricks, theme, export, file uploads, duplicating a content) plus three meta-tools that unlock the full catalog:

browse_workspace covers three needs: browse one folder level, search the whole scope by title/name with query, or map the entire folder tree in a single call with recursive: true (every folder with its parentId). To clone a content — lessons, bricks and assets — as a template, use duplicate_content (top-level); duplicate_lesson does the same for a single lesson.

Beyond authoring, the catalog also covers: full trash lifecycle for folders (restore_folder, delete_folder_permanently) and batch content ops (batch_move_contents, batch_trash_contents); moving a content across organizations (update_content with targetOrganizationId); version management (rename_snapshot, delete_snapshot); and searching licensed stock libraries and importing an asset under a content (search_stock_images/import_stock_image, search_stock_icons/import_stock_icon). Media the model generates itself is uploaded with request_asset_upload — the server does not expose generative-AI tools.

Meta-tool	Purpose
`find_tools`	Search the whole catalog by keyword (publishing, snapshots, translation, templates, trash…)
`tool_schema`	Get the input schema of any catalog tool
`run_tool`	Execute a catalog tool by name

For bricks, list_brick_types lists every type grouped by category (text, media, collections, questions, games) with a "when to use" hint to pick the right one for a teaching goal, and get_brick_type_schema returns the exact authoring shape (with an example) for each one — rich text is authored as plain HTML.

Choosing the right brick

To help the assistant pick the most appropriate brick, list_brick_types carries per-type "when to use" guidance, and the bricks://guides/brick-selection resource is a full selection guide (intent → recommended bricks). Both are generated from the same source, so they never drift, and both work in any MCP client.

Uploading files

Bricks content uses files — images, video, audio, subtitles, downloadable attachments, custom fonts, embed packages — and the MCP can upload them. The binary never travels through the MCP (no base64): the tool mints a short-lived presigned upload URL and the client sends the file straight to storage, out of band.

The flow for a brick asset:

Call request_asset_upload with the target contentId, the kind (image | video | audio | subtitle | attachment | font) and the file's contentType (e.g. image/png). Each kind has a MIME allowlist, so a mismatched type is rejected up front.
The tool returns { uploadUrl, path, curlCommand, expiresAt }. Upload the file — run the returned curlCommand (replacing <local-file> with the real path) or PUT the bytes to uploadUrl with the exact Content-Type. The URL expires after 15 minutes.
Put the returned path into the brick's media field via add_brick / update_brick (imagePath, videoPath, audioPath, filePath, posterPath, subtitlesPath, front*/back*/…), or into the theme via update_theme (cover image, logo, custom woff2 fonts).

list_content_assets returns the files already uploaded for a content, so an existing asset can be reused instead of uploaded again.

Embed bricks (a self-contained index.html + assets package) use request_embed_upload: upload each file of the package under the same folderId, then set the returned embedFolderPrefix on the EMBED brick. These land in the public embeds bucket with their Content-Type pinned.

Imports follow the same presigned pattern:

Articulate Rise — start_rise_import (upload the .zip) → confirm_rise_import → poll get_rise_import until completed to read the created contentId.

Instructional-design document import is intentionally not exposed over MCP: its parse step depends on browser-side extraction in the app, so the flow can't complete headlessly — do it in the app's Instructional Design editor.

All upload tools authorize the target content (scope + organization membership) before signing, and the server builds the storage key — a client never supplies a raw path.

Live collaboration

Brick edits made through MCP are merged through the collaboration server: if someone has the lesson open in the editor, they see the assistant's changes appear in real time, and nobody's work is overwritten.

Destructive actions

Deleting content, lessons or bricks, resetting themes, restoring snapshots and emptying the trash all require an explicit confirm: true. Without it, the tool answers with a preview of what would happen so the assistant can ask you first.

Operations notes

The OAuth authorization server is part of the app (Better Auth mcp plugin); tokens live in the oauth_* tables and expire after 1 hour (refresh tokens: 7 days).
Brick edits require the collab server's internal API: set COLLAB_HTTP_URL (e.g. http://bricks_yjs:1234) and a shared COLLAB_INTERNAL_SECRET in both services. Without them, MCP falls back to writing lesson state directly to the database — fine for single-user setups, unsafe while someone edits the same lesson.
The endpoint is rate-limited per user (120 requests/minute).
When billing is enabled, MCP access is gated by the plan's apiAccess feature, exactly like API keys.