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

Each AI agent has its own way of being told about an MCP server. In all of 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.

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

Use the codex mcp add command to register the server:

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

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

Add the server 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, it can register the MCP server automatically — see Undo AI in Visual Studio Code 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; we have seen good results with current-generation models such as Claude Sonnet 4.5+, Claude Opus 4.5+, or GPT 5.3+.

  • 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.