Using Undo from your AI agent

Undo ships an MCP server, started with undo mcp, that lets a compatible AI agent drive the Undo Engine to investigate Undo recordings. Once configured, the AI agent decides when to use Undo and which tools to call; you keep using your AI agent as you normally would.

Added in version 10.0.

About the Model Context Protocol

The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources. Undo provides an MCP server that exposes the runtime context captured in an Undo recording, along with a set of capabilities tailored to how LLMs investigate software, to any agent that speaks the protocol. The How it works page describes these capabilities.

Where the MCP server runs

The undo mcp server runs on the machine where you would normally run UDB, alongside the source code and debug symbols of the program you are investigating. The AI agent starts the server as a subprocess and communicates with it over its standard input and output.

There is no centrally-hosted Undo MCP server to connect to and there is nothing to deploy; if your AI agent runs on a developer workstation, your MCP server runs there too. Container-based and CI workflows are also supported, but the same rule applies: the MCP server must run somewhere that has the recording, the source code and debug symbols for the program being investigated.

Providing a recording

The undo mcp server investigates an Undo recording. It can get one in three ways:

  • you point the AI agent at a recording you already have;

  • you ask the AI agent to capture a recording of a program and investigate it;

  • the AI agent decides on its own to capture a recording when it needs one.

See Using the LiveRecorder tool for how to capture a recording; you can also save one from a UDB session with the usave command.

Resource use

Your AI agent starts the undo mcp server when the agent itself starts, so that it can list the available tools; this happens whether or not you go on to ask an Undo question. You will therefore see one server process (a gdb process running some Python) for each running agent instance. After starting up, the server sleeps until the agent calls one of its tools, and uses far fewer resources than a typical editor or IDE.

No Undo license is consumed until the agent first calls an Undo tool, that is, when an investigation actually begins.

Configuring your AI agent

For Claude Code or Codex users, the Undo Suite provides interactive configuration with the undo init user interface. For other agents, or to configure an agent manually, see Manual configuration.

In the examples below, replace <UNDO-DIR> with the path to your Undo Suite installation directory, such that <UNDO-DIR>/undo is the undo command shipped with the suite.

Automatic configuration with undo init

Added in version 10.2.

Run undo init from your Undo Suite installation on the machine where your AI agent runs:

$ <UNDO-DIR>/undo init

A terminal user interface will be displayed, listing detected agents, their configuration files, and whether they use this installation’s MCP server.

  1. Use the arrow keys to move between agents and Space to toggle a checkbox. Checked agents will use Undo; unchecking a configured agent removes its Undo MCP server configuration.

  2. Press a to preview the changes and the files they affect. Choose Apply to write them, or Cancel to return to the list without writing.

  3. Press q to quit. If there are changes you have not applied, press q again to discard them and quit.

You can also click an agent to toggle its checkbox, or click a key at the bottom of the screen instead of pressing it. After applying changes, restart any running agents so that they use the new configuration.

Undo’s Time Travel Debug for C/C++ extension for Visual Studio Code and Cursor makes the same changes with its Undo: Configure Coding Agents command: see Configuring AI agents to use the Undo MCP server.

Supported agents and configuration files

undo init detects agents by looking for these existing files:

  • Claude Code: ~/.claude.json, or .claude.json in CLAUDE_CONFIG_DIR if that environment variable is set to a nonempty value;

  • Codex: ~/.codex/config.toml, or config.toml in CODEX_HOME if that environment variable is set to a nonempty value.

If no agents are detected, set up a supported agent first, or use the manual setup instructions. The command does not install the agents themselves or edit project-specific configuration files.

Adding the server creates or replaces an entry named undo that runs undo mcp from this Undo installation. Other settings are preserved. An existing entry that runs this installation’s server is recognized even if it has a different name. Removing the server removes all such entries, but leaves entries pointing to other Undo installations in place.

Manual configuration

Each AI agent has its own way of being told about an MCP server.

Claude Code

Use the claude mcp add command to register the server:

claude mcp add --scope user undo -- <UNDO-DIR>/undo mcp

See the Claude Code documentation.

Codex

Codex reads its configuration from ~/.codex/config.toml, or from config.toml in CODEX_HOME if that environment variable is set to a nonempty value. Add the server to that file:

[mcp_servers.undo]
command = "<UNDO-DIR>/undo"
args = ["mcp"]
omit_tools_from = ["deferred"]

Recent OpenAI models see an MCP server’s tools only if they search for them, which they rarely do. The omit_tools_from setting preloads Undo’s tools instead, at the cost of a small part of the model’s context window.

See the Codex documentation.

Note

Codex’s default workspace-write sandbox blocks ptrace for processes the model spawns from a bash tool call, so any attempt by Codex to capture a recording with live-record itself will fail with Permission denied. To allow this, add the following to your ~/.codex/config.toml:

sandbox_mode = "danger-full-access"

The undo mcp server itself runs outside the sandbox and is not affected.

Be aware that danger-full-access disables Codex’s sandbox entirely, not just the ptrace restriction: the model can run any command, modify any file, and make any network request that you can. Only use this setting if you trust both the model and the prompts you give it.

Cursor

If you have Undo’s Time Travel Debug for C/C++ extension installed in Cursor, its Undo: Configure Coding Agents command can register the Undo MCP server for you. See Configuring AI agents to use the Undo MCP server for instructions.

To configure the server manually instead, add it to .cursor/mcp.json in your project (for workspace-specific configuration), or to ~/.cursor/mcp.json (for user-wide configuration):

{
  "mcpServers": {
    "undo": {
      "command": "<UNDO-DIR>/undo",
      "args": ["mcp"]
    }
  }
}

See the Cursor documentation.

The same configuration is used by the cursor-agent command-line tool and by the Cursor IDE.

Note

The debugging session driven by Cursor is independent of any debugging session running inside the Cursor IDE. You cannot execute the debugged program in the IDE and then ask Cursor a question that depends on where the IDE is currently stopped.

Gemini CLI

Use the gemini mcp add command to register the server:

gemini mcp add undo <UNDO-DIR>/undo mcp

See the Gemini CLI documentation.

GitHub Copilot CLI

Add the server to ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "undo": {
      "type": "local",
      "command": "<UNDO-DIR>/undo",
      "args": ["mcp"],
      "tools": ["*"]
    }
  }
}

See the GitHub Copilot CLI documentation.

GitHub Copilot in Visual Studio Code

If you have Undo’s Time Travel Debug for C/C++ extension installed, its Undo: Configure Coding Agents command can register the Undo MCP server for you. See Configuring AI agents to use the Undo MCP server for instructions.

To configure the server manually, run MCP: Add Server from the command palette (Ctrl+Shift+P) and fill in the form:

  • Type: stdio

  • Command (with optional arguments): <UNDO-DIR>/undo mcp

  • Name: Choose a unique name for the server, for example “Undo MCP Server”.

  • Configuration target: “Global” to register the MCP server on your local machine, or “Remote” if you are using the Remote - SSH extension and want to register the server on the remote host where UDB runs.

MCP: Open User Configuration or (MCP: Open Remote User Configuration if using Remote - SSH) from the command palette (Ctrl+Shift+P) can be used to view or edit the configuration of the MCP server.

See the Visual Studio Code MCP documentation.

Kiro CLI

Register the server with the kiro-cli mcp add command:

kiro-cli mcp add --name "undo" \
    --scope global \
    --command "<UNDO-DIR>/undo" \
    --args "mcp"

Alternatively, you can add the server to .kiro/settings/mcp.json in your workspace or to ~/.kiro/settings/mcp.json, using the same JSON format as the Kiro IDE.

See the Kiro CLI documentation.

Kiro IDE

First, ensure MCP support is enabled in the Kiro IDE settings (open settings with command-, on macOS or control-, on Windows or Linux, search for “MCP” and enable the MCP support setting).

Then add the server to .kiro/settings/mcp.json in your workspace (for workspace-specific configuration) or to ~/.kiro/settings/mcp.json (for user-wide configuration):

{
  "mcpServers": {
    "undo": {
      "command": "<UNDO-DIR>/undo",
      "args": ["mcp"],
      "disabled": false
    }
  }
}

You can also use the Kiro: Open workspace MCP config (JSON) or Kiro: Open user MCP config (JSON) commands from the command palette (command-shift-P on macOS or control-shift-P on Windows or Linux) to open the configuration files.

See the Kiro IDE documentation.

Roo Code

Click the settings icon in the top navigation of the Roo Code pane in Visual Studio Code, scroll to the bottom of the MCP settings view, and click Edit Global MCP (or Edit Project MCP). Add the server to the JSON file that opens:

{
  "mcpServers": {
    "undo": {
      "command": "<UNDO-DIR>/undo",
      "args": ["mcp"]
    }
  }
}

See the Roo Code documentation.

Troubleshooting

If you suspect your AI agent is not picking up the undo mcp server (for example, it investigates a problem without ever mentioning Undo), check its connection status. Most chat-style agents accept a /mcp or /mcp list command in the chat window that lists the configured MCP servers and whether they are connected; IDE-based agents typically have an MCP servers panel in their user interface. Refer to your AI agent’s documentation for the exact command or location.

If the AI agent reports that the undo mcp server is not connected, or it refuses to use it, check the following:

  • The <UNDO-DIR>/undo path in the AI agent configuration is correct and points at an Undo Suite installation on a Linux machine. The AI agent must be running on the same machine.

  • AI features are enabled in your Undo license. Run <UNDO-DIR>/undo mcp --check to check; the command exits with status 0 if AI is enabled and prints an explanation otherwise. If AI is not enabled, contact support@undo.io.

  • The model selected in the AI agent supports MCP tools. Older or smaller models may not be able to handle MCP tools well; see Choosing a model.

  • Your local policies allow the AI agent to start MCP servers. Some organizations restrict which MCP servers can be configured; in that case, ask your administrator to allow undo mcp specifically.

If you still cannot diagnose the issue, run the AI agent in debug mode (for example claude --debug --verbose) so that it prints any error encountered while starting or talking to the MCP server.

Using undo mcp over HTTP

By default the undo mcp command communicates with the AI agent over standard input and output (“stdio mode”). We strongly recommend leaving it that way: there is nothing to manually start and nothing listens on the network. The HTTP mode described below exists for environments whose tooling or security policies cannot accept a stdio MCP server.

To start the server in HTTP mode, run:

<UNDO-DIR>/undo mcp --http [--port PORT]

The server then listens at http://localhost:<PORT>/mcp (default port: 8001) until you stop it.

Warning

The HTTP server is reachable by any user on the same machine. It is not authenticated and is not designed to be exposed outside localhost. Do not bind it to an interface other than the local loopback, and do not run it on a host shared with other users without considering the security implications.

Configure your AI agent to use the running HTTP endpoint, instead of starting undo mcp as a subprocess. The exact configuration depends on the AI agent; refer to your AI agent’s documentation for how to point it at an HTTP MCP server.