> For the complete documentation index, see [llms.txt](https://docs.spreo.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spreo.io/boards/mcp/mcp-tools.md). # 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. {% hint style="info" %} **While the Spreo MCP server is in beta, you must** [**manually add it to your agent / AI assistant**](/boards/mcp.md#connect-your-ai-assistant)**.** {% endhint %} ### 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 | Tool | What it does | Limits | | ----------------- | ------------------------------------------------- | ---------------------- | | `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](https://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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.spreo.io/boards/mcp/mcp-tools.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.