xstate-mcp-bridge

Expose a running XState actor through controlled Model Context Protocol tools.

Verify in 60 Seconds

git clone https://github.com/keshavvashishth212121-oss/xstate-mcp-bridge.git
cd xstate-mcp-bridge
npm install
npm test
npx tsx examples/demo.ts

The demo starts an MCP server over stdio, connects an MCP client, walks an order through pending, paid, and shipped, rejects an invalid transition, and prints the transition history.

Related MCP server: Agent NextUp

Why this exists

AI clients increasingly need to observe and advance business workflows, but they should not bypass the transition rules, guards, or context owned by the application. This bridge exposes a narrow MCP interface around a running XState actor so clients can request state, submit events, and wait for transitions while the state machine remains the source of truth.

Architecture

MCP Client  ->  xstate-mcp-bridge  ->  XState Actor
                  (permissions,          (state, guards,
                   validation,             transitions, context)
                   history)

The bridge is transport-agnostic. Connect the returned MCP server to stdio, HTTP, or another supported MCP transport.

Tools

Safety model

• Permissions: readState, sendEvent, and reset can be restricted independently. Permissions default to enabled unless explicitly set to false.

• Transition validation: send_event checks the actor snapshot's XState can() method before sending, so invalid events are rejected explicitly.

• Context redaction: Provide redactContext to remove secrets such as API keys before context is returned by get_state.

• Bounded history: Transition history is limited by maxHistory, which defaults to 1000. When entries are dropped, get_history reports truncated and droppedCount.

Limitations

• There is no built-in authentication or authorization beyond bridge permissions.

• The bridge does not provide process isolation; it runs in the host application's process.

• Transition history is in-memory and is lost when the process exits.

Deployment responsibility

Bridge permissions are application-level capability controls, not client authentication. This library does not authenticate MCP callers, authorize users, isolate the actor process, or make context and tool output trustworthy. Applications exposing the bridge over a network must provide transport-level authentication, authorization, network restrictions, and any required approval workflow or process isolation.

Use cases

• Approvals: An AI assistant can request or observe approvals, but cannot skip pending -> approved guards.

• Deployments: An operator can expose build, test, approval, and deploy states without allowing an MCP client to jump directly to deployed.

• Incident runbooks: An agent can advance a remediation workflow while the application retains authority over valid transitions.

Non-goals

• This is not an MCP authentication server.

• This is not a durable event store.

• This is not a replacement for XState.

• This does not provide process isolation.

API reference

interface CreateMcpBridgeOptions {
  name: string;
  actor: AnyActorRef;
  permissions?: {
    readState?: boolean;
    sendEvent?: boolean;
    reset?: boolean;
  };
  maxHistory?: number;
  redactContext?: (context: any) => any;
}

function createMcpBridge(options: CreateMcpBridgeOptions): McpBridge;

The returned McpBridge is an McpServer with an additional reset(): void method. The actor must be started by the application before creating the bridge.

Development

npm install
npm test
npm run build
npm run example
npx tsx examples/demo.ts

Relationship to DevCompanion AI

This library was extracted from the state-machine integration work in DevCompanion AI. It is now a standalone, open-source bridge with no runtime dependency on DevCompanion AI, its application, prompts, storage, or user interface. It can be used independently in any TypeScript project that already owns an XState actor.

DevCompanion AI was the first real consumer of this bridge, not a runtime dependency. The reusable boundary is the running XState actor: applications own their machines, guards, context, and business rules; this library adds a controlled MCP interface without importing application-specific prompts, storage, sandbox logic, or UI.

Package status

The repository is the source release for the current hackathon submission. An npm package release is planned after the API stabilizes.

Security Warning

Note: Mutating permissions (sendEvent, reset) default to enabled for ease of use in local development. For externally reachable MCP servers, explicitly configure permissions to deny mutations unless required, rather than relying on defaults.

Roadmap

• Add optional persistence adapters for transition history.

• Support richer matching for deeply nested state values.

• Add examples for HTTP and WebSocket MCP transports.