Soleil Clusters

Make and browse visual mood boards from AI chat: pictures from links, notes, palettes and docs in sections, drawn inline. Hosted with OAuth, or local via npx.

View on soleilpictures.com

Hosted MCP Server

npx add-mcp 'https://clusters.soleilpictures.com/api/v1/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

MCP server

Soleil Clusters ships an MCP server exposing the API as tools an AI assistant can call directly. Point a client at https://clusters.soleilpictures.com/api/v1/mcp and approve it in the browser; it signs you in over OAuth, so there is no token to paste. With no account, https://clusters.soleilpictures.com/mcp lets an assistant build a draft cluster you keep with a link. Run it locally with npx only for files on your machine. It holds no credentials of its own, so an agent reaches exactly what your account reaches.

The MCP server puts Soleil Clusters in reach of Claude and any other Model Context Protocol client, so an assistant can read and build boards directly. An AI without it can still make you a board: it writes the board into a make-it link, which shows the board before anyone signs in.

If you are weighing up whether that is useful rather than how to wire it up, the AI mood board maker page covers what an assistant can actually do with a board — and what it deliberately does not do, which is invent images.

What it is

A layer over the REST API. It holds no credentials and implements no permissions of its own — it forwards whatever credential you connected with, so everything about the authorization model applies here unchanged. An OAuth access token and a personal access token resolve to the same thing: your own session, under ordinary row-level security.

Connect it

Every app below uses the same address, https://clusters.soleilpictures.com/api/v1/mcp. It signs you in itself, so there is no token to paste: the first call comes back 401 with a pointer to our OAuth metadata, the app opens a browser, and you approve the connection on one screen. If you do not have an account yet you get one on that screen, since signing in is a single email box.

Afterwards the connection is listed under Settings → Connections → Connected apps, where you can see what it has done and disconnect it.

Coding apps connect on an account's first day too, as Claude and ChatGPT do: Claude Code, Codex, Cursor, VS Code and Windsurf, and the npm package below. While an account is under 72 hours old, a connected app's token answers 300 requests an hour instead of 1000.

Claude

In claude.ai or the desktop app, open Settings → Connectors, add a custom connector, and paste the address. Claude then draws a cluster in the chat when you ask to see one.

ChatGPT

In ChatGPT, turn on developer mode under Settings → Apps → Advanced settings, then create an app from Settings → Apps and paste the address. On a Business or Enterprise workspace an admin may need to allow developer mode first. ChatGPT draws a cluster in the chat too.

Claude Code

claude mcp add --transport http soleil-clusters https://clusters.soleilpictures.com/api/v1/mcp

Then run /mcp inside Claude Code to sign in. It answers with a link to the cluster rather than drawing it.

Cursor

Add to Cursor installs it in one click. Or put this in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "soleil-clusters": {
      "url": "https://clusters.soleilpictures.com/api/v1/mcp"
    }
  }
}

VS Code

Add to VS Code installs it in one click. The same install as a link to the app itself is vscode:mcp/install?%7B%22name%22%3A%22soleil-clusters%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fclusters.soleilpictures.com%2Fapi%2Fv1%2Fmcp%22%7D. Or put this in .vscode/mcp.json, which uses servers, not mcpServers:

{
  "servers": {
    "soleil-clusters": {
      "type": "http",
      "url": "https://clusters.soleilpictures.com/api/v1/mcp"
    }
  }
}

Windsurf

Add this to ~/.codeium/windsurf/mcp_config.json. Windsurf calls the address field serverUrl:

{
  "mcpServers": {
    "soleil-clusters": {
      "serverUrl": "https://clusters.soleilpictures.com/api/v1/mcp"
    }
  }
}

Any other app

An app that takes a remote server by URL needs only the address:

{
  "mcpServers": {
    "soleil-clusters": {
      "type": "http",
      "url": "https://clusters.soleilpictures.com/api/v1/mcp"
    }
  }
}

If your app cannot do OAuth, a personal access token still works exactly as before:

"headers": { "Authorization": "Bearer undefined…" }

For a team rather than a person, use a service account — a credential that does not stop working when someone leaves.

Only Claude and ChatGPT draw the cluster in the chat (below). In the others, show_board and every answer end with the cluster's link.

Local — for files on your machine

The hosted address cannot read your disk. Install the npm package only for the one tool that needs it, upload_file, which reads a file from your computer and uploads it, including large ones like video that cannot fit through an assistant's message.

npx soleil-clusters-mcp login

It runs the same OAuth flow: it opens a browser, catches the callback on a port on your own computer, and stores the credential in ~/.config/soleil-clusters/credentials.json, refreshing it as it nears expiry. npx soleil-clusters-mcp logout removes it; the connection is then still listed under Settings → Connections → Connected apps, to disconnect for good. Then point your app at the package:

{
  "mcpServers": {
    "soleil-clusters": {
      "command": "npx",
      "args": ["-y", "soleil-clusters-mcp"]
    }
  }
}

Prefer a token? SOLEIL_API_TOKEN takes precedence over a stored sign-in:

"env": { "SOLEIL_API_TOKEN": "undefined…" }

SOLEIL_API_BASE overrides the host. With neither a sign-in nor a token the server exits at startup, telling you to run login, rather than running in a state where every call fails.

upload_file is the local server's one extra tool. Everything else is identical: both servers are built from one registry, so a tool cannot exist on one and not the other.

No account: drafts

https://clusters.soleilpictures.com/mcp works with no account, so anyone can try Clusters from Claude or ChatGPT. When the person is not signed in, create_boards starts a draft cluster: up to 25 cards, with a draft key (dk_…) that the assistant passes as draft on every later call, and a keep link it gives the person. Every answer repeats both, and after a call that changed cards says how much is spent: Cards used 12 of 25.

A draft lasts 30 days after its last change, then is deleted. Each draft may make 300 requests an hour.
A card link in a draft's answers opens that card on the keep page: the page shows the cluster read only, selects the card and brings it into view.
A tool that needs an account, such as one that reads the person's own clusters, answers that they need to sign in. Signed in, the same address works as the account.
A draft can't be shared until it is kept.

Keeping takes an email address and the 6-digit code sent there; the cluster then belongs to that account, a new one or one that already exists, and the keep link opens nothing more. See keep links.

Discovery

A client finds the server without being told anything but the address. A call to /api/v1/mcp with no credential comes back 401 with a WWW-Authenticate header whose resource_metadata points at our OAuth metadata; a call with a token that is wrong or expired adds error="invalid_token", so a client can tell "sign in" from "sign in again". A web browser sent to the address is redirected to this page.

The server describes itself, without any sign-in, in MCP's standard server card at /api/v1/mcp/server-card (the same card is at /mcp/server-card): its name, title, version, the two addresses and the protocol versions they accept. /.well-known/ai-catalog.json lists it, so a client that knows only the domain finds it. Directories that scan a server they can't sign in to read the older card at /.well-known/mcp/server-card.json (and /.well-known/mcp.json), which adds that it signs in over OAuth, its capabilities and its tools with their titles and annotations. Any other path under /.well-known/ that we don't serve answers a JSON 404, not a page.

Protocol versions

Both servers accept 2026-07-28 · 2025-11-25 · 2025-06-18.

2026-07-28 is the revision that removed the initialize handshake: protocol version, client identity and client capabilities now travel in _meta on every request, and there is no session to establish or keep alive. Nothing needs to be configured to use it — the server decides per request:

A request whose params._meta carries io.modelcontextprotocol/protocolVersion is served under that revision.
An initialize request is served under the older, session-based rules.

So a client built on the current official SDK — which tops out at 2025-11-25 — connects exactly as it always did, and a newer one gets the newer behaviour from the same URL. If you ask for a version the server does not implement, it answers -32022 and lists the ones it does, so a client can retry rather than guess.

server/discover returns the supported versions, the capabilities and the server identity in a single call. On the local server it doubles as the probe that tells a client which era it is talking to, because stdio has no HTTP status code to branch on.

Under 2026-07-28 the hosted transport also requires the mirrored request headers — MCP-Protocol-Version, Mcp-Method, and Mcp-Name for tools/call and prompts/get. They must agree with the request body; a mismatch is refused with -32020 rather than served, because a proxy is allowed to route on the header without reading the body, and two components acting on different values is exactly the confusion the rule exists to prevent. Older clients send no such headers and are not held to them.

Two things that changed with the revision and may surprise you: ping is gone (a stateless protocol has no connection to keep alive), and a POST body must be a single message — JSON-RPC batching is no longer accepted. Both still work for clients connecting under an older version.

Protocol errors

These are JSON-RPC error codes, distinct from the REST API's error codes — a client branches on the number.

Code	Means	HTTP
`-32700`	The body was not JSON	400
`-32600`	Not a valid single JSON-RPC message	400
`-32601`	No such method	404
`-32602`	Bad params — also an unknown tool or prompt	200
`-32603`	The server failed	200
`-32020`	A mirrored header disagrees with the body	400
`-32021`	The request needs a capability the client did not declare	400
`-32022`	Unsupported protocol version — the answer lists the supported ones	400

A tool that runs and fails is not an error here. It returns a normal result with isError: true and the API's own sentence in the content, because a model that reads "this token cannot delete" can correct itself, while one that gets a transport error only learns that something broke. The sentence ends with the API's error code in brackets, [insufficient_scope] or [limit_reached], so an agent can branch on more than the wording, and both servers word the same refusal the same way.

Arguments are checked against the tool's input schema before anything runs. A call that does not fit comes back the same way, as isError: true, naming each problem by its path:

Invalid arguments for add_cards:
- cards[1].kind must be one of note, image, link, doc, video, audio, pdf, file (got "text")
- boardId is not an argument here — did you mean board_id?

Some near misses are read the way they were meant rather than refused: null for an optional argument means "not given", a number or true / false sent as text is read as one, a list sent as JSON text is parsed, and an enum value in the wrong case is matched.

Choosing scopes for an agent

The three scopes (delete · read · write) exist mainly for this. "Can add cards to my moodboard" and "can delete my moodboard" are different levels of trust to place in a language model, and they are separate grants.

Give it	For
`read`	Research, summarising, answering questions about your boards
`read` + `write`	Building boards, adding references — the usual choice
all three	Housekeeping and cleanup agents

An agent without delete gets a 403 naming the missing scope rather than quietly failing.

Tools

Orientation and finding things

Tool	Input
`whoami`	— · the account, its scopes (`read`, `write`, `delete`), whether it is a service account (confined to one workspace), and the workspaces it can see, with the ids `workspace_id` takes
`search`	`query` (min 2 chars), `kind?` (`board` \| `card`), `workspace_id?`, `limit?` (default 20 of each kind, up to 100), `offset?` · boards and cards by their words, and pictures by what is in them, boards first, each result `{ id, title, url }` with, for a card, an excerpt (for a picture found by what is in it, `in_picture`) and the name of its board — the shape ChatGPT asks of a search tool; each `id` is one `fetch` reads. Pictures added in the last couple of hours have no description yet and are found by title until it is ready: when some are waiting, the answer carries `undescribed_pictures` (the count, capped at 50, which then means "or more") and a `note` saying to try again in a few minutes or look with `view_board`
`fetch`	`id` — `board:<board id>`, `card:<board id>:<card id>`, `doc:<board id>:<card id>` (`:<page id>` for one page), or a link from the app · one board, card or doc as text to read, `{ id, title, text, url, metadata }`, up to 40,000 characters; a doc's `metadata.pages` carry each page's `hash`, and a described picture says what is in it
`list_boards`	`workspace_id?`, `parent?` (`"root"` for top level), `since?`, `cursor?`, paging, `response_format?` · one level at a time, each board with its link; with `depth?` (up to 20) a whole hierarchy in one call, at most 500 boards; with `deleted?` the boards that can still be restored
`resolve_identifier`	`scope`, `value` — find something by an id from another system

Reading

Tool	Input
`read_board`	`board_id`, `response_format?`, `full?`, `include?`, `source?`, `since?`, paging · the board with its link, fields and how much of the card allowance is used, its groups, and a page of its cards, a described picture with `in_picture`; `format?` (`json` \| `omc`) for the whole board as one document instead
`view_board`	`board_id`, `limit?` (default 12, up to 24), `cursor?`, `card_ids?` (up to 4, at a larger size) — look at a board: its overall picture, then its images in reading order, each named by its card
`show_board`	`board_id` — show the person the board as it is laid out: drawn in the chat where the host can draw it (ChatGPT, Claude). Every answer also outlines the board, its sections and a few card titles each (a section with more says `+N more`), and ends with a line giving its link to pass on
`list_comments`	`board_id`, `status?` (`open` \| `resolved` \| `all`), `limit?` (up to 200), `cursor?` — the board's comment threads, those inside its docs and notes with the text they are on
`list_tags`	`workspace_id?`, `board_id?`, `tag?` (a name or an id), `limit?` (up to 500) — a workspace's tags, the tags on one board, or with `tag` everything carrying it
`list_audit`	`since?`, `cursor?` — recent writes and image fetches

Writing

Tool	Input
`create_boards`	`boards[]` — one, or up to 500, each `{ name, workspace_id?, parent_board_id?, view?, identifiers?, props? }`; `workspace_id?`, `on_conflict?` · each board comes back with its `url`; with no `parent_board_id` it becomes a project at the top of the workspace, where New cluster puts one, and the answer's `placement` offers up to 12 of your clusters to ask where it belongs
`add_cards`	`board_id`, `cards[]` — up to 1000, each with its section by name in `group?`, `groups?` (the sections' order and colours), `on_conflict?` · a note shows its `title` as its heading and is sized to its text, a `palette` is made from `swatches`; sections and their notes take colours of their own unless given one; leave `x`, `y`, `w` and `h` out and the server places and sizes everything — 3 or more cards in one call are always laid out as `auto` lays them out (a `layout` names another), and `x` / `y` place only one or two; a note is never shorter than its text — see Cards
`import_urls`	`board_id`, `urls[]` — each an https address as a plain string, or `{ url, title?, group? }`; `titles?` by position, `group?` for those that name none, `layout?`, `dry_run?` — bring reference in from the web, into a section by name if given; a title becomes the picture's caption; safe to re-run
`upload_image`	`board_id`, `data` (base64), `content_type`, optionally `file_name`
`upload_file`	`board_id`, `path` — local server only; handles large files
`write_doc`	`board_id`, `pages[]` — up to 50, each `{ title?, markdown }`; `title?` for a new doc, placed in free space or at `x?` and `y?`, in a section by name with `group?` (made if missing), at the top-left ahead of the sections with `position: "top"`, and sized with `w?` and `h?`; or `card_id` and `parent_page_id?` to add pages to one · a doc written from Markdown
`create_group`	`board_id`, `name`, `color?`, `shape?` — say a set of cards is one thing; `add_cards` can simply name the section instead. Given no colour, a group takes a named one
`add_comment`	`board_id`, `body`, and `card_id?`, `group_id?`, `x?` and `y?`, or `reply_to?`; `quote?` and `page_id?` with a doc's `card_id` — a comment in the person's name, placed beside what it is about, on words in a doc, or a reply

Changing

Tool	Input
`update_boards`	`boards[]` — up to 100, each a `board_id` and any of `name`, `view`, `parent_board_id` (`null` for the top level), `identifiers`, `props` · each board is changed on its own, and the answer lists the boards updated and why any failed
`update_cards`	`board_id`, `cards[]` — up to 1000, each an `id` and any field `add_cards` takes — `group` by name or `group_id` (empty to ungroup), `z`, `rotation`, `section_header`, `swatches`, `identifiers`, `props`, and any kind; `groups?` · a note's new title or body is written into it, and its height follows; the answer lists each card compactly, as `add_cards` does
`edit_doc_page`	`board_id`, `card_id`, `page_id`, and `markdown` with `page_hash`, or `edits[]` (up to 50), or `title` · marked destructive, since a rewrite takes words away; the board goes to Version history first
`arrange_board`	`board_id`, `layout?`, `card_ids?`, `order?` (card ids to put first, in order; those in no section come first, at the top-left), `dry_run?` — lay a board out or tidy it: `auto` unless another layout is named — columns, the pictures leading, or blocks, whichever suits the board — which also brings notes made earlier up to date
`move_cards`	`from_board_id`, `to_board_id`, `card_ids[]`
`tag_cards`	`board_id`, `card_ids[]` (up to 200), `add[]?`, `remove[]?` (tag names or ids, up to 10 each) — put tags on cards or take them off, as the Tag menu does; a new name makes the tag
`resolve_comments`	`board_id`, `comment_ids[]` (up to 50), `resolved?` — resolve threads, or reopen them with `false`; lists any refused, with why
`restore_board`	`board_id`
`share_board`	`board_id`, `include_subboards?` — the board's view-only link, made only when it has none; call it only when the person asks to share
`unshare_board`	`board_id` — revokes the board's view-only links this account may revoke

Deleting — requires the delete scope

Tool	Input
`delete_cards`	`board_id`, `card_ids[]` — one, or up to 1000
`delete_board`	`board_id`

Card kind is audio, doc, file, image, link, note, palette, pdf, video, defaulting to note.

add_cards once lacked audio and pdf while the REST API took both, so an agent could not create the two kinds Soleil Scout makes from a text message. Both work now, and a file_key from upload_file is what any of video, audio, pdf or file is built from. palette joined them so a moodboard's colours are a palette card rather than hex codes in a note.

Every tool carries a title and annotations — readOnlyHint, destructiveHint, idempotentHint, openWorldHint — which is what a client reads when deciding whether a call needs confirming. They are structured, so unlike a warning in a description they actually participate in that decision.

Read-only: whoami, search, fetch, list_boards, resolve_identifier, read_board, view_board, show_board, list_comments, list_tags and list_audit. They change nothing and can be repeated freely.
Destructive: update_boards, update_cards, edit_doc_page, unshare_board, delete_cards and delete_board, since each can take something away (words, a link, cards, a cluster).
Open-world: import_urls, which fetches addresses on the web, and share_board, which makes a link anyone can open. The rest act only on the person's own clusters.

Answers to the card writers are compact. add_cards, update_cards and arrange_board answer with each card's id, kind, title, section, position and size, and its url where it points somewhere, not the card whole; read_board has the rest.

Errors say what to do next. A failed call returns the reason in a sentence and then the next step (connect again with a wider permission, wait and retry, use list_boards to find the id, pass the draft key), ending with the API's error code in brackets.

Renamed in 3.0

Version 3.0 folded fifteen tools into the ones above, so an assistant has fewer, clearer tools to choose between. Calling an old name answers -32602 with renamed_to in its data, naming the tool that does it now, and the message says how; an assistant still holding the old list corrects itself from that.

Before 3.0	Now
`list_workspaces`	`whoami`, which lists the workspaces
`board_tree`	`list_boards` with `depth`
`list_deleted_boards`	`list_boards` with `deleted: true`
`get_board`, `list_groups`, `get_metadata`	`read_board`, which carries the board, its fields, its capacity and its groups
`export_board`	`read_board` with `format`
`view_image`	`view_board` with `card_ids`
`list_images`	`read_board`; the Images API still lists stored files
`create_board`	`create_boards` with one entry
`rename_board`, `move_boards`	`update_boards`
`set_metadata`	`update_boards` or `update_cards`, with `props` and `identifiers`
`update_card`	`update_cards` with one entry
`delete_card`	`delete_cards` with one id

The local package's 2.x releases carry their own copy of the tools, so they keep the old names until they are updated.

Prompts

Starting points a person picks by name (slash commands in Claude Code), each a short plan in the tools' own words:

Prompt	Does
`moodboard`	`brief`, `workspace_id?` — builds a finished cluster from a brief: pictures from the web, a palette, notes and a short treatment, laid out, with its link
`review_board`	`board_id` (an id, the cluster's name, or a link from the app) — says what a board is going for, what is missing and what to add next; changes nothing
`organize_board`	`board_id` (id, name or link) — proposes groups, or boards inside it, without moving anything until asked
`treatment`	`board_id` (id, name or link) — writes a treatment as a doc on the board, grounded in what is on it
`import_plan`	`workspace_id`, `listing` — turns a file listing into a plan of boards and cards, with identifiers so it can be re-run

A prompt that asks for a cluster takes its id, its name, or a link copied from the app. A name is looked up among the person's clusters, an exact match preferred; if two clusters answer to it, or none does, the prompt says so in a sentence rather than guessing.

Completions. The server declares the completions capability: while a person types a cluster for one of those prompts, completion/complete returns their own clusters' names that start with what they have typed, a short list.

describe_board is review_board since 3.0.

Adding an image

Two calls:

upload_image with the base64 bytes and a content_type, plus file_name to keep the file's own name — returns an image_key (and the file_name it kept)
add_cards with {"kind": "image", "image_key": "…", "file_name": "…"}

Images are limited to 25 MB through the API and are charged to the board owner's storage. See Images API.

Writing a doc

write_doc with the pages in Markdown — returns the doc's url and each page's id and hash
edit_doc_page to change a page afterwards: edits for a few words, or the whole page as markdown with its page_hash. fetch with doc:<board id>:<card id>:<page id> reads a page and its current hash.

A rewrite keeps every block it didn't change, comments and all, and is refused if the page changed since it was read. A picture goes in only from a file already on the board. The Docs API has the details.

The board, in the chat

show_board opens the board inside the conversation, in the hosts that draw MCP Apps, which are ChatGPT and Claude (Cursor, VS Code and Windsurf don't, and the answer's link is how the person gets to the cluster there): the cluster laid out as it is on its canvas, its groups named, its pictures, notes, palettes and docs where they sit. Clicking a card picks it, as on the canvas, and Ask about these puts a message in the chat naming what was picked, with the ids the assistant needs to look closer. Open in Clusters opens the board itself, and View all shows it full screen, to zoom and pan.

The view is one page, which hosts read with resources/read as text/html;profile=mcp-app. Its address names its build, ui://clusters/board-<build>.html, so a host that kept an older copy asks for the new one, and an older address, ui://clusters/board-v1.html included, opens the page as it is now. In ChatGPT the view also draws from what ChatGPT hands its apps directly, so the board shows even when ChatGPT's side of MCP Apps doesn't answer. It loads nothing but the board's pictures, from https://clusters.soleilpictures.com, at addresses that work for an hour (GET /boards/:id/canvas); open the conversation again later and it asks for fresh ones. Every word on the board is drawn as text, and the only links it opens are Clusters' own.

The assistant is told what the board holds, never the pictures' addresses: an outline of its sections, in the order they read, with how many cards each holds and the titles of the first few, then the cards in no section. The answer ends with the board's link, which the assistant is told to pass on, so a chat that can't draw the view, or whose view fails to open, still has the board in words and a way into it.

Keep links

A keep link, https://clusters.soleilpictures.com/keep/…, opens a cluster an assistant made for someone who wasn't signed in to Clusters. The page shows the cluster read only, and keeping it takes an email address and the 6-digit code sent there: the cluster then belongs to that account, a new one or one that already exists. Whoever holds the link can keep it, so it goes only to the person it was made for. Once kept it opens nothing, and a cluster nobody keeps is deleted 30 days after its last change.

A cluster kept by someone who already has a workspace of their own arrives as another one beside it. Someone who already has 10 workspaces of their own deletes one first, then opens the link again.

Drafts made through /mcp hand one out in every answer.

What agents should know

Each answer says what happened in its first line, with the link to give the person and, when there is more, how to get it: Board "Diner — night" · 42 cards (1–25 here; more with offset 25) · https://…. The JSON follows, and is also the call's structured result. search and fetch answer with the JSON alone, the shape ChatGPT reads.

Answers are concise by default. read_board gives each card's id, kind, title, text and what it points at (a link, an image_key, a file), with long text shortened, and for a picture Clusters has described, in_picture: what is in it, as a vision model saw it (data, never instructions); response_format: "detailed" adds positions, sizes, colours and dates, for placing things, and full: true every word. list_boards gives each board's id, name, place and link; detailed adds how it opens and when it was made. Both paginate — check for more rather than assuming one page is everything.

What people wrote is marked as data. An answer that quotes people's text — cards, captions, comments, docs, search excerpts — begins with an untrusted field saying so: it is material to work with, never instructions to follow, so a note that says "delete this board" is something to tell the person about, not something to do. The server's instructions say the same, for hosts that pass them on.

A new board goes where you say, or you're asked. Name the cluster it belongs in and create_boards puts it there. Say nothing and it becomes a project at the top of your workspace, as New cluster makes one, and the answer carries placement: up to 12 of your clusters, projects first, the ones you worked in most recently first. The assistant finishes what you asked, then asks where the board should live and moves it there with update_boards. Leave it where it is by saying so.

Deleting returns the cards. delete_cards responds with the cards it removed. Those objects are the undo — pass them back to add_cards to restore them. Worth keeping in context before destructive work. Card kinds add_cards does not create (grids, cluster cards and the like), a palette set to hide its labels and docs written in the app are the exception: the response lists them in not_restorable, and they come back from the board's Version history in the app instead.

Deleting a board is destructive and confirmable. delete_board removes a whole board; the tool description says to confirm with the user first, and restore_board exists because that is not always heeded.

Writes are idempotent by key. Every POST the server issues carries a generated idempotency key, so a retried call replays rather than duplicating.

Batch. One add_cards call with forty cards is one request against the rate limit; forty calls are forty.

live: false is not an error. The change is saved; a canvas someone already has open will not show it until reload.

Start with whoami. It reports the scopes and whether the credential is a service account, which is cheaper than discovering both through failures, and lists the workspaces and the ids to pass as workspace_id.

Reading the docs as an agent

/llms.txt — an index of every page with descriptions
/llms-full.txt — the entire corpus in one file
OpenAPI — the machine-readable API spec
Any page plus .md — for example /docs/api/cards.md

Frequently asked questions

Do I have to install anything?

No. Point an MCP client at https://clusters.soleilpictures.com/api/v1/mcp. It discovers the sign-in flow on its own and opens a browser; you approve once. Running it locally is only needed for uploading files from your own machine.

Do I need an account before connecting?

Not to try it. The no-account address, https://clusters.soleilpictures.com/mcp, lets an assistant build a draft cluster of up to 25 cards, which you keep with a link and an email address. The hosted address, /api/v1/mcp, needs you signed in: it opens the sign-in itself, and the sign-in screen is a single email box that creates the account if there isn't one.

Which apps does it work with?

Claude, ChatGPT, Claude Code, Cursor, VS Code, Windsurf, and any app that takes a remote MCP server by URL. Coding apps connect on an account's first day too, under the new-account hourly limit.

Do I still need a personal access token?

Only for a client that cannot do OAuth, or for your own scripts. Assistants that speak current MCP handle it themselves.

Does the MCP server have its own permissions?

No. It forwards whatever credential you connected with — an OAuth access token or a personal access token — to the same API, so it inherits your account's permissions exactly. A credential without the delete scope cannot delete.

How do I stop an agent deleting things?

Deleting is a separate grant from writing precisely so an agent can be allowed to build without being allowed to destroy, and it is never granted by default. Over OAuth, simply do not approve it; with a token, mint one without the delete scope.

Can an agent upload a video?

Only the local server can, with upload_file, because the file has to be read from a disk. The hosted one handles images with upload_image.

Can the assistant show me the board in the chat?

In ChatGPT and Claude, yes. show_board draws the cluster inside the conversation, laid out as it is on its canvas; you can pick cards and ask about them, or open it in Clusters. Cursor, VS Code, Windsurf and other apps don't draw it: the assistant gives you the cluster's link instead.

Is it the same set of tools either way?

Yes, apart from upload_file, which needs a filesystem. Both servers are built from one registry so they cannot drift apart, though the local package's 2.x releases still have the tool names from before 3.0.

Machine-readable: /docs/mcp.md · /llms.txt
What changed and when: /changelog