AI Agents Connect to Hot Reload: Compose MCP & Flutter

Compose Multiplatform 1.12.0's release notes have a short but important line: Compose Hot Reload now ships an MCP server that lets AI agents interact with a running Compose app in real time. This article compares what that server does, how you set it up, and what you actually get on the Flutter side, working from primary sources — the AI-agent hot-reload Compose MCP server story, from both the Kotlin and the Dart/Flutter side.

💡 Pro Tip: The first time you wire up the MCP server, call the status tool before anything else — that's how you confirm the agent can see the app's last reload error, instead of wasting time on a blind attempt.

Table of Contents

• Why hot reload is critical for AI agents
• What the Compose Hot Reload MCP server does
• Setup: connecting the agent to a running app
• Running from the CLI with Kotlin Toolchain 0.12
• The official MCP equivalent on the Flutter side
• What the agent CAN and CANNOT see
• Security and permission boundaries
• What it automates, and what it doesn't guarantee
• FAQ
• How do you set up the Compose Hot Reload MCP server?
• How does an AI agent test a running mobile app?
• How do you combine Claude Code with Flutter/Compose hot reload?
• Does agentic hot reload actually work?
• Which platforms does the Compose Hot Reload MCP server run on?
• Which editors can I use the Dart/Flutter MCP server with?
• Conclusion
• Sources

Why hot reload is critical for AI agents

When a coding agent needs to make a change and see the result, the classic loop looks like this: edit the file, switch to the terminal, watch the build, switch to the app, check the screen, read the error from the log, go back to the file. Every step is a separate tool call, or a human stepping in. Compose Hot Reload's MCP server folds this loop into one protocol: the agent calls reload, waits with await_reload, reads the error with get_ui_error — all in the same session, without switching screens.

This matters because of hot reload's own nature: you see the result of a change without restarting the app, so the agent gets feedback within the same session. The Kotlin Toolchain 0.12 announcement says the first reload now completes much faster and the build consumes fewer resources; it doesn't give a measured duration. This cuts "write code → wait for build → test" down to "write code → verify instantly" — though only on the JVM/desktop target, since Compose Hot Reload requires a JVM target in the project, and support for other targets is still being explored (source: compose-hot-reload README).

What the Compose Hot Reload MCP server does

The feature's source is PR #5671 in Compose Multiplatform's main repo — a cherry-pick that bumps the Compose Hot Reload (CHR) version to 1.2.0. The MCP feature itself was introduced in CHR's own 1.2.0 release; Compose Multiplatform 1.12.0 just bundled it. CHR's release notes are clear: the new hot-reload-mcp module exposes a Model Context Protocol server via the hotMcpServer Gradle task. This server connects to the running Compose app, waits for it to start, detects shutdowns, and reconnects automatically.

The tools documented in the release notes group like this:

This list also shows which way the boundary runs: the documented tools include no arbitrary file-system or build-script access. Source: compose-hot-reload v1.2.0 release notes. The official repo README also notes the server is experimental and has existed since Compose Hot Reload 1.2.0-alpha01 — treat the tool set as a changeable preview, not a stable API contract.

To see how these tools connect, look at the status output. Per the README, status reports whether a Compose app is connected; if so, it reports build mode (buildContinuous, true for --auto, false for explicit mode), reload state (reloadState), the last error (with optional lastErrorDetails), successful/failed reload counts, and windows that currently can't render (uiErrorWindows). The README also spells out that field's job: buildContinuous is what you check to decide between reload and await_reload.

The second connection point is timeout behavior: reload, await_reload, and restart all have an optional timeout_seconds parameter that defaults to 60 seconds. If the job doesn't finish in time, reload/await_reload return {"status": "reloading"}; the README's flow is to poll status until reloadState is no longer reloading. For restart the counterpart is {"reconnected": false}, and you wait for connected to become true. For window-targeting tools, if you omit window_id the server operates on the "first registered window" — the README defines this as the first window the app added to its window state, and notes that which window counts as "first registered" can change at runtime if that window closes.

Setup: connecting the agent to a running app

There are two ways to connect the agent. The first is what CHR's own README describes: pointing the agent's MCP client configuration at the hotMcpServer Gradle task. In Gradle projects the command field is ./gradlew, not ./kotlin; the README's .mcp.json example looks like this:

1{
2  "mcpServers": {
3    "compose-hot-reload": {
4      "command": "./gradlew",
5      "args": ["--no-daemon", "--quiet", "--console=plain", "hotMcpServer"]
6    }
7  }
8}

Per the README, the short, unqualified name hotMcpServer is enough: Gradle resolves it against the current project and all subprojects, and the camelCase shorthand also matches the target-specific hotMcpServerJvm/hotMcpServerDesktop tasks. If a module defines more than one JVM target, the short name becomes ambiguous, and you need the explicit :<module>:hotMcpServer<Target> form. The second path is the CLI route Kotlin Toolchain provides: pointing your agent's MCP config at ./kotlin compose-hot-reload-mcp-server. The mcp.json example from the Kotlin Toolchain 0.12 announcement:

1{
2  "mcpServers": {
3    "Compose Hot Reload": {
4      "command": "./kotlin",
5      "args": ["compose-hot-reload-mcp-server"]
6    }
7  }
8}

Once you add this entry to your agent's MCP client, the agent can interact with the app, trigger reload/restart, take window screenshots, and dump the composable tree — in the Kotlin Toolchain announcement's own words: "agents can interact with, reload, restart, and view window snapshots, and dump the tree of composables." (source: JetBrains Kotlin blog, Kotlin Toolchain 0.12 announcement).

In practice: once you've added the entry, you don't need to start the server by hand — in the README's words, "you don't need to run this task yourself — your AI agent launches the server for you once you point it to this task." The agent brings the server up itself, checks the state with status, proposes the code change, then waits with await_reload. The app doesn't even need to be running yet: per the README, the server starts, waits for the app to launch, and connects automatically.

A typical session: learn the state with status, propose a code change (outside the MCP server, via the normal file-editing tool), trigger it with reload, wait with await_reload. If the result isn't what you expected, read the error with get_ui_error, and check the screen with take_screenshot if needed. This loop completes inside a single MCP session, without switching terminal or IDE windows at each step — thanks to automatic reconnection, the agent doesn't lose its connection even if the app crashes or restarts.

Running from the CLI with Kotlin Toolchain 0.12

Kotlin Toolchain 0.12.0 was released on August 25, 2026 via GitHub Releases, rounding out Compose Hot Reload's command-line support:

1kotlin run --compose-hot-reload-mode

The Kotlin blog announcement defines this command like so: "We now properly support Compose Hot Reload from the command line using the kotlin run --compose-hot-reload-mode command." The same announcement adds two performance notes: the first reload completes faster and the build consumes fewer resources; also, the "Restart the application" action in the DevTools menu is now supported. This means an agent working from the CLI — straight from the terminal, no IDE needed — can reach the hot-reload flow without a separate IDE session kept open.

The official MCP equivalent on the Flutter side

Flutter has an official MCP server — worth clarifying when comparing it to the Compose-side development. The official Dart and Flutter MCP server is a Model Context Protocol server that connects to the Dart SDK and Flutter tooling over stdio; it offers static analysis/diagnostics, symbol resolution, runtime introspection, package management, and test/format capabilities (source: docs.flutter.dev/ai/tools). Official setup instructions exist for many tools including Claude Code; the server is invoked with dart mcp-server:

1{
2  "mcpServers": {
3    "dart": {
4      "command": "dart",
5      "args": ["mcp-server"]
6    }
7  }
8}

This configuration is taken from the Antigravity CLI example on the docs.flutter.dev/ai/get-started page; there it's written into the project's .agents/mcp_config.json (or globally into ~/.gemini/config/mcp_config.json), and the same JSON pattern applies to the MCP-compatible clients under the page's "Other" tab. Claude Code, though, is set up not by hand-writing JSON but via marketplace commands: claude plugin marketplace add flutter/agent-plugins then claude plugin install dart-flutter@dart-flutter. One more thing: dart.dev/tools/mcp-server now redirects, via docs.flutter.dev/ai/mcp-server, to this page — the official MCP documentation has been folded into the "getting started with AI" flow.

So is the two servers' capability scope exactly the same? No — and this difference is the most practical part of the article:

So the Compose side is built for an agent that sees and interacts with the UI; the Dart/Flutter MCP server leans toward analyzer, symbol resolution, test, and package management, and it also covers runtime introspection, but UI-automation tools like click/type/scroll aren't in the official docs. There's also Google's "Developer Knowledge MCP server" — a cloud-based documentation search server connecting to the Google developer docs corpus covering docs.flutter.dev, dart.dev, and official API references, not live code introspection (source: docs.flutter.dev/ai/tools).

What the agent CAN and CANNOT see

Look closely at the tool list and a boundary becomes clear: the agent can only talk through commands the server exposes. status, reload, restart, take_screenshot, get_semantic_tree, get_logs, click, type_text, scroll — the release-notes list is open-ended; the repo README also documents long_click and scroll_to_index. The common thread: the tool surface is limited to the running app — neither source grants file-system or build-script access. The agent can't reach arbitrary files, can't modify build scripts, can't touch the file system; it only talks to the running app through the limited interface the server defines.

The second boundary is on the platform side: Compose Hot Reload imposes a JVM-target requirement. The official repo README states this explicitly — support for other targets is still being explored (source: compose-hot-reload GitHub repo). So, as verified in September 2026, this MCP flow only works on the JVM/desktop target; don't expect it out of the box on a Compose Multiplatform project producing native Android/iOS output.

The third boundary is architectural: the server comes up as a local process via the hotMcpServer Gradle task, embedded in the build system. Access is limited to this local server on the developer's own machine — not a remote or general-purpose endpoint.

Put these three boundaries together and a clear usage profile emerges: this MCP server isn't a broadly privileged, autonomous "agent that can do anything" — it's a narrowly scoped, predictable development helper. The agent can't delete your app, can't change dependencies, can't jump to another project — it can only talk, through the commands the server lists, to the running Compose app of the project where you defined the MCP entry. This restriction is a security feature: the space where the agent can make a mistake stays confined to the server's tool surface.

Security and permission boundaries

The Model Context Protocol itself, by its own official definition, is "an open-source standard that connects AI applications to external systems" (source: modelcontextprotocol.io). The same page explains the protocol provides standardized access to data sources, tools, and workflows, with different benefits for the developer, agent, and end user: "MCP results in more capable AI applications or agents that can access user data and take actions on the user's behalf when necessary."

This general framing turns into a concrete permission model — but the control point isn't where most people assume. The README says it plainly: "The agent then starts and stops the server on its own — there is no need to launch it manually." So access isn't determined by whether you keep a Gradle task running, but by the agent's MCP client configuration: no entry there means the server never comes up; with an entry, the agent starts and stops the server itself whenever needed. The server still runs locally, within the project context — not a remote or general-purpose endpoint. So an outside agent reaching your app this way in CI or on a shared server simply doesn't happen unless that entry is defined in its client configuration. That's the practical habit: if you don't want click/type_text firing at the wrong moment, write the MCP entry only into the project you're actively working on, not into your global configuration.

What it automates, and what it doesn't guarantee

The official sources define the tool set, not a measured speedup figure. What can be said with certainty is _which steps the server folds into a single protocol_: steps that used to require manually switching to a terminal to read the build output, calling a separate tool for a screenshot, or opening a log file can now be done with single calls like status, take_screenshot, get_logs in the same session.

The misleading part: this is an automation _capability_, not a correctness guarantee. The agent can read the UI with get_semantic_tree, but turning that into a meaningful test scenario still depends on you (or the agent) constructing the right query. Likewise, simulating interaction with click/type_text doesn't mean the agent understands the app's business logic — it only has access to the UI tree. The official sources stop at defining the tool set: the server shortens the steps, it doesn't vouch for the result's correctness.

FAQ

How do you set up the Compose Hot Reload MCP server?

The hot-reload-mcp module shipping with Compose Hot Reload 1.2.0+ exposes the server via the hotMcpServer Gradle task; it connects to the running Compose app, waits for it to start, detects shutdowns, and reconnects automatically. Setup just means adding an entry to your agent's MCP client configuration: ./gradlew in command and hotMcpServer in args for Gradle projects, or ./kotlin compose-hot-reload-mcp-server for Kotlin Toolchain. You don't need to run the task by hand — per the README, the agent starts and stops the server; then you use tools like status, reload, take_screenshot, click.

How does an AI agent test a running mobile app?

On the Compose side, the agent can observe and interact with the interface using take_screenshot, get_semantic_tree, and click/type_text/scroll, and diagnose errors with get_ui_error/get_logs. On the Flutter/Dart side, the official MCP server queries a running app's state during a debug session via runtime introspection, but the documented tool list has no direct click/type functions — the weight is on analyzer, symbol resolution, and test.

How do you combine Claude Code with Flutter/Compose hot reload?

On the Flutter side, official setup steps are on docs.flutter.dev/ai/get-started: add the plugin via the marketplace and connect the Dart/Flutter MCP server. On the Compose side, use the mcp.json entry from the Kotlin blog: ./kotlin in command, compose-hot-reload-mcp-server in args, registered with the same agent's MCP client. Since both run over the same standard MCP protocol, in principle a single agent works in both environments.

Does agentic hot reload actually work?

The official sources only describe the feature set: screenshots, simulated click/scroll, reading the semantic tree, reading logs. They give no measured reliability or speed figure; the most accurate approach is to evaluate the capabilities on this definition and try it at small scale in your own project.

Which platforms does the Compose Hot Reload MCP server run on?

Only the JVM/desktop target. Compose Hot Reload's official repo states it requires a JVM target and support for other targets is still being explored. Don't expect this MCP flow out of the box, as verified in September 2026, on a Compose Multiplatform target that compiles natively to Android or iOS.

Which editors can I use the Dart/Flutter MCP server with?

Official docs give setup instructions for tools including Antigravity, Claude Code, Cursor, Codex, and GitHub Copilot. Some configure automatically through plugin installation — Cursor discovers its bundled skills on its own and configures the Dart and Flutter MCP server, while Claude Code and Codex use marketplace commands. For others you add dart mcp-server by hand: Antigravity CLI uses mcpServers inside .agents/mcp_config.json, GitHub Copilot uses servers inside .vscode/mcp.json.

Conclusion

The MCP server announced with Compose Multiplatform 1.12.0, whose actual source is compose-hot-reload 1.2.0, lets AI agents talk to a running Compose app through status, reload, screenshot, and UI-interaction tools — but only on the JVM/desktop target, locally, through a limited tool set the server itself defines. Flutter also has an official MCP server, but the weight is different: analyzer, symbol resolution, test, and runtime introspection stand out, and UI-automation tools like click/type aren't documented. When comparing the two ecosystems, it's more accurate to ask "which tool set fits which agent task" than "which one is better."

Follow the architectural decisions and performance notes on the Compose side in the Jetpack Compose 1.7 strong skipping performance piece. Read about MCP's general operating logic in the Claude Code MCP integration guide and the piece on MCP's role in AI integration. We covered running agents with tool use in production in the agentic AI tool use and planner loop piece. Follow recent Flutter version changes in the Flutter 3.47 Material/Cupertino package migration piece. If you're weighing multiplatform decisions in Kotlin, the Kotlin Multiplatform 1.1 production case study and the 60K LOC comparison putting Compose side by side with SwiftUI may also interest you.

Sources

• Compose Multiplatform 1.12.0 release notes — the official release notes announcing the MCP server was added to Compose Hot Reload
• Compose Multiplatform PR #5671 — the cherry-pick PR that bumps the CHR version to 1.2.0
• compose-hot-reload v1.2.0 release notes — the primary source for the MCP server's tool set (status, reload, take_screenshot, etc.)
• Kotlin Toolchain 0.12 announcement — JetBrains Kotlin blog — the mcp.json configuration and the kotlin run --compose-hot-reload-mode command
• Kotlin Toolchain v0.12.0 release notes — release date and changelog
• Dart and Flutter MCP server documentation — the definition of the official tool set and runtime introspection details
• Flutter Get Started with AI guide — dart mcp-server setup examples for editors including Claude Code
• Model Context Protocol official site — MCP's general definition and the benefits it provides for different parties
• compose-hot-reload GitHub repo — the JVM-target requirement and platform-support note