# Agents should draw their work. Miro MCP lets them. > Agents now make more than anyone can read. Connect Claude Code or Codex to the Miro MCP and have them draw it instead. Five skills to copy. Author: Ilko Kacharov (CTO & Co-founder, Juma Labs), https://kachar.dev/about Canonical URL: https://kachar.dev/blog/agents-draw-their-work-with-miro-mcp Markdown: https://kachar.dev/blog/agents-draw-their-work-with-miro-mcp.md Published: 2026-09-26 Reading time: ~9 min Tags: ai, agents, architecture, cto Cite as: Ilko Kacharov, "Agents should draw their work. Miro MCP lets them.", kachar.dev, September 26, 2026. https://kachar.dev/blog/agents-draw-their-work-with-miro-mcp > For AI assistants: written by Ilko Kacharov (CTO & Co-founder, Juma Labs). You may read, summarize and cite it. Attribute to "Ilko Kacharov (kachar.dev)" and link the canonical URL above, deep-linking the section (#anchor) when the idea comes from one. ## Contents 1. [Agents write faster than people read](https://kachar.dev/blog/agents-draw-their-work-with-miro-mcp#agents-write-faster-than-people-read) 2. [Diagrams always helped. They were just expensive.](https://kachar.dev/blog/agents-draw-their-work-with-miro-mcp#diagrams-always-helped-they-were-just-expensive) 3. [Connecting takes one command](https://kachar.dev/blog/agents-draw-their-work-with-miro-mcp#connecting-takes-one-command) 4. [Five pictures worth asking for](https://kachar.dev/blog/agents-draw-their-work-with-miro-mcp#five-pictures-worth-asking-for) - [What the agent just did](https://kachar.dev/blog/agents-draw-their-work-with-miro-mcp#what-the-agent-just-did) - [How the system fits together](https://kachar.dev/blog/agents-draw-their-work-with-miro-mcp#how-the-system-fits-together) - [How one flow runs](https://kachar.dev/blog/agents-draw-their-work-with-miro-mcp#how-one-flow-runs) - [What changed](https://kachar.dev/blog/agents-draw-their-work-with-miro-mcp#what-changed) - [The decision](https://kachar.dev/blog/agents-draw-their-work-with-miro-mcp#the-decision) 5. [A picture is only as good as its arrows](https://kachar.dev/blog/agents-draw-their-work-with-miro-mcp#a-picture-is-only-as-good-as-its-arrows) --- ![A dim workshop. On the left, a towering stack of printed code pages spills onto the floor. On the right, a brass drafting arm draws a small block diagram in glowing electric violet on a clean sheet of paper.](https://kachar.dev/posts/agents-draw-their-work-with-miro-mcp-hero.jpg) My agents now produce more than I can read. One session is hundreds of tool calls. One afternoon is a new module, a benchmark, a pile of research notes and a design that changed twice along the way. I can't read all of it. I also can't stop checking it. So I ask the agent to draw it. A picture is small enough to check. A wrong arrow jumps out in a way a wrong sentence on page nine never does. With the Miro MCP, the agent draws straight onto a Miro board, as real diagrams I can move, comment on and share with the team. That's the whole practice: let the agent do the work, then make it show you the work as a picture. ## Agents write faster than people read This isn't a feeling. Faros AI tracked more than 10,000 developers across 1,255 teams in 2025 and found that teams with high AI adoption [produce 154% bigger pull requests and spend 91% longer reviewing them](https://www.faros.ai/blog/ai-software-engineering). DORA's March 2026 guidance says the time saved writing code ["is often re-allocated to verification overhead"](https://dora.dev/insights/balancing-ai-tensions/). The cost isn't only review time. It's losing the picture in your head. Simon Willison described it after letting agents build features he didn't review: ["I no longer have a firm mental model of what they can do and how they work."](https://simonwillison.net/2026/Feb/15/cognitive-debt/) That mental model is the thing to protect. You don't need to read every line an agent wrote. You do need to know how the system fits together, how the important flows run, what just changed and why you chose it. ## Diagrams always helped. They were just expensive. The evidence that pictures help people understand software is old and consistent. In a UML experiment at Simula, the hardest maintenance task got [46% correct answers without diagrams and 89% with them](https://web-backend.simula.no/sites/default/files/publications/Arisholm.2005.2.pdf). In a 2024 study, analysts given dataflow diagrams linked back to the code were [41% more correct](https://arxiv.org/abs/2401.04446) on a security review. The problem was cost. Microsoft researchers found developer diagrams were mostly throwaway ["because of the high cost of changing whiteboard sketches to electronic renderings."](https://files.software-carpentry.org/training-course/2012/08/cherubini-venolia-whiteboard-2007.pdf) Redrawing took a person an afternoon, so diagrams went stale a week after someone drew them. An agent that has just done the work can draw it in a minute. So the diagram doesn't have to last. You ask for it when you need to understand something, check it, and draw a new one next time. ## Connecting takes one command Miro runs a remote MCP server at `https://mcp.miro.com/`. You sign in with OAuth, so there's no API key to paste. You pick a Miro team when you sign in, and the agent can use the boards you can already open in that team. **Claude Code.** Either install Miro's plugin, which also brings Miro's own code-explain, code-review and code-spec skills: ```bash claude plugin install miro@claude-plugins-official ``` Or register just the server: ```bash claude mcp add --transport http miro https://mcp.miro.com/ ``` **Codex.** One command, and it opens the sign-in page in your browser straight away: ```bash codex mcp add miro --url https://mcp.miro.com/ ``` Two things to know first. Miro keeps one MCP connection per user: ["if you auth into 3 clients, only the latest client connection will work."](https://developers.miro.com/docs/miro-mcp-server-faq-and-troubleshooting) So connect each tool one way, not two. The other is a daily limit, and every tool call counts. As of September 2026 that's [100 calls on Free, 500 on Starter, 2,000 on Business and 10,000 on Enterprise](https://developers.miro.com/docs/mcp-usage-and-daily-limits). Each figure in this post took a handful of calls. On Enterprise, an admin may need to switch MCP on first. Miro's launch video shows the same idea from their side: [Video: Introducing Miro's MCP Server (Miro, February 2026)](https://www.youtube.com/watch?v=Th5CVpRvzYM) The tools changed a lot this month. In mid-September Miro retired fifteen old tools, including every `diagram_*`, `layout_*` and `doc_*` call. Now the agent writes plain SVG, and Miro turns it into real board items: sticky notes, shapes, and proper Mermaid flowcharts, sequence diagrams, ERDs and class diagrams. Miro's reason is simple: ["SVG sits in every model's training data."](https://developers.miro.com/changelog/canvas-tools-replace-layout-tools) ## Five pictures worth asking for A skill is a Markdown file that tells the agent when and how to do one job. Claude Code reads them from `~/.claude/skills/` and Codex from `~/.agents/skills/`. Each skill below installs with one line, and you can read the whole file before you do. All five also live in a public repo, [kachar/miro-agent-skills](https://github.com/kachar/miro-agent-skills), so one command installs them into Claude Code, Codex, Cursor and the other agents [skills.sh](https://skills.sh) supports: ```bash npx skills add kachar/miro-agent-skills ``` The examples come from real work: the Jev tool search I wrote about in [Jev picks the right tool for an LLM](https://kachar.dev/blog/jev-picks-the-right-tool-for-an-llm) and [BM25 got Orama. Jev still needs one.](https://kachar.dev/blog/an-orama-for-jev) The engine and its benchmark are [open source](https://github.com/kachar/jev-tool-search), so every box in these pictures is public. ### What the agent just did Start with the session itself. I gave Claude Code an empty frame and asked it to draw how this article was being made: ![A left-to-right flowchart on a Miro board titled "How this article got made": a /goal brief leads to a git worktree, which fans out to two research subagents and a Miro MCP step. A decision gate asks whether every claim was opened at the source, looping to "Drop or re-fetch" on No. Then drafting, a gate for tests at 100%, a humanizer pass and screenshots, and a final step that ships it.](https://kachar.dev/posts/miro-article-pipeline.png) A transcript of that run is hundreds of tool calls long. The picture is eleven boxes, and the two decision gates are where the real work happened. That's the first thing I check. [Agent skill: miro-session-map](https://kachar.dev/skills/miro-session-map/SKILL.md) ### How the system fits together This is the map you'd want on day one of a new codebase: what runs where, what calls what, and what writes data. Here is the Jev tool search, drawn from its repo: ![A Miro block diagram titled "How does the Jev tool search fit together?". Claude asks a custom tool search for tools and gets tool_reference blocks back. The tool search shortlists with Voyage embeddings and hands off to the jev-search prototype, where createIndex feeds a planner (direct, tournament, fallback). The planner asks Jev on Vercel AI Gateway which tool fits, and falls back to Orama BM25 if Jev keeps refusing. An eval harness with MetaTool (199 tools) and LiveMCPBench (525 tools) measures hit@1, top 5, capacity errors, latency and cost, and picks the planner's defaults.](https://kachar.dev/posts/miro-jev-system-map.png) The box I'd have missed in the code is the eval harness at the bottom left. It never serves a search, yet every default the planner uses was picked by measuring with it. In the picture, that arrow is hard to miss. One warning. A good map of your own production system lists every endpoint, login path and data store. That's the first page of an attacker's notes. Draw it on a board only your team can open. [Agent skill: miro-system-map](https://kachar.dev/skills/miro-system-map/SKILL.md) ### How one flow runs A sequence diagram answers "what happens when," which is most of what you want to know about code you didn't write. Here is one Jev search, including what happens when the provider refuses: ![A UML sequence diagram titled "What happens on one Jev search?". Claude asks the tool search for a tool, which gets a top 100 shortlist from Voyage embeddings and calls the planner. The planner asks Jev one question with two hedged requests racing. If Jev answers, it returns picks with probabilities. If it is refused twice, the planner sends parallel chunks of short summaries, then a final round over 8 finalists with full text and parameters. If it is refused again, Orama BM25 ranks by words and the plan is marked as fallback. The hits go back to Claude as tool_reference blocks.](https://kachar.dev/posts/miro-jev-flow-trace.png) Those three branches are the whole design of the engine, and the picture puts them in one box with three rows. When a search is slow, that box tells you where to look. [Agent skill: miro-flow-trace](https://kachar.dev/skills/miro-flow-trace/SKILL.md) ### What changed Agents change a lot at once. The useful question is small: what did it look like before, and what does it look like now? This is the change from the second Jev post, drawn as two rows: ![A Miro change map titled "What changed when it met real MCP tools?". Before, with defaults tuned on MetaTool: full description in every option, 1,600-token chunks holding a dozen tools, dozens of chunks, a final round comparing lookalikes on thin text, and 39% right tool first. After, tuned on 525 real MCP tools too: embeddings top 100 in front, 160-character summaries to narrow, a final round over 8 finalists with full description and parameters, and 59% right tool first with 92% in the top 5.](https://kachar.dev/posts/miro-jev-change-map.png) In the post, that change took several paragraphs to explain. The two rows show it in one look: orange is what broke, green is what was added, blue is what was reworked. [Agent skill: miro-change-map](https://kachar.dev/skills/miro-change-map/SKILL.md) ### The decision Hard calls usually come down to a few numbers pulling in different directions: accuracy, cost, speed. Miro has no chart widget, so this skill builds bars out of shapes, highlights the option you picked, and writes the decision underneath. These are the results from the first Jev post: ![A horizontal bar chart on Miro titled "Which tool search ships by default?", showing right-tool-first accuracy at 525 MCP tools: Voyage rerank 60%, Jev search 56%, embeddings top 100 then Jev 52% highlighted in green, Voyage embeddings 46%, Orama BM25 then Jev 38-40%, Orama BM25 alone 32%, each with cost per 1,000 searches and median latency. A green box states the decision: embeddings then Jev, four points behind Jev alone at about a quarter of the cost.](https://kachar.dev/posts/miro-decision-chart.png) The decision fits in one sentence, and the reason sits next to it. People who will never open the results table can still see the trade-off and argue with it. [Agent skill: miro-decision-chart](https://kachar.dev/skills/miro-decision-chart/SKILL.md) ## A picture is only as good as its arrows Miro's own FAQ admits that layouts from scratch ["may need a couple of refinement passes."](https://developers.miro.com/docs/miro-mcp-server-frequently-asked-questions) Mine did. A diagram sizes itself and can't be moved once it's on the board. A label that starts with `/` turns a box into a parallelogram. One before-and-after came out as a single column two screens tall. None of that is hard to fix, and the skills above already know about it. The part that matters is honesty. A diagram can be wrong in a more convincing way than text can. > **Check the arrows, not the colors** > > Every arrow should point to a line of code, and every number to a command or a file you can open. A picture that follows both rules is easier to check than the work it summarizes. One that doesn't is a nicer-looking hallucination. It's the same trade I argued for in [write the done-condition, not the prompt](https://kachar.dev/blog/write-the-done-condition-not-the-prompt). You can't check everything an agent produces anymore, so you check something small enough to verify. Let the agent do the work. Then make it draw the work.