Skip to content

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

It also works everywhere Understand works: an agent backed by a language server or by text search is limited to the languages that tooling supports, while Understand answers the same questions across all 17+ analyzed languages — including Ada, Fortran, VHDL, JOVIAL, and Delphi/Pascal — and across the boundaries between languages in a mixed codebase.

The server program is undmcp, installed alongside und in Understand's bin directory.

What the agent can do

In its default mode the server exposes a code-navigation toolset: searching for entities by name, resolving what's at a file and line, walking call graphs and references, tracing file dependencies, browsing and reading source, listing CodeCheck violations, re-analyzing changed files, and — when the Understand GUI is running — driving it (opening locations, presenting code tours).

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.

The tools are designed for the agent to discover and read on its own; you don't need to know their names to use the server. To see the exact toolset your build provides, run:

undmcp -tools

(No project needed — this lists the tools and their parameters and exits.)

Once it's connected, you ask questions in your own words and the agent decides what to call — for the questions the code model answers especially well, and how to get a guided tour instead of a list of file paths, see Work with an AI agent on your code.

Connect a client

You need an existing Understand project (a .und file) that has been analyzed at least once. Point your client at the undmcp program with your project as the -db argument.

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

This registers the server for the current project. Start a chat, run /mcp to confirm understand is connected, then ask something that needs project data — the agent will call Understand instead of guessing.

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.

Name the server understand, as above — it keeps every project and client consistent, and it's the name the rest of these docs use.

Always pass -db. It tells the server which project to serve. Without it the server starts with no database open, and the agent has to open one before it can answer anything — the server never guesses which database you meant, because silently answering from the wrong project is worse than asking. Absolute paths and paths beginning with ~/ both work.

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 the tools that drive the editor. 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.

More than one project

-db can be repeated. One configuration entry can serve several databases:

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

Don't add a second server entry for a second project — repeat -db in the one entry instead.

You refer to the databases by name when you talk to the agent, but you don't have to invent or look up those names: the agent reports the short name of each database it opens, and you can tell it to use names of your own instead. That, and opening or closing a database mid-conversation rather than listing it in configuration, is covered in Work with more than one database.

Permissions & privacy

The MCP server runs for every project you open, and you control what an agent may do through the project's MCP settings — Project → Project Configuration → MCP Server. The query tools are read-only; the actions that change state or reach outside the project are gated:

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 works from your local project database; 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?.

Troubleshooting

  • The agent doesn't see the tools. Confirm the client launched undmcp — run undmcp -tools yourself to verify the binary runs and lists its tools. Check the client's MCP/tool panel (/mcp in Claude Code) for a connection error, and double-check the -db path in the client config.
  • See what the agent is actually calling. Project Configuration → MCP Server shows a Recent activity list of the tool calls the server has served, with arguments. It's always recording, so it's the fastest way to tell "the agent never called Understand" apart from "it called Understand and got an answer you didn't expect."
  • Enable verbose logging. Set STI_MCP_LOG=1 in the server's environment (e.g. -e STI_MCP_LOG=1 in the client config) to get a JSONL log of the session.
  • "The agent says no database is open." Its configuration is missing -db. Either add it, or ask the agent to open one — it can list the databases it knows about and open the one you name.
  • "Read outside project" prompts keep appearing. That's the Ask first default for files outside the project tree — set it to Always (or Never) in the project's MCP settings.
  • Analysis vs. serving. Prefer running against an already-analyzed, up-to-date .und; let the agent call reparse_changed when it needs to refresh, rather than analyzing the project by other means while the agent is mid-task.

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.