VSCXML MCP Server Setup Guide

This guide explains how to set up and use the @vscxml/mcp server with Claude Code, Claude Desktop, and other MCP-compatible LLM tools.

Prerequisites#

Install the VSCXML tools:

After installation, the tools are at:

Starting the Backends#

The MCP server auto-discovers and auto-spawns the backends. But you can also start them manually:

Windows#

# Generator CLI (REST API on port 48620)
& "$env:LOCALAPPDATA\VSCXML-Generator-CLI\VSCXML-Generator-CLI.exe" serve --port 48620 --cors

# Simulator (WebSocket on port 48621, REST on port 48622)
& "$env:LOCALAPPDATA\VSCXML-Simulator\VSCXML-Simulator.exe" serve --ws-port 48621 --rest-port 48622 --cors

# Editor (just launch it — the MCP editor API starts automatically on port 48623)
& "$env:LOCALAPPDATA\Programs\VSCXML-Editor\VSCXML-Editor.exe"

macOS / Linux#

# Generator CLI
vscxml-generator-cli serve --port 48620 --cors

# Simulator
vscxml-simulator serve --ws-port 48621 --rest-port 48622 --cors

# Editor
# Just launch the application

Auto-Spawn Mode#

If the MCP server can't find backends on the default ports, it automatically:

1. Looks for installed executables in the standard locations
2. Spawns them with the correct arguments
3. Waits for them to be ready (health polling, up to 15 seconds)
4. Cleans them up when the MCP server exits

Claude Code Configuration#

One-line install (recommended)#

Open a terminal in your project directory and run:

claude mcp add vscxml -- npx -y @vscxml/mcp

This adds the MCP server to the current project (-s local, the default). It only works when Claude Code is launched from this project directory.

To make it available in all projects, use -s user:

claude mcp add -s user vscxml -- npx -y @vscxml/mcp

Verify the installation#

After restarting, ask Claude:

"Use scxml_status to check if the VSCXML backends are connected"

You should see the 49 VSCXML tools in the tool list.

Manual configuration (alternative)#

If you prefer editing config files directly:

Project-level — add to .claude/settings.json in your project:

{
  "mcpServers": {
    "vscxml": {
      "command": "npx",
      "args": ["-y", "@vscxml/mcp"]
    }
  }
}

Global — add to ~/.claude/settings.json:

{
  "mcpServers": {
    "vscxml": {
      "command": "npx",
      "args": ["-y", "@vscxml/mcp"]
    }
  }
}

With explicit backend URLs#

If your backends run on non-default ports:

claude mcp add vscxml -- npx -y @vscxml/mcp --generator http://localhost:48620 --simulator ws://localhost:48621 --editor ws://localhost:48623

Or via environment variables in the JSON config:

{
  "mcpServers": {
    "vscxml": {
      "command": "npx",
      "args": ["-y", "@vscxml/mcp"],
      "env": {
        "VSCXML_GENERATOR_URL": "http://localhost:48620",
        "VSCXML_SIMULATOR_URL": "ws://localhost:48621",
        "VSCXML_EDITOR_URL": "ws://localhost:48623"
      }
    }
  }
}

Claude Desktop Configuration#

In Claude Desktop: Settings > Developer > MCP Servers, add:

{
  "mcpServers": {
    "vscxml": {
      "command": "npx",
      "args": ["-y", "@vscxml/mcp"]
    }
  }
}

Other MCP-Compatible Agents#

The @vscxml/mcp server works with any agent that supports the Model Context Protocol. The pattern is always the same: tell the agent to run npx -y @vscxml/mcp via stdio.

Cursor#

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "vscxml": {
      "command": "npx",
      "args": ["-y", "@vscxml/mcp"]
    }
  }
}

Windsurf#

Add to .windsurf/mcp.json in your project root:

{
  "mcpServers": {
    "vscxml": {
      "command": "npx",
      "args": ["-y", "@vscxml/mcp"]
    }
  }
}

Continue.dev#

Add to ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@vscxml/mcp"]
        }
      }
    ]
  }
}

Zed#

Add to Zed settings.json:

{
  "context_servers": {
    "vscxml": {
      "command": {
        "path": "npx",
        "args": ["-y", "@vscxml/mcp"]
      }
    }
  }
}

OpenCode#

Add to mcp.json:

{
  "mcpServers": {
    "vscxml": {
      "command": "npx",
      "args": ["-y", "@vscxml/mcp"]
    }
  }
}

Workflow Guidance for All Agents#

All MCP agents (not just Claude Code) can call scxml_help to get workflow guidance:

scxml_help()              → overview of all workflows
scxml_help("design")      → step-by-step design workflow
scxml_help("simulate")    → simulation best practices + pitfalls
scxml_help("generate")    → code generation for all 7 targets
scxml_help("trace")       → trace recording, comparison, replay

Claude Code users additionally get slash commands (/vscxml:design, etc.) via the plugin system, which automatically inject this guidance and are auto-invoked by context. Other agents can call scxml_help at any time to get the same content.

See docs/architecture/MULTI_REPO_ARCHITECTURE.md for the full breakdown of what each agent gets.

Verifying the Setup#

After configuring, restart Claude Code (or start a new conversation). Then:

1. Check connectivity:

   "Use the scxml_status tool to check backend connectivity"

2. Quick validation test:

   "Validate this SCXML: <scxml xmlns='http://www.w3.org/2005/07/scxml' version='1.0' initial='s1'><state id='s1'/></scxml>"

3. Full pipeline test:

   "Create a simple toggle switch state machine with 'on' and 'off' states, simulate pressing the button 4 times, then generate Python code"

Default Ports#

Available Tools (49)#

Design (4)#

• scxml_create — Create SCXML from a structured spec (no raw XML needed)
• scxml_validate — Validate SCXML against the W3C spec
• scxml_inspect — Get the full structured model (states, transitions, events, variables)
• scxml_help — Get workflow guidance (topics: design, simulate, generate, trace)

Simulation (7)#

• scxml_sim_start — Load SCXML into the simulator and start
• scxml_sim_send — Send an event and get the trace
• scxml_sim_scenario — Run a batch of events (most useful for testing)
• scxml_sim_timed_scenario — Run a timed scenario with delays between events
• scxml_sim_get_state — Get current state without sending an event
• scxml_sim_set_variable — Set a variable value during simulation
• scxml_sim_reset — Reset to initial state

Trace Management (6)#

• scxml_trace_embed — Embed a trace into the SCXML (from session history or JSONL)
• scxml_trace_list — List all embedded traces in the current SCXML
• scxml_trace_get — Get a trace by name (returns parsed entries)
• scxml_trace_play — Start real-time playback of an embedded trace
• scxml_trace_step — Step forward/backward through a trace
• scxml_trace_delete — Delete an embedded trace by name

Code Generation (3)#

• scxml_generate — Generate code for any of 7 targets (Java, JS, C#, C, Python, Go, ST)
• scxml_generate_project — Generate a complete runnable project with build files
• scxml_list_targets — List available targets and options

Verification (1)#

• scxml_compare_traces — Compare two execution traces

Editor Interaction (8)#

• editor_push_scxml — Push SCXML to the visual editor
• editor_get_scxml — Get current SCXML from the editor
• editor_highlight — Highlight states with color: hex (#ef4444) or preset (error, success, warning, info, active, danger)
• editor_add_note — Add annotations with optional attachedTo, visibleWhen, and color
• editor_remove_notes — Remove MCP-added notes (by ID or all)
• editor_navigate — Navigate canvas: center on state, fit states, fit all, zoom
• editor_show_notification — Show toast notification in the editor UI
• editor_status — Check editor connectivity

Diagram Editing (8)#

• editor_add_state — Add a new state to the diagram. Supports parentId to add as child (auto-positioned), id and label to set at creation time. Returns stateId.
• editor_add_transition — Add a transition between two states. Supports inline event and cond. Returns transitionId.
• editor_set_property — Set properties on a state or transition (label, color, events, guards, actions)
• editor_remove_element — Remove a state or transition (cascades to children and connected transitions)
• editor_clone_state — Clone/duplicate a state with all children, internal transitions, and actions
• editor_auto_layout — Trigger automatic layout (hierarchical or grid algorithm)
• editor_add_image — Add an image to the canvas with optional state-dependent visibility
• editor_set_image_property — Modify image properties (position, visibility, opacity, rotation)

File I/O (3)#

• editor_save_file — Save SCXML to a file path (auto-fetches from editor if no content provided)
• editor_load_file — Load an SCXML file from disk into the editor
• editor_screenshot — Capture the editor window as a PNG image

Export (3)#

• editor_export_svg — Export the full diagram as parseable SVG text (agent can read state IDs, positions, labels)
• editor_export_png — Export the full diagram as a high-resolution PNG (2x scale, entire diagram, not just viewport)
• editor_export_player_html — Export a self-contained interactive HTML player with embedded SCXML runtime, SVG, and trace playback

Selection & Awareness (3)#

• editor_get_selection — Get selected states/transitions and current MCP highlights (with colors)
• editor_get_viewport — Get visible area, zoom level, and pan offset
• editor_connect_simulator — Connect editor to simulator for live state highlights

Simulator Sync (3)#

• editor_disconnect_simulator — Disconnect editor from the simulator backend
• editor_pull_from_simulator — Pull the simulator's SCXML document (including traces) into the editor
• editor_push_to_simulator — Push the editor's SCXML to the simulator (overwrites simulator document)

Status (1)#

• scxml_status — Check connectivity of all three backends

Usage Examples#

Design a state machine from natural language#

"Design a traffic light controller that cycles through red, green, yellow on a timer event, and can be shut down after 3 cycles"

Claude will use scxml_create to build the machine, scxml_validate to check it, scxml_sim_scenario to test it, and offer to generate code.

Analyze an existing SCXML file#

"Inspect this SCXML and explain what it does: [paste SCXML]"

Claude will use scxml_inspect to get the structured model and explain states, transitions, and behavior.

Generate code for multiple targets#

"Generate a complete Java project and a Python project for this state machine"

Claude will use scxml_generate_project for Java (with build.gradle, pom.xml, Main.java) and Python (with pyproject.toml, README, main.py).

Interactive simulation#

"Start a simulation of my vending machine, then insert 5 quarters one at a time and show me what happens"

Claude will use scxml_sim_start and then scxml_sim_send for each event, showing the trace.

Visual editor collaboration with colored highlights#

"Push this state machine to the editor, highlight the error states in red and the success states in green"

Claude will use editor_push_scxml to load the SCXML, then editor_highlight with color: "error" for problem states and color: "success" for valid states. Available presets: error (red), success (green), warning (yellow), info (blue), active (purple), danger (dark red).

Save and load files#

"Save the current state machine to C:\projects\alarm.scxml"

Claude will use editor_save_file to write the SCXML to disk. To load it back later:

"Load the alarm state machine from C:\projects\alarm.scxml into the editor"

Claude will use editor_load_file which reads the file and pushes it to the editor automatically.

Export diagrams for documentation#

"Export the state diagram as SVG so I can include it in my README"

Claude will use editor_export_svg to get the full diagram as SVG text — a parseable XML format that contains state IDs, labels, and positions. For a high-resolution image, use:

"Export a PNG of the full diagram"

Claude will use editor_export_png which renders the entire diagram (not just the viewport) at 2x resolution.

Create an interactive demo#

"Export a standalone HTML player so I can share this state machine with my team"

Claude will use editor_export_player_html to generate a self-contained HTML file with the embedded SCXML player runtime. The file opens in any browser with zero dependencies — recipients can simulate the state machine, send events, and step through recorded traces.

Record and replay execution traces#

"Simulate this scenario, save the trace, then let me replay it"

Claude will use scxml_sim_scenario to run events, scxml_trace_embed to save the execution trace into the SCXML document, and the user can replay it via the editor's simulator panel or export it as a Player HTML.

Take a screenshot for review#

"Take a screenshot of the editor so I can see the current state"

Claude will use editor_screenshot to capture the editor window. The image shows the full canvas with any active highlights and annotations.

Troubleshooting#

"Generator API error (404): Not Found"#

The installed VSCXML-Generator-CLI is outdated. Rebuild and reinstall from the latest source:

cd scxml-gen
.\scripts\build-installers.ps1 -Target generator-cli

"Not connected to simulator"#

The simulator isn't running. Start it manually or ensure it's installed for auto-spawn.

"Editor not connected"#

The VSCXML-Editor isn't running. Launch it — the MCP API server starts automatically on port 48623.

Simulation works but no enabledEvents#

The installed simulator is outdated. Rebuild and reinstall:

.\scripts\build-installers.ps1 -Target simulator