MCP Tools
Tools, tips and limits
What your assistant can actually call, how to get better results out of it, and what the MCP server can't do yet.
How it works
An MCP server gives your assistant a set of tools it can call. You write a prompt, your assistant works out which tools it needs, and Spreo carries out the work against your boards using your own permissions.
Two things follow from that, and they explain most of what you'll see.
Your assistant reads Spreo's manual before it builds. The first time it creates content it fetches a full reference for Spreo's board format: every element, the layout rules and the colour palette. That's why the first build in a conversation takes a moment longer than the ones after it.
Edits land as one transaction. A single edit either applies completely or not at all, so you'll never end up with half a retro on the board because one instruction was wrong.
Tool reference
list_workspaces
Lists your workspaces and folders
—
list_boards
Finds boards, with search, filtering and sorting
64 boards per call
read_boards
Reads the full content of boards
5 boards per call
search_people
Finds people in your account by name or email
20 people per call
create_board
Creates a new, empty board
—
clone_board
Duplicates a board with all its content
—
edit_board
Adds, changes, arranges and deletes board content
50 operations per call
edit_board_help
Spreo's board manual, for your assistant
—
list_workspaces
Returns your workspaces and their folders as a tree, matching what you see in Spreo. Your assistant uses it to work out where a board should go.
Tip: if you work across several workspaces, name the one you want in your prompt. Otherwise new boards land in your account's default workspace.
list_boards
Finds boards you have access to, with search, workspace and folder filters, and sorting. Returns each board's name, ID, link and workspace.
Tip: board names are what your assistant searches on, so a board called "Retro" is much harder for it to find than "Platform squad retro, sprint 24". Paste a board link into your prompt when you want to be certain which board you mean.
read_boards
Reads the full content of up to five boards: every sticky, zone, card and connection, and how they're nested inside each other.
Tip: ask it to read the board before it changes anything, so it works from what's on the canvas rather than assuming. If you want it to look across a run of retros, ask for them five at a time.
search_people
Finds people in your Spreo account by name or email address, and returns their name, email and avatar. Names match loosely, so "Mel Brookes" will find "Melanie Brookes". A full email address matches exactly. Up to 20 people per call.
Your assistant uses it when it needs real people on a board, usually to place their avatars as tokens.
Tip: if two people share a name, your assistant should ask you which one you meant rather than guess. If it picks the wrong person, give it their email address instead.
create_board
Creates a new, empty board. You can set the name, workspace and folder.
Tip: boards get built in two steps, created empty and then filled in. If you're watching the board while your assistant works, expect a blank canvas for a moment before the content turns up.
clone_board
Duplicates a board, including everything on it. You can give the copy a new name and send it to a different workspace or folder.
Tip: this is the quickest route to a recurring ceremony. Ask your assistant to copy last sprint's board, rename it, and clear out the old stickies.
edit_board
Does all the actual work on a board, placing stickies, zones, text, shapes, images, connectors, Jira cards, index cards, task cards, topics, tokens, grids, frames, calendars, videos, counters, buzzers, spinners, timers and the music player. It also handles:
the structured formats
laying out retrospectives
flowcharts
mind maps
org charts
timeline roadmaps,
voters
trays of items
Each call carries up to 50 operations and applies as a single transaction. A few things worth knowing:
Large boards need several calls, so a big build can arrive in stages. That's normal.
Because a call is all or nothing, a rejected build leaves the board untouched. Ask your assistant what went wrong and it can usually correct itself.
Ask for changes rather than starting again. "Move the risks into their own zone and make them red" is quicker and safer than rebuilding the board.
Images are generated after the rest of the board lands, so they show up a few seconds later.
edit_board_help
Spreo's board manual. Your assistant calls this on its own and you never need to ask for it. It's what keeps generated boards looking like real Spreo boards rather than boxes on a canvas.
Built-in formats
Spreo MCP uses seven formats that your assistant can build properly. They aren't separate tools, so you won't see them in the list above. They're structures your assistant passes to edit_board, and Spreo does the layout.
This matters more than it sounds. Ask for a mind map and you get a laid-out mind map with balanced branches and real connectors, not a scattering of stickies with lines drawn between them.
Retrospective. Any sections-style board, not just retros. You get one zone per section, laid out as columns up to three sections and as a panel grid beyond that. It sizes itself to your team, so tell it how many people are coming. You can also ask for a grouping area, an actions area, a description under each section title, and scene-setting copy for the session. Themed retros get a generated illustration per section.
Flowchart. Give it the steps and how they connect. It picks the shapes for you: rounded boxes for process steps, diamonds for decisions, a banner for the start, an oval for the end, a parallelogram for input and output. Branches out of a decision get labelled, and you can have it run top-to-bottom or left-to-right. Describe the branching in your prompt and you'll get proper decision diamonds with yes and no on the arrows.
Mind map. A central topic with branches radiating out, balanced either side and nested as deep as you like. Each top-level branch takes its own colour, which its children inherit.
Org chart. Name and role cards connected as a reporting tree, nested as deep as your hierarchy goes. It runs downward by default, but left-to-right suits deep structures better. Colour a person and their whole subtree takes that colour, which is a quick way to get one colour per department.
Timeline roadmap. A real timeline element with Gantt-style bars on a month axis, in horizontal swim lanes. It needs actual start and end dates, so quarters and month names resolve to real days. Lanes are your parallel tracks: teams, workstreams or products. There are no dependency arrows between bars.
Tray. A stock of stickies or tokens participants drag copies out of. Ask for a tray of the session's participants and it stocks itself with everyone's token at runtime.
Vote. A voting widget where everyone casts a vote across your options and then reveals. Needs at least two options and sizes itself to the count.
What it can't do yet
The MCP server is in active development. Today it won't do any of the following:
1. It can't use templates
It has no access to Spreo's templates, because it builds boards generatively rather than starting from one. We plan to make both Spreo's templates and your custom saved templates available via MCP.
2. It won't run your process for you
It doesn't facilitate. It won't run the session, prompt your team or keep time. It doesn't replace the conversation, or the expertise in the room. It won't manage your agile process or ceremonies, and it can't share a board or invite people for you.
3. It doesn't work autonomously in real time
It acts when you ask it to. It doesn't watch your board, react to changes, or join a live session.
4. It can't access additional data
No Jira access, no actions.
5. No freehand drawing
No freehand drawing or sketching.
6. Not 100% on Technical Diagram Formats
Technical diagram formats like UML or Mermaid are not 100% supported yet, though it will do a good first job.
7. It won't analyse across boards automatically
There's no automatic analysis of patterns across your retros or meeting series. You can ask for it board by board, five at a time, and give instructions on what you want.
What we're working on
We're running the beta with a small group of customers first, then opening it up. Template access, retro analysis across sprints, and a board generator are all on the list. If something you need is missing, tell us, because what beta customers ask for is what we build next.
Tell us what you think
We're actively seeking feedback while MCP is in beta. Tell us what worked, what didn't, and especially what you tried to do that it couldn't handle. We'll come and ask you too.
The Spreo API
MCP isn't the only way to work with Spreo programmatically. Spreo has a basic HTTP API covering boards, workspaces, templates, tasks, notifications, users and account administration.
Visit spreo.io/developers while signed in to Spreo. Your API key is there, along with the reference for each endpoint.
The API and MCP are separate. Connecting an AI assistant over MCP doesn't need an API key, and an API key won't connect an assistant.
Last updated