An MCP server allows AI agents to call the Understand API directly, enabling more accurate, code-aware analysis. It covers the design decisions, implementation, and practical setup needed to integrate the server with AI tools like Cursor, Claude Code or VSCode with CoPilot.


Prerequisites

  • Understand installed or available via a local checkout

  • Python 3.14+

  • An existing Understand project file (.und)

  • An AI client that supports MCP (e.g., Cursor, Claude Code, VSCode with CoPilot)

1. Download the MCP Server Script

Download the mcp_server_for_understand.py script and place it somewhere accessible on your machine.

2. Install FastMCP

Install FastMCP into the Python environment that will run the server:

pip install fastmcp

⚠️ If you are using a non-default Python (conda, venv, system Python, etc.), ensure fastmcp is installed in that environment.

3. Configure Environment Variables

The Understand Python API requires platform-specific environment variables.

macOS / Linux

Set PYTHONPATH to the directory containing Understand’s Python bindings.

Example (macOS):

export PYTHONPATH=/path/to/Understand/bin/macosx/Python

Linux users may also need:

export LD_LIBRARY_PATH=/path/to/Understand/bin/linux64

Windows

Set the following environment variables:

PYTHONPATH=C:\Program Files\SciTools\bin\pc-win64\Python UNDERSTAND_DLL_DIR=C:\Program Files\SciTools\bin\pc-win64\

The MCP server checks for UNDERSTAND_DLL_DIR on Windows. Alternatively, this path can be hardcoded in the script.

4. Choose an Understand Project

The MCP server takes an Understand project file as an argument in the script (mine is using cursor.und).

Notes:

  • The project remains open while the MCP server is running.

  • The project cannot be analyzed while the server is active.

  • To work with multiple projects simultaneously, run one MCP server per project.

Example: Configuring the MCP Server in Cursor

Cursor uses an mcp.json file to define MCP servers. It needs to be saved to project_path/.cursor/mcp.json and it will just work

Example mcp.json

{
  "mcpServers": {
    "understand": {
      "command": "/Users/natasha/miniconda3/envs/aienv/bin/python",
      "args": [
        "/Users/natasha/projects/ai/cursor_plugins/Scripts/Python/mcp_server_for_understand.py",
        "cursor.und"
      ],
      "env": {
        "PYTHONPATH": "/Users/natasha/sti/bin/macosx/Python"
      }
    }
  }
}

Key Fields

  • command
    Path to the Python executable with FastMCP installed.

  • args

    1. Path to the MCP server script

    2. Path to the Understand project (.und)

  • env
    Environment variables required for the Understand Python API

Verifying the Setup

Once configured:

  1. Open the project in Cursor

  2. Start an AI chat

  3. Ask a question that requires Understand data (e.g., metrics, entities, relationships)

If configured correctly, the AI will call the MCP server and retrieve data directly from the Understand project instead of guessing.