Graph Runner MCP

🖥️ Graph Runner MCP (actrun)

The actrun CLI includes a built-in MCP server for running and debugging graphs locally. It communicates over stdio and exposes debug tools that let an AI agent step through graph execution node by node, set breakpoints, and inspect state.

Tipp

Install actrun first. See the Installation guide.

Configuration

Claude Code

claude mcp add actrun -- actrun mcp

Cursor

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

{
  "mcpServers": {
    "actrun": {
      "command": "actrun",
      "args": ["mcp"]
    }
  }
}

GitHub Copilot

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "actrun": {
      "command": "actrun",
      "args": ["mcp"]
    }
  }
}

OpenCode

Add to opencode.json in your project:

{
  "mcp": {
    "actrun": {
      "type": "local",
      "command": ["actrun", "mcp"]
    }
  }
}

Windsurf

Add to your ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "actrun": {
      "command": "actrun",
      "args": ["mcp"]
    }
  }
}

Available Tools

Tool	Description
debug_connect	Connect to a local actrun debug server
debug_run	Send a graph and start execution
debug_step	Step over the current node
debug_step_into	Step into a group node
debug_step_out	Step out of a group node
debug_resume	Resume until breakpoint or completion
debug_pause	Pause at the next node
debug_set_breakpoint	Set a breakpoint at a node
debug_remove_breakpoint	Remove a breakpoint
debug_inspect	Inspect current debug state
debug_logs	Retrieve buffered log output
debug_stop	Stop the current execution
debug_disconnect	Close the debug connection

Debug Workflow

The AI agent follows this flow automatically:

1. Start actrun --local in the background (captures the WebSocket port)
2. Call debug_connect with the port
3. Read the .act file from disk and send it via debug_run
4. Step through execution with debug_step / debug_step_into / debug_resume
5. Inspect state and logs at each pause point
6. Call debug_disconnect and stop the background process when done