On this pageOverview

DevTools MCP Server

Overview

Foldkit ships @foldkit/devtools-mcp, an MCP server that exposes a running Foldkit app to AI agents. Agents can read the current Model, list and inspect Message history, rewind the UI to any past Model, and dispatch Messages into the runtime.

It complements agent skills. Skills generate code; the MCP server lets agents observe and interact with code that’s already running.

The MCP server pairs with DevTools. DevTools shows Message history and Model snapshots in a panel for humans; the MCP server exposes the same data and controls to AI agents.

Setup

Projects scaffolded with create-foldkit-app already ship with the MCP server pre-wired. Open the project in your AI agent and the tools appear under the foldkit-devtools server. Skip the rest of this section.

For existing projects, run the init command in your project root. It writes a .mcp.json that any MCP-aware AI agent (Claude Code, Codex, Cursor, Windsurf) will pick up:

npx @foldkit/devtools-mcp init

For faster startup, install the MCP server as a devDependency. Otherwise npx fetches it on each AI agent restart:

npm install -D @foldkit/devtools-mcp

In vite.config.ts, pass devToolsMcpPort to the Foldkit plugin so it opens the WebSocket relay:

import { foldkit } from '@foldkit/vite-plugin'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [foldkit({ devToolsMcpPort: 9988 })],
})

In your Runtime.makeProgram call, pass your Message Schema. The runtime decodes every dispatched Message against it before reaching your update function:

Runtime.makeProgram({
  devTools: {
    // Rest of your DevTools config
    Message,
  },
})

Restart your dev server, then restart your AI agent. The foldkit_* tools are now available under the foldkit-devtools server.

The browser bridge runs inside your app, so the MCP server only sees a runtime while the app is open in a browser tab. Close the tab and the runtime disappears from foldkit_list_runtimes.

Tools

Each tool accepts an optional runtime_id. When omitted, the most recently connected runtime is used.

Tool	Description
foldkit_list_runtimes	Returns metadata for every connected browser tab. Agents call this first to discover which runtime to target.
foldkit_get_model	Snapshots the current Model.
foldkit_list_messages	Lists recent Message history entries with pagination. Each entry carries the Message body, command names triggered, timestamp, and a path-level diff.
foldkit_get_message	Reads one entry at a given index, including the Model before and after the Message was applied.
foldkit_list_keyframes	Returns the indices Foldkit can replay back to. Index `-1` is the initial Model.
foldkit_replay_to_keyframe	Time-travels the runtime to a previous state. The runtime is paused at that snapshot until `foldkit_resume` is called.
foldkit_resume	Resumes normal execution after a replay.
foldkit_dispatch_message	Enqueues a Message into the runtime as if your application produced it. The runtime decodes the payload against your Schema and returns a clean error if it does not match.

How It Works

The browser bridge runs alongside DevTools in your app and subscribes to the DevTools store. The Vite plugin opens a WebSocket server on devToolsMcpPort and relays traffic between browsers and MCP clients. The MCP server runs as a Node child process spawned by your AI agent, connects to the relay, and exposes the typed tools.

Multiple browser tabs can be connected at once and each is addressable by its connection id. When a tab closes (gracefully or not) the plugin prunes it from the live runtime list, so the agent’s default to most recently connected always points at a live tab.

Messages flow as Effect Schema values end to end. Foldkit defines the wire protocol and every layer validates at its boundary. To dispatch, agents read your application source to learn the Message Schema and construct a payload; the runtime decodes it and returns a clean error if the shape does not match.

When the dev server restarts, the MCP server’s WebSocket client reconnects automatically with exponential backoff. No agent restart required.

Notes

The MCP bridge shares its lifecycle with DevTools. The default enables both in dev. Setting devTools: false in your program config disables the bridge along with DevTools. The runtime becomes invisible to MCP.

Without Message in your DevToolsConfig, dispatch is rejected. The other tools (read-only) work without it.

The relay only runs at dev time. Production builds never include the relay or the bridge, regardless of any show setting.