Connect an AI agent via MCP¶

Understand includes an MCP (Model Context Protocol) server so an AI agent — Claude Code, Cursor, VS Code with Copilot, or any MCP client — can call Understand's exact code model directly instead of guessing. When the agent asks "who calls this function?" or "what depends on this file?", it gets Understand's deterministic answer rather than a probabilistic one. That's what turns an assistant from impressive into trustworthy (see Why Understand + AI).

What the agent can do¶

By default, Understand's MCP server allows an AI agent to:

Query the Understand database for entities, references, and other data.
Access source code.
Analyze the project.
Open views in a running Understand GUI.
Discover and open existing databases.

Some of these are controllable through project settings. See the Permissions & privacy section below for details.

GUI or headless — both work

If Understand is already open with that project, the server relays tool calls to the running application, and the agent additionally gets tools to open views in the GUI. If not, undmcp opens the database headlessly on its own and closes it when your session ends. You don't have to keep the GUI open — and if you open the project in Understand mid-session, the agent picks up the editor tools without reconnecting.

Connecting an MCP server to your AI agent doesn't guarantee the agent will call the tools. See Work with an AI agent on your code for techniques to encourage AI to use Understand.

The MCP server answers questions; if instead you want the AI to build something that runs inside Understand — a custom graph, metric, report, or check — see Build an Understand plugin with AI. And for batch AI generation (overviews, the code-search index) from the command line, see und ai.

How to connect your agent¶

In general, connecting an AI agent to an MCP server is providing directions on how to run the server. So, you need the path to the executable and the arguments for it.

The executable is undmcp, installed alongside und in Understand's bin directory. All arguments to the executable are optional, but providing the Understand project as an argument is recommended, especially if the project is not in the same location as the source code. The Understand project must have been analyzed at least once.

Setup instructions by agent are below. Note that there are often multiple ways to connect an MCP server to an agent and just one way is presented below. Refer to each agent's documentation for more details, like controlling the scope of the MCP server (by directory, user, etc.).

Claude CodeVS Code (Copilot)Copilot CLICursor / Claude Desktop

claude mcp add understand /path/to/undmcp -- -db /path/to/project.und

This registers the server with the name "understand" for the current user in the current working directory. In a chat, you can run /mcp to confirm understand is connected.

To have Claude Code load the tools' parameters at session start, add "alwaysLoad": true to the server's entry, for example in a .mcp.json:

{
  "mcpServers": {
    "understand": {
      "command": "/path/to/undmcp",
      "args": ["-db", "/path/to/project.und"],
      "alwaysLoad": true
    }
  }
}

Create .vscode/mcp.json in your workspace (or run MCP: Add Server from the Command Palette). Note VS Code's key is servers, not the mcpServers most other clients use:

{
  "servers": {
    "understand": {
      "command": "/path/to/undmcp",
      "args": ["-db", "/path/to/project.und"]
    }
  }
}

Commit the file to share the setup with your team, or add the server to your user profile instead (MCP: Open User Configuration) to have it in every workspace. Copilot uses MCP tools in agent mode: open the Chat view's tools picker and confirm understand is listed and enabled.

copilot mcp add understand -- /path/to/undmcp -db /path/to/project.und

This adds the server to your user configuration (~/.copilot/mcp-config.json), available in every session. Run /mcp show in a session — or copilot mcp list from the terminal — to confirm understand is configured and started. To scope the server to one repository instead, put the mcpServers JSON block from the Cursor tab in a .mcp.json at the repository root.

Add an entry to the client's MCP configuration (Cursor uses .cursor/mcp.json; other clients have an equivalent mcpServers block):

{
  "mcpServers": {
    "understand": {
      "command": "/path/to/undmcp",
      "args": ["-db", "/path/to/project.und"]
    }
  }
}

Restart the client (or reload its MCP servers) and confirm understand appears in its tool list.

Permissions & privacy¶

You control what an agent may do with Understand's MCP server through the project's MCP settings — Project → Project Configuration → MCP Server. The following controls are available.

Permission	Default for a new project	Applies to
Don't suggest this database for AI agent usage	Off (the project is available to agents; this is an opt-out, and it does not stop the server)	whether this database is offered to agents
Allow reparse	Your last-used setting (initially Always)	re-analyzing changed files
Allow UI interaction	Your last-used setting (initially Always)	tools that drive the GUI
Read files inside the project	Always (resets every project)	reading source in the project tree
Read files outside the project	Ask first (resets every project)	reading files outside the project tree

Anything set to Ask first prompts you in the GUI before the agent proceeds (for example, a reparse request or reading a file outside the project). The reparse and UI settings carry forward: whatever you chose last becomes the default for your next new project. The two file-read permissions do not — every new project starts back at Always / Ask first.

The MCP server runs locally, reading from your local project. It doesn't send your code anywhere on its own — what the agent you connect sends onward is a separate question, answered in What can the AI access?.

Advanced¶

Working with multiple projects¶

Understand's MCP server can have multiple projects open at a time. In this mode, the server provides a list of possible projects and the AI agent chooses which project to use for each request. You can prepopulate the list of projects by specifying the -db switch multiple times:

{
  "mcpServers": {
    "understand": {
      "command": "/path/to/undmcp",
      "args": ["-db", "/work/service.und", "-db", "/work/firmware.und"]
    }
  }
}

Giving no -db switches also enters the multiple-project mode.

Importantly, the multiple-project mode requires the AI agent to manage the open projects. So, it may require more explicit instructions from you about which projects to use and when to open them. A common error state in this mode is for the AI to not open any projects at all and then stop using Understand since most requests require an open project. See Work with more than one database for more information on how to have the AI agent manage your open projects.

Don't add a second server entry for a second project

Some agents limit the total number of MCP tools, and registering the same server multiple times can confuse the AI by presenting the same tools multiple times. Use multiple projects with the same server instead.

Server modes¶

Understand's MCP server has multiple modes which each provide a different toolset. The default mode was written for AI agents that are editing/writing code. For other use cases, another mode might be more useful. You can use undmcp -modes to view the available modes and undmcp -mode <MODE> to run in a different mode. Note that not all modes have the same capabilities.

Next¶

Work with an AI agent on your code — what to ask, how to get guided tours instead of lists of file paths, and how to work across several databases at once.