# 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 89 tools, and hand the result
> to a human as a proposal to accept or reject.

## MCP server

- [MCP endpoint](https://paintbox.erikbethke.com/api/mcp): Streamable HTTP (JSON-RPC 2.0), protocol version 2025-06-18
- Auth: OAuth 2.1 with PKCE. MCP clients discover it from the 401 on tools/call
  ([protected resource metadata](https://paintbox.erikbethke.com/.well-known/oauth-protected-resource/api/mcp)) and send
  the user to a PaintBox approval page; there is no token to paste. From a terminal: `scripts/paintbox login`.
- Tools: 89 (82 editor tools, 7 session tools)
- Skill tools are per-user and dynamic: a signed-in tools/list also carries each of the user's pinned skills, up to 10, as skill_<slug> with that skill's own input schema. They are not in the tool count. list_skills and run_skill reach every skill, pinned or not.
- Install: `claude mcp add --transport http paintbox https://paintbox.erikbethke.com/api/mcp`

## Workflow

1. Authenticate: add the server with no header; the client signs in through the browser on the first tools/call.
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 [llms-full.txt](https://paintbox.erikbethke.com/llms-full.txt).

- Layers (24): set_layer_styles, rasterize_styles, convert_to_smart_object, replace_smart_object_source, 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_clipping, set_mask_from_selection, clear_mask, merge_down, merge_group, merge_visible, flatten
- Selection (8): set_selection, clear_selection, invert_selection, modify_selection, select_all, grow_selection, named_selection, select_color_range
- Paint (7): create_pattern, erase_selection, fill, fill_gradient, fill_shape, add_vector, rerender_vector
- Adjustments (3): set_adjustment, create_adjustment_layer, apply_preset
- Filters (1): apply_filter
- Transform (7): set_transform, align_nodes, distribute_nodes, set_crop, resize_canvas, resample_document, flip
- Asset production (3): trim_to_content, remove_background, create_document_from_asset
- Export (5): set_export_spec, delete_export_spec, apply_export_preset, rename_document, export_bundle
- Recipes (5): make_cutout, make_favicon_package, uniform_asset, apply_proposal_headless, sync_develop_settings
- Generate (4): generate_image, request_image_edit, restyle_layer, generative_expand
- History (2): compare_revisions, get_history
- Variants (5): list_variants, create_variant, create_variant_grid, switch_variant, compare_variants
- Inspection (4): describe_document, inspect_layer, inspect_channel, get_headless_job
- View (1): set_guides
- Control (3): apply_edit, ask_clarification, finish
- Session (7): list_documents, set_active_document, set_document_context, list_skills, describe_skill, run_skill, get_proposal

## Discovery surfaces

- [Agent hub](https://paintbox.erikbethke.com/for-agents): interactive landing page for agents
- [MCP manifest](https://paintbox.erikbethke.com/.well-known/mcp.json): machine-readable MCP server and tool list
- [Agent card (A2A)](https://paintbox.erikbethke.com/.well-known/agent-card.json): Agent2Agent capability card
- [agents.json](https://paintbox.erikbethke.com/.well-known/agents.json): agents.json discovery manifest
- [OpenAPI 3.1](https://paintbox.erikbethke.com/openapi.json): OpenAPI 3.1 schema for the REST surface
- [llms.txt](https://paintbox.erikbethke.com/llms.txt): this summary
- [llms-full.txt](https://paintbox.erikbethke.com/llms-full.txt): full tool reference