soleil-clusters-mcp

MCP server for Soleil Clusters — read andbuild visual boards from Claude, or any Model Context Protocol client.

Connect it

The hosted server is a URL, and it signs you in by itself:https://clusters.soleilpictures.com/api/v1/mcp

No token. The first call comes back 401 with a pointer to the OAuth metadata;your client registers itself, opens a browser, and you approve the connection onone screen. If you do not have an account yet you get one there.

Claude (claude.ai or the desktop app): Settings, Connectors, add a customconnector, paste the URL.
ChatGPT: Settings, Apps, Advanced settings, turn on developer mode; thencreate an app and paste the URL.
Claude Code: claude mcp add --transport http soleil-clusters https://clusters.soleilpictures.com/api/v1/mcp
Cursor: Add to Cursor
VS Code: Add to VS Code
Windsurf and any other client that takes a remote server: add this to itsMCP config (Windsurf calls the URL field serverUrl).

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

No account

https://clusters.soleilpictures.com/mcp works with no account. Anyone can tryit from Claude or ChatGPT: the assistant builds a draft cluster, and you keep itwith the keep link it hands back (an email address and a code). Signed in, thesame URL works as your account.

Local, for files on your machine

Install this package only for the one tool the hosted server cannot offer:upload_file, which reads a file from your own disk — including large mediathat will not fit through an assistant's message.

npx soleil-clusters-mcp login

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

login runs the same OAuth flow from your terminal: it opens a browser, catchesthe callback on a loopback port, and stores the credential in~/.config/soleil-clusters/credentials.json (mode 600). It refreshes itselfafter that. npx soleil-clusters-mcp logout removes it.

Prefer a token? SOLEIL_API_TOKEN still works and takes precedence — mint oneunder Settings → Connections. SOLEIL_API_BASE overrides the host.

What it can do

31 tools: search and fetch, read, write and export boards and docs, look at a whole board or theimages on it, show a board to you as it is laid out (drawn in the chat where the app can draw it),create and change boards and cards in bulk, lay a board out as justified rows or masonry, share it bylink, read, add and resolve comments, list tags and tag cards, import from URLs, attach identifiersfrom other systems, move and delete things, and read the audit log. Five prompts: make a moodboardfrom a brief, review a board, organise one, write a treatment from one, and plan an import.

Version 3.0 folded fifteen tools into others (get_board into read_board, update_card intoupdate_cards, and so on). Calling an old name says which tool does it now.

Full reference, limits and per-app steps: https://clusters.soleilpictures.com/docs/mcp

Permissions

This server holds no credentials of its own and implements no permissions. Itforwards your token, and the API resolves it to your own session — so an agentreaches exactly what your account reaches, and the database refuses anythingelse.

Three scopes: read, write, delete. Deleting is separate from writing onpurpose, so an agent can be allowed to build without being allowed to destroy.login asks for read write and never for delete.

Whatever you connect is listed under Settings → Connections → Connected apps, withwhat it has done and a button to disconnect it.

Development

src/tools.js and src/server.js are generated fromboards/src/lib/mcpTools.js and boards/src/lib/mcpServer.js, which the hostedserver also uses. Edit those, then:

npm run sync

A test in boards/ fails if either copy is stale, so the two transports cannotdrift apart.

Publishing

server.json describes this server for theMCP Registry. Its name and themcpName in package.json must match, and the com.soleilpictures namespacecomes from a DNS TXT record on the apex of soleilpictures.com.

npm publish --access public
mcp-publisher login dns --domain soleilpictures.com --private-key <hex>
mcp-publisher publish

soleil-clusters-mcp