# PaintBox: the agentic, Photoshop-class image editor

> PaintBox is a browser image editor where every edit is a tool call. A mouse, a voice, a
> terminal and an agent all drive the same canvas through the same typed operations. External
> AI agents connect over MCP, compose edits with 60 tools, and hand the result
> to a human as a proposal to accept or reject.

## MCP server

- Endpoint: https://paintbox.erikbethke.com/api/mcp
- Transport: Streamable HTTP (JSON-RPC 2.0), protocol version 2025-06-18
- Auth: Bearer JWT. Get a refresh token in the editor (Account > MCP Connection), then
  POST /api/auth/refresh for a 15-minute access token.
- Tools: 60 (56 editor tools, 4 session tools)
- Install: `claude mcp add --transport http paint-box https://paintbox.erikbethke.com/api/mcp --header 'Authorization: Bearer YOUR_TOKEN'`

## Workflow

1. Authenticate: POST /api/auth/refresh with your refresh token.
2. Initialize: JSON-RPC "initialize" on /api/mcp.
3. Discover: list_documents shows what the user has open.
4. Load: set_active_document loads the editor's last pushed state.
5. Edit: call editor tools (set_selection, create_layer, add_text, set_opacity, ...).
6. Finish: call finish with one sentence describing what will change.
7. Deliver: call get_proposal. It deposits the proposal in the editor's inbox.
8. The user sees it in their browser and clicks Accept or Reject.

## Tool categories

Every tool, with its description and parameters, is in https://paintbox.erikbethke.com/llms-full.txt.

- Layers (19): 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 (5): set_selection, clear_selection, invert_selection, modify_selection, select_color_range
- Paint (2): erase_selection, fill
- Adjustments (2): set_adjustment, create_adjustment_layer
- Filters (1): apply_filter
- Transform (5): set_transform, set_crop, resize_canvas, resample_document, flip
- Asset production (1): trim_to_content
- Export (3): set_export_spec, delete_export_spec, apply_export_preset
- Recipes (3): make_cutout, make_favicon_package, uniform_asset
- Generate (3): generate_image, request_image_edit, generative_expand
- History (2): compare_revisions, get_history
- Variants (5): list_variants, create_variant, create_variant_grid, switch_variant, compare_variants
- Inspection (2): describe_document, inspect_layer
- Control (3): apply_edit, ask_clarification, finish
- Session (4): list_documents, set_active_document, set_document_context, get_proposal

## Discovery surfaces

- Agent hub: https://paintbox.erikbethke.com/for-agents
- MCP manifest: https://paintbox.erikbethke.com/.well-known/mcp.json
- Agent card (A2A): https://paintbox.erikbethke.com/.well-known/agent-card.json
- agents.json: https://paintbox.erikbethke.com/.well-known/agents.json
- OpenAPI 3.1: https://paintbox.erikbethke.com/openapi.json
- Summary: https://paintbox.erikbethke.com/llms.txt
- Full reference: https://paintbox.erikbethke.com/llms-full.txt