MCP server

https://mcp.scenebrew.com/v1/mcp is a remote Model Context Protocol server over the public API. It exposes the pipeline and everything around it as primitives: your agent orchestrates, Scenebrew runs the work. There is no "Scenebrew agent" tool — the host agent is the agent. (Scenebrew's own conversational agent is reachable too, as create_session and send_session_message.)

Connect

claude mcp add --transport http scenebrew https://mcp.scenebrew.com/v1/mcp \
  --header "Authorization: Bearer sbk_live_…"

Any host that speaks Streamable HTTP with a static bearer header works the same way — Codex, Cursor, Zed and others take a JSON entry:

{
  "scenebrew": {
    "type": "http",
    "url": "https://mcp.scenebrew.com/v1/mcp",
    "headers": { "Authorization": "Bearer sbk_live_…" }
  }
}

One name per action

Tool names are the API's operation ids: create_scene on REST is create_scene as a tool, with the same arguments and the same result. Every tool call carries a Scenebrew id as an ordinary argument — a project_id for creates and lists, an entity id (scene_id, session_id, operation_id, …) as returned by earlier calls — which is how the 2026-07-28 revision prescribes cross-call state. There is no transport-level session.

Three places the two surfaces differ, by design: the REST endpoint run_scene_step is one tool per step (generate_scene_sdd, generate_scene_peg, generate_scene_blueprint, generate_scene_model, plus the declared-but-not-yet-available revise_scene_sdd, revise_scene_peg, analyze_scene_image, decorate_scene); generate_library_entity is one tool per kind (generate_theme, generate_design, generate_recipe, generate_asset); and the three membership links collapse into link_library_entities / unlink_library_entities.

Core tools

The library toolset (?toolsets=core,library) adds list/create/get/update/delete_{theme,design,recipe,asset}, link_library_entities (an asset binds into a recipe slot), unlink_library_entities, list_design_types, list_recipe_types, preview_recipe, export_theme, add_asset_file, replace_asset_file, and the four generate_* tools.

export_theme(theme_id) hands a theme to an engine: it wraps GET /v1/themes/{id}/export and returns url (the /v1 route — fetch it with your API key to write the .sbe file), content_hash (the container's hash, the same whatever the attachment mode), filename, media_type, size_bytes, and the parsed container itself when it is at most 2 MiB (inline: false skips it). attachments, roles and slots are the endpoint's; every attachment URI inside points back at /v1/assets/{id}/files/{role}?sha256=… on the same API.

add_asset_file(asset_id, file_id, role) fills an empty file role of an existing asset from an uploaded file (see Library → Add a file to an asset); the same bytes again are a no-op, different bytes on a filled role are refused with the recipes and themes using the asset named in the error. replace_asset_file(asset_id, role, file_id, if_match) replaces deliberately, with if_match the digest the role holds now (files[role].sha256); a stale value is a 412 naming current_sha256. There is no force flag.

Every tool carries _meta.version (SemVer of the tool surface), _meta.billed on the AI ones, _meta.runs_as: "operation" on the ones that start work, and read-only / destructive / idempotent annotations, so a host can show what a call will do and cost before making it.

Long-running tools

Every tool that starts work — the steps, create_session, send_session_message, the generate_* tools — returns an operation and takes a wait argument (default 300 seconds). The call stays open with progress notifications and returns the operation as it stands: terminal, or still running once wait has passed. wait: 0 hands the queued operation back at once; get_operation(operation_id, wait) polls it, cancel_operation stops it, list_operations(target_id) is a scene's or session's history.

A failed operation is a normal result with status: "failed" and error.code — the same catalogue as Errors. Tool errors are reserved for the call itself: 401, 403 insufficient_scope (create a Read & write key), 404 (unknown id or another workspace's), 409 missing_sdd / missing_peg / missing_blueprint / step_in_progress (a step called out of order), 422, 501 not_implemented.

Resources

For hosts that surface MCP resources, the reads are also available as URIs:

Tool and resource lists are cacheable for an hour; instance reads are not cached.

Authorization details

• Without a key the server answers 401 with WWW-Authenticate: Bearer error="invalid_token", resource_metadata="…/.well-known/oauth-protected-resource/v1/mcp".
• The RFC 9728 metadata names Scenebrew's authorization server, so OAuth-capable hosts fail cleanly today and will work unchanged once the OAuth 2.1 flow ships. Until then, bearer keys are the way in.

Versioning

/v1 names a surface generation and is not bumped for protocol revisions, tool evolution (_meta.version per tool) or compatible changes. Tools 0.2.0 replaced the fifteen tools of 0.1.0 (create_sdd, build_peg, generate_layout, brew_scene, get_turn, …) with the names above; the old names are gone, not aliased; 0.4.0 keyed recipe assets by operator slot; 0.5.0 added export_theme; 0.6.0 added add_asset_file and replace_asset_file. A /v2 appears only for a breaking change to the auth/transport generation, and runs side by side with /v1 for at least twelve months.