Connect an external AI
ClipSpaces speaks MCP (Model Context Protocol), so an AI assistant you already use — Claude Code, Claude Desktop, or any other MCP client — can read and edit your boards from wherever you work. You choose exactly which spaces it reaches, and you can cut it off at any time.
What it can do
Once connected, your assistant can:
- See your spaces — the ones you picked, and no others.
- Read a whole board — every card, what it says, and how the cards connect to each other.
- Build on it — add notes, sticky notes, shapes, frames and links; reword and resize what’s already there; draw connections; move, duplicate and delete cards; tidy the layout.
Its edits show up on your canvas live, exactly the way a collaborator’s do — no refresh, no import step. If you have the space open you’ll watch it build.
Set it up
Four steps, about a minute. Nothing to copy into a settings box — no API key, no client ID, no token. Your assistant and ClipSpaces work that out between themselves once you approve the connection in your browser.
Add ClipSpaces to your assistant
Pick the client you use:
claude mcp add --transport http clipspaces https://clipspaces.app/api/mcpClaude Desktop: Settings → Connectors → Add custom connector, then paste the URL above. Other clients: add the block to wherever that client keeps its MCP servers.
Start the connection
In Claude Code, list your servers and authenticate the new one. Pick
clipspaces, then choose Authenticate. Other clients show a Connect or Sign in button next to the server instead./mcpType this in Claude Code, not in your shell.
Approve it, and pick your spaces
Your browser opens a ClipSpaces approval screen naming the app that asked. Sign in if you aren’t already, tick the spaces it should reach, and decide whether it may edit them or only read. Approve, and the browser hands control back to your assistant.
Check it worked
Ask your assistant something only ClipSpaces can answer:
List my ClipSpaces spaces, then summarise what's on the first one.You should get back the spaces you ticked — and nothing else.
Choosing what it reaches
This is the part worth being deliberate about. A connection is narrower than you are: a space you own but didn’t tick stays invisible to it. It can’t list it, read it, edit it, or even learn that it exists.
The same goes for editing. If you grant reading only, the assistant can look and never touch. And if you’re a viewer on a space someone else shared with you, the connection is a viewer there too — permission is checked against your access at the moment of every request, not frozen at the moment you approved it. Get removed from a shared space and the connection loses it immediately, with nothing to revoke.
To change which spaces a connection covers, connect it again and tick a different set. The new approval replaces the old one rather than adding to it.
Using it
Talk to your assistant normally and name the space. A few things that work well:
- “Read my Research space and tell me what I’m missing.”
- “Turn the notes in Launch plan into a flowchart.”
- “Add a sticky to Roadmap summarising each link, then tidy the layout.”
- “Group the cards in Inbox by theme and put each group in a frame.”
Everything it does is an ordinary edit, so it syncs to your other devices and to anyone you share the space with, just like your own changes.
What it gets access to
Three tools, and that’s the whole surface:
| Tool | What it does | Needs |
|---|---|---|
list_spaces | Names the spaces you granted. | Any access |
get_space | Reads one board — its cards and their connections. | Read |
edit_board | Creates, edits, moves, connects and deletes cards. | Edit |
Two limits are deliberate and won’t change:
- Clearing a whole space is something only you can do, in the app, where it asks you to confirm. An external assistant can’t — the most destructive thing in the vocabulary is the one thing it’s denied.
- Images, maps and stock photos can’t be added over a connection. Those need to upload files or call a third-party service, which only works from the app. Ask for one and it’ll say so rather than quietly skipping it.
Managing & disconnecting
Everything you’ve connected is listed in the app under Settings → Connectors → Connected apps: what it is, whether it can read or also edit, which spaces it reaches, and when it last used them.
Disconnect cuts it off immediately — its access stops on the very next request it makes. Nothing on your boards is deleted, and you can connect the same app again later. If a connection shows needs re-authorizing, it’s still approved but its session has expired; the app will renew it the next time you use it.
Troubleshooting
| What you see | What to do |
|---|---|
| The assistant says it has no ClipSpaces tools | It hasn’t been authenticated yet. Run /mcp, pick clipspaces, choose Authenticate. |
| “This request has expired” | Approval links are only good for a few minutes. Start the connection again from the assistant. |
| “We don’t recognise that app” | The connection was set up against a different ClipSpaces instance, or was removed. Add the server again. |
| It can’t find a space you know exists | It wasn’t ticked when you approved. Connect again and include it. |
| It reads fine but every edit is refused | Either editing wasn’t granted, or you’re a viewer on that space. Reconnect with editing allowed, or ask the owner for editor access. |
| “This space is read-only because the workspace is over its plan limit” | The space’s owner needs to upgrade or free up room. Not a connection problem — the app refuses those edits too. |
| “Connections aren’t available here” | That ClipSpaces instance runs without an account backend, so there’s nothing to connect to. See below. |
Local dev & self-hosting
The path is always /api/mcp — only the host changes. Running the app locally:
claude mcp add --transport http clipspaces-dev http://localhost:3000/api/mcpConnections need Supabase — the approval, the spaces it covers and the session behind it all live in the database. With no Supabase configured, ClipSpaces still runs fully local-first in the browser, but there’s no account for a connection to be scoped to, so every MCP route refuses up front instead of half-working.