For Agents

PaintBox MCP

The first fully agentic Photoshop-class editing experience. External AI agents compose image edits through 60 MCP tools and submit proposals for human review.

Quick start

claude mcp add --transport http paint-box https://paintbox.erikbethke.com/api/mcp --header 'Authorization: Bearer YOUR_TOKEN'

Get your token from the editor: Account → MCP Connection.

Workflow

1. Auth

POST /api/auth/refresh with your refresh token. Get a 15-min access token.

2. Initialize

POST /api/mcp — JSON-RPC "initialize". Returns a session ID header.

3. Discover

Call list_documents to see what the user has open in their browser.

4. Load

Call set_active_document with a document ID. Context is loaded from the DB.

5. Edit

Call editor tools: set_selection, fill, create_layer, set_opacity, etc.

6. Finish

Call finish with an interpretation explaining what you did and why.

7. Deliver

Call get_proposal. This deposits the proposal in the editor's inbox.

8. Review

The user sees the proposal in their browser with Accept / Reject buttons.

Tools (60)

Layers

set_opacity, set_visibility, set_blend_mode, rename_node, reorder_node, create_layer, duplicate_layer, import_raster, add_text, set_text, group_layers, ungroup_layers, set_locked, set_mask_from_selection, clear_mask, merge_down, merge_group, merge_visible, flatten

Selection

set_selection, clear_selection, invert_selection, modify_selection, select_color_range

Paint

erase_selection, fill

Adjustments

set_adjustment, create_adjustment_layer

Filters

apply_filter

Transform

set_transform, set_crop, resize_canvas, resample_document, flip

Asset production

trim_to_content

Export

set_export_spec, delete_export_spec, apply_export_preset

Recipes

make_cutout, make_favicon_package, uniform_asset

Generate

generate_image, request_image_edit, generative_expand

History

compare_revisions, get_history

Variants

list_variants, create_variant, create_variant_grid, switch_variant, compare_variants

Inspection

describe_document, inspect_layer

Control

apply_edit, ask_clarification, finish

Session

list_documents, set_active_document, set_document_context, get_proposal

Discovery surfaces

MCP server
Streamable HTTP

JSON-RPC 2.0 endpoint — 56 editor tools + 4 session tools. Requires Bearer JWT.

Discovery manifest with tools, workflow, and install command.

Agent card
A2A JSON

Skills, interfaces, and provider metadata.

OpenAPI spec
OpenAPI 3.1

Machine-readable REST API description.

llms.txt
Markdown

LLM-readable summary of the tool surface and workflow.

Every tool with its description and parameters, generated from the registry.

One index of the MCP endpoint, its auth, the OpenAPI spec and these docs.

Discovery URLs for AI crawlers.

PaintBox is built by Erik Bethke / Million on Mars. The MCP interface is the first fully agentic loop for a Photoshop-class editor — agents compose, humans review.