Jun 29, 2026

Miro MCP vs Miro API for AI Agents

TL;DR

Miro ships a hosted MCP server (around 30 tools) and a versioned REST API.
Coverage overlaps but diverges in both directions: the MCP server adds DSL-based diagram generation, code widgets, tables, and comment tools; the REST API owns webhooks, board-member management, and Enterprise organization, team, and project administration.
Both paths are OAuth user-delegation. The MCP server uses OAuth 2.1 with Dynamic Client Registration (DCR); the REST API uses the OAuth 2.0 Authorization Code flow. Miro has no client-credentials or JWT bearer grant, so there is no static service credential for acting across customer teams on either path.
The MCP consent flow is bound to an interactive MCP client; a headless background job cannot complete it. The REST API lets you run the same OAuth flow from your backend, persist the rotating refresh token, and execute with no browser after one-time consent.
For a multi-tenant B2B agent, every user has one Miro OAuth token to store, refresh (1-hour access token, single-use 60-day refresh token), and revoke. Neither path gives you the vault, rotation, or revocation.
Scalekit's Miro connector handles the OAuth flow, token storage, and refresh for both paths, so the MCP vs API decision does not change your auth infrastructure.

Your agent needs to read and write Miro boards. Miro ships two ways in: a hosted MCP server at mcp.miro.com and the Miro REST API (v2) at api.miro.com. They cover overlapping but not identical territory, they put you on different operational paths, and the auth story has a constraint that matters specifically for background agents. Here is the decision framework you need for Miro MCP vs API.

What's Miro MCP

Miro's hosted MCP server is a remote, Miro-maintained endpoint at https://mcp.miro.com/, released in late 2025. It gives MCP-compatible clients access to the boards inside a selected Miro team. Authentication is OAuth 2.1 with Dynamic Client Registration; the user completes a browser-based consent flow and selects the team to install into. On Enterprise plans an admin must enable the MCP server for the organization before anyone can connect.

Miro positions the server around two supported use cases today, generating diagrams on a board and generating code from board content, while exposing a broader tool surface underneath.

What's Miro API

The Miro REST API is versioned (v2), with resource-oriented endpoints under https://api.miro.com/v2/. It exposes CRUD across boards, board members, and most board item types, plus webhooks and a set of Enterprise-only governance APIs. Every application must authenticate with the OAuth 2.0 Authorization Code flow; there is no API key and no machine-to-machine grant.

What your agent can actually do with Miro MCP vs API

The honest summary for Miro is that this is not a clean subset relationship. The MCP server is purpose-built for AI authoring and exposes some newer item types that the standard REST item API does not. The REST API, in turn, owns the operational and Enterprise surface that the MCP server never touches.

Capability

Miro MCP (hosted)

Miro REST API

Search and read boards and items

Yes

Create board items (sticky notes, shapes, cards, frames, text)

Yes, via layout and DSL tools

Yes, explicit per-item endpoints

Generate diagrams from DSL

Yes

No, compose items manually

Code widgets (create, read, update, delete)

Yes

Tables on a board (create, read, update)

Yes

Comments (read, reply, resolve)

Yes

Connectors (lines and arrows) explicit CRUD

Limited, via DSL

Yes

Board member management

Yes

Webhooks (real-time board events)

Yes

Enterprise organization, team, project administration

Yes, Enterprise

Audit logs, eDiscovery export, data classification

Yes, Enterprise

SCIM user provisioning

Yes, separate API

Where the MCP server is stronger

For an authoring agent, the MCP server is the more direct tool. Its diagram_create and layout_create tools build multiple items from a single DSL block, which is far less brittle than placing each shape and connector through individual REST calls. It also reads board context with context_get and context_explore, and it can work with code widgets, tables, and comment threads, none of which the standard REST item API supports.

Where the REST API is stronger

The REST API is the only path for anything operational or organizational. Webhooks for real-time board events, board-member roles, and the Enterprise organization, team, and project APIs live exclusively in REST. If your agent has to react to board changes, manage who can see a board, or administer teams and projects at scale, the MCP server has no equivalent tool. That gap is architectural, not a roadmap item.

The shared rate-limit reality

The MCP server applies standard Miro request limits per user, totaled across all tool calls, with some tools carrying stricter tool-specific limits. The REST API uses a credit-based model: a global budget of 100,000 credits per minute per user per application, with each method assigned one of four weight levels. Either way, an agent issuing many sequential calls per user action will meet these limits sooner than a traditional integration, so plan for backoff from day one.

The auth path each one puts you on

MCP: OAuth 2.1 with Dynamic Client Registration
The MCP server requires OAuth 2.1 with DCR, and there is no alternative. Each user who connects completes a browser-based consent flow and selects the team to install into. The session is held by the MCP client; the agent calls tools through it. There is no token type that skips the interactive flow.
REST: OAuth 2.0 Authorization Code, and nothing else
Every application calling the REST API must implement the OAuth 2.0 Authorization Code flow. Miro does not offer client credentials, JWT bearer, or API keys. You choose at app creation between two token styles, and the choice is irreversible: expiring tokens, where the access token lasts one hour and a single-use refresh token lasts 60 days and rotates on every use, or non-expiring tokens, which stay valid until the user uninstalls your app.

The one non-interactive option, and its limit

Miro does document a service-account style shortcut: you install your own app into your own team from the developer dashboard and collect the resulting token without coding the full redirect flow.

That works for single-tenant internal automation against your own boards. It does not extend to acting on behalf of customer teams, because there is no cross-tenant machine grant.

For multiple customers, you are back to per-user, per-team Authorization Code consent.

Why this defines the headless decision

This is the correction worth internalizing for Miro specifically. Because there is no machine-to-machine grant, the headless distinction is not about token type. It is about who drives the flow.

The MCP server's DCR consent is bound to an interactive client and cannot be completed by a background process.
The REST API lets you run the Authorization Code flow from your own backend, persist the rotating refresh token, and execute on a schedule with no browser present after the one-time consent.

For background agents, that is the deciding difference.

The implication for multi-tenant agents

Both paths give you one Miro OAuth token per user. The MCP flow hands you a session-scoped token per user; the REST flow hands you an access and refresh token pair per user. In a multi-tenant B2B agent, that is N credentials, one per user, each with its own lifecycle. Neither path stores, rotates, or revokes them for you.

What you own in production

On the MCP path

Miro manages hosting, tool schemas, and permission enforcement. You still own per-user token storage, refresh, and revocation, and you depend on Miro's admin gating on Enterprise plans. You also inherit unversioned tool schemas: when Miro updates the hosted server, tool definitions can change without a versioning contract, which matters for deterministic pipelines.

On the REST path

You own the full stack: endpoint selection, request construction, pagination, error handling, credit-aware retries, and the complete token lifecycle. The tradeoff is stability. The REST API is explicitly versioned at v2, so you pin behavior and migrate on your own schedule rather than absorbing an upstream schema change as an incident.

When to use MCP, when to use the API

Use Miro MCP when

Your agent is interactive and user-present: a developer in Claude Code, Cursor, or VS Code generating diagrams from a PRD or scaffolding code from a board.
The job is board authoring and context: creating diagrams from DSL, summarizing board content, or working with tables, code widgets, and comment threads.
You want Miro to own server maintenance and you are comfortable with admin-gated access on Enterprise.
The agent is single-team or personal, not a multi-tenant B2B product.

Use the Miro REST API when

The agent runs headless: scheduled board syncs, background generation jobs, or any workflow with no browser present at execution time.
You need webhooks to react to board changes, or board-member and role management.
Your use case touches the Enterprise organization, team, project, audit-log, eDiscovery, or data-classification APIs that the MCP server does not expose.
You need explicit connector CRUD or deterministic, version-pinned behavior across many customer teams.

The credential problem that exists on both paths

Same problem, different token

Whether you choose MCP or REST, every user in a multi-tenant Miro agent has their own credential. Fifty customers means fifty OAuth tokens, fifty refresh cycles, fifty revocation events. The MCP flow gives you a session token per user; the REST flow gives you an access and refresh token pair per user. The token type differs; the infrastructure required is identical.

What neither path hands you

Neither path is a vault, a rotation engine, or a revocation flow. Miro access tokens expire in one hour, refresh tokens are single-use and rotate on every call, and a user uninstalling your app invalidates the refresh token silently. Your agent has no built-in way to detect that until it sees the 401, unless you are watching for it.

Where Scalekit fits

Scalekit's Miro connector handles the OAuth flow, per-user token storage, and automatic refresh for both paths, so the MCP vs API decision does not change your auth infrastructure.

Building the Miro agent with Scalekit

Agent Auth and the Token Vault

Scalekit's Agent Auth runs the Miro OAuth flow for each user and stores the resulting tokens in a vault, encrypted at rest and resolved at request time. Credentials never touch the agent runtime or the LLM context: the agent calls a tool, gets a result, and never sees a token. Miro's one-hour access tokens and single-use rotating refresh tokens are refreshed for you, which removes the most common silent-failure mode in production Miro agents.

Scoped tools instead of a 100-tool catalog

The Scalekit Miro connector is REST-backed and exposes roughly 100 tools spanning board items, connectors, groups, tags, bulk item creation, and the Enterprise organization, team, project, audit-log, and board-export surface. Handing all of that to a model is the wrong default. A diagram agent needs five to ten of those tools, not a hundred.

list_scoped_tools returns only the tools the current user's connected account is authorized to call, not the full catalog. Scoping a surface from 100 tools to a handful reduces token overhead and produces more reliable tool selection. The fix is not better prompting. It is surface reduction.

Per-user scope for multi-tenant agents

Scope here is a function of identity, not connector configuration. The agent inherits exactly what the user authorized through Miro's own scopes, such as boards:read and boards:write. What the user cannot do, the agent cannot do. Shared credentials are a single-user solution; they do not survive a second tenant, and they cannot express per-user board permissions.

A working agent loop

The example below fetches the user's scoped Miro tools, then runs the full Claude tool-use loop. The connection_name you pass must match the connection name configured in your Scalekit dashboard; a mismatch is the most common integration error.

import os import scalekit.client import anthropic from google.protobuf.json_format import MessageToDict scalekit_client = scalekit.client.ScalekitClient( client_id=os.getenv("SCALEKIT_CLIENT_ID"), client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"), env_url=os.getenv("SCALEKIT_ENV_URL"), ) actions = scalekit_client.actions client = anthropic.Anthropic() # Connect the user to Miro (one-time consent) account = actions.get_or_create_connected_account( connection_name="miro", identifier="user_123", ) if account.connected_account.status != "ACTIVE": link = actions.get_authorization_link(connection_name="miro", identifier="user_123") print("Authorize Miro:", link.link) input("Press Enter after authorizing...") # Fetch only the tools this user's connected account is authorized to call scoped_response, _ = actions.tools.list_scoped_tools( identifier="user_123", filter={"connection_names": ["miro"]}, page_size=100, # page past the default so no connector tools are missed ) llm_tools = [ { "name": MessageToDict(t.tool).get("definition", {}).get("name"), "description": MessageToDict(t.tool).get("definition", {}).get("description", ""), "input_schema": MessageToDict(t.tool).get("definition", {}).get("input_schema", {}), } for t in scoped_response.tools ] messages = [{"role": "user", "content": "List my boards and summarize the action items on the latest retro board"}] while True: response = client.messages.create( model="claude-sonnet-4-6", max_tokens=1024, tools=llm_tools, messages=messages, ) if response.stop_reason == "end_turn": print(response.content[0].text) break tool_results = [] for block in response.content: if block.type == "tool_use": result = actions.execute_tool( tool_name=block.name, # e.g. miro_boards_list identifier="user_123", tool_input=block.input, ) tool_results.append({ "type": "tool_result", "tool_use_id": block.id, "content": str(result.data), }) messages.append({"role": "assistant", "content": response.content}) messages.append({"role": "user", "content": tool_results})

Virtual MCP, without hosting a server

If you would rather expose Miro to your agent over MCP, Scalekit's Virtual MCP Servers give every agent a scoped, per-user MCP endpoint that declares exactly which tools it can see and whose credentials it acts with, with no MCP server to deploy, host, or maintain. You configure the connection and tool allow-list once per agent role; before each run, a short-lived session token is minted scoped to that user's connected account. One server definition serves all users; the endpoint is static, the identity is per-user. A Scalekit Virtual MCP URL looks like https://yourcompany.scalekit.com/mcp/v3/servers/<server-id>.

Recommended:

Observability with agent auth logs

For multi-tool, multi-tenant agents, the operational question auditors ask is whose credentials ran which action. Scalekit's auth logs tie each authorization, token-refresh, and tool call back to the user who authorized it, and the Miro connector ships a miro_token_info_get tool that returns the authenticated user, team, and granted scopes for the active token. That gives you a per-user trail across every Miro call, which is what you need when one agent acts for many customers.

If a tool you need is missing

Scalekit's Miro connector already covers the full board-item and Enterprise surface. If you need a Miro capability or another connector that is not yet exposed, request it through the Scalekit Slack community or the Talk to us page.

Which one to build against

If your agent is interactive and its job is authoring, generating diagrams, scaffolding code from a board, or working with comments and tables, the hosted MCP server is the faster path, and Miro maintains it for you. If your agent runs headless, needs webhooks or board-member control, or touches the Enterprise organization, team, and project APIs, build against the REST API, where you control the OAuth flow, persist the refresh token, and pin a stable version. Most production Miro agents end up using both. Either way, the credential management problem is the same, and that is what needs production-grade infrastructure.

Browse the Scalekit Miro connector and the connector docs.

No items found.

On this page

Introduction
‍

This is some text inside of a div block.