GraphMind MCP server

GraphMind

API-aware MCP server for Microsoft Graph — always fresh, never hallucinated.

GraphMind solves the core problem with AI + Microsoft Graph: LLMs have a training cutoff and will hallucinate endpoint paths for APIs released after training. GraphMind maintains a local, always-fresh index of the entire Graph API and uses a 3-tier funnel to find the correct endpoint for any natural language query.

Architecture

GraphMind sits between your AI client and Microsoft Graph. The AI never guesses endpoint paths — it searches a local, always-fresh index first, then executes the exact endpoint it found.

flowchart TD
    user["Natural language prompt"] --> client["AI client (Cursor / VS Code Copilot)"]
    client -->|"search_graph_api"| funnel["3-tier search funnel"]
    funnel --> schemas["Ranked endpoint schemas injected into AI context"]
    schemas --> pick["AI picks the exact endpoint"]
    pick -->|"call_graph_api"| writeCheck{"Write method?"}
    writeCheck -->|"GET"| exec["Execute against Microsoft Graph / Azure RM"]
    writeCheck -->|"POST / PATCH / PUT / DELETE"| preview["Return preview (confirmed=false)"]
    preview --> approve["User approves in chat"]
    approve -->|"confirmed=true"| exec
    exec --> result["Response (with pagination / aggregate)"]

The 3-tier search funnel

flowchart TD
    query["Natural language query"] --> tier1["Tier 1: Structural filter"]
    tier1 -->|"~45k endpoints to <= 500, ~1ms"| tier2["Tier 2: Cross-encoder rerank"]
    tier2 -->|"top 20, ~100ms, local 80MB model"| tier3["Tier 3: Full schemas injected into AI context"]
    tier3 --> pick["AI picks the exact endpoint"]

Search also applies domain hints (e.g. Cloud PC / snapshot queries auto-select api_version=beta and narrow tags). Write calls require user confirmation before execution.

Prerequisites

• Python 3.11+ and git on your PATH. CI tests Python 3.11.
• Internet access. The install downloads PyTorch via sentence-transformers (often 1 GB or more), the first run clones msgraph-metadata, and the first search downloads an ~80MB reranker model.
• A Microsoft Entra tenant with an app registration (see docs/entra_setup.md)

Quick Start

git clone https://github.com/askaresh/graphmind.git
cd graphmind

python -m venv .venv

# Windows PowerShell
.venv\Scripts\Activate.ps1
# Windows cmd
.venv\Scripts\activate.bat
# macOS / Linux
source .venv/bin/activate

pip install -e ".[dev]"

# Configure — copy the example env, then fill in TENANT_ID, CLIENT_ID, AUTH_MODE
copy .env.example .env     # Windows (PowerShell / cmd)
cp .env.example .env       # macOS / Linux

# Verify (auto-clones msgraph-metadata on first run)
python -m graphmind.cli stats

# Start MCP server
python -m graphmind.cli serve

Use that activated virtual environment for every later command. After activation, graphmind stats works as well. If PowerShell blocks the activate script, call the venv interpreter directly: .venv\Scripts\python.exe -m graphmind.cli stats (macOS / Linux: .venv/bin/python -m graphmind.cli stats).

AUTH_MODE and credentials are read from .env. See docs/entra_setup.md for app registration and permissions.

The spec repo is cloned to ./msgraph-metadata automatically when missing. See docs/spec_lifecycle.md for the full lifecycle and recommended CI workflow.

What to expect on first run

• Cold start (~4–6 min): the first tool call parses the full Graph OpenAPI spec (~45k endpoints) into an in-memory index. The MCP server responds to the handshake immediately and loads the index in the background; subsequent searches are instant until the process restarts. See docs/spec_lifecycle.md.
• One-time model download (~80MB): the cross-encoder reranker downloads on the first search_graph_api call, then is cached locally.

Realistic time-to-first-query: GraphMind itself is clone-and-go in ~3 minutes. Because the one-time Entra app registration + admin consent and the cold-start parse are unavoidable, plan for ~10–15 minutes before your first live Graph call.

Cursor MCP setup

This repo includes .cursor/mcp.json. Credentials and AUTH_MODE stay in .env (not in MCP config):

{
  "mcpServers": {
    "graphmind": {
      "command": "python",
      "args": ["-m", "graphmind.mcp.server"],
      "cwd": "${workspaceFolder}",
      "env": {
        "SPEC_REPO_PATH": "./msgraph-metadata",
        "DEFAULT_API_VERSION": "v1.0",
        "RERANKER_TOP_K": "20"
      }
    }
  }
}

command must be the same interpreter you installed into. With the Quick Start venv, set it to ${workspaceFolder}/.venv/Scripts/python.exe on Windows, or ${workspaceFolder}/.venv/bin/python on macOS / Linux. A bare python only works when that python on PATH is the one that received pip install -e ".[dev]".

Keys in the MCP env block override the same keys in .env. Leave AUTH_MODE, TENANT_ID, CLIENT_ID, and secrets out of this block.

Enable GraphMind under Cursor Settings → MCP. The index loads in the background on the first tool call (~4–6 minutes cold; instant once warm). See docs/spec_lifecycle.md.

Agent behaviour for Graph queries is defined in .cursor/rules/graphmind-mcp.mdc.

VS Code (GitHub Copilot) MCP setup

This repo includes .vscode/mcp.json, which VS Code picks up automatically when you open the folder. It uses VS Code's MCP schema (servers + "type": "stdio"). Credentials and AUTH_MODE stay in .env (not in the MCP config):

{
  "servers": {
    "graphmind": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "graphmind.mcp.server"],
      "cwd": "${workspaceFolder}",
      "env": {
        "SPEC_REPO_PATH": "./msgraph-metadata",
        "DEFAULT_API_VERSION": "v1.0",
        "RERANKER_TOP_K": "20"
      }
    }
  }
}

Use the same venv interpreter for command as in the Cursor section above. MCP env values override .env.

Requires GitHub Copilot agent mode (Chat: Agent view). Open the Chat view, switch to Agent, then Start the graphmind server from the MCP tools picker. As with Cursor, the index loads in the background on the first tool call (~4–6 minutes cold).

Any other MCP-capable client works too. From the repo root, run python -m graphmind.mcp.server with the venv interpreter.

MCP tools

Always use this workflow for tenant / Graph questions:

1. search_graph_api — natural language query; returns ranked endpoint schemas
2. get_endpoint_schema — full parameters for a chosen path (optional)
3. call_graph_api — execute the call against Graph or Azure RM

Additional tool:

• get_changelog — recently decommissioned endpoints from the spec diff pipeline

call_graph_api options

Parameter	Default	Purpose
paginate	false	Follow @odata.nextLink for large GET collections
aggregate	true	With paginate, return { total, sample } instead of full JSON
max_pages	50	Page limit when paginating
sample_size	10	Rows in aggregate sample
confirmed	false	Required for writes — see below

Write confirmation: POST, PATCH, PUT, and DELETE calls return a preview on the first call (confirmed: false). Re-call with the same parameters and confirmed: true only after the user explicitly approves. Set GRAPHMIND_REQUIRE_WRITE_CONFIRMATION=false to skip (e.g. automation scripts).

404 handling: Failed calls suggest related endpoints from the local index when possible.

Example queries

Question	Approach
How many users?	search → GET /users/$count or GET /users with paginate=true, aggregate=true
List Cloud PCs	search → GET /deviceManagement/virtualEndpoint/cloudPCs
Cloud PC restore points	search (beta) → resolve Cloud PC id → GET .../cloudPCs/{id}/retrieveSnapshots()
Reboot a Cloud PC	search → POST .../reboot → preview → user confirms → confirmed: true

Many Windows 365 / Cloud PC APIs are beta-only. GraphMind auto-selects beta for Cloud PC and snapshot queries.

CLI

Command	Description
graphmind serve	Start MCP server
graphmind bootstrap	Clone msgraph-metadata (also runs automatically)
graphmind refresh	Pull latest spec + diff
graphmind scheduler	Run daily/weekly spec refresh scheduler
graphmind stats	Index statistics
graphmind search "query"	Terminal search (debug; no domain hints)

Helper scripts

Optional dev helpers under scripts/ bypass MCP (no write confirmation gate). See scripts/README.md for details.

Script	Purpose
count_users.py	Entra user count
count_cloud_pcs.py / list_cloud_pcs.py	Cloud PC inventory
cloudpc_specs.py	Cloud PC SKU details

Tenant-specific scripts belong in scripts/local/ (gitignored, not on GitHub).

Run from repo root, with the venv activated: python scripts/count_users.py. These scripts force AUTH_MODE=client_secret and need CLIENT_SECRET in .env. Interactive mode is enough for the MCP server and is not enough for these scripts.

Configuration

See .env.example for the full list. Key variables:

Variable	Default	Description
DEFAULT_API_VERSION	v1.0	Default API version for search and calls
SPEC_AUTO_CLONE	true	Auto-clone msgraph-metadata on first run
STRUCTURAL_FILTER_CEILING	500	Max candidates before reranking
RERANKER_TOP_K	20	Endpoints returned after rerank
GRAPHMIND_READ_ONLY	false	Block all write methods via MCP
GRAPHMIND_REQUIRE_WRITE_CONFIRMATION	true	Preview before POST/PATCH/PUT/DELETE
GRAPHMIND_MAX_PAGES	50	Default page limit for pagination
GRAPHMIND_MAX_RESPONSE_CHARS	8000	Truncate large MCP responses
TOKEN_CACHE_PATH	./.graphmind_token_cache.json	Persisted MSAL token cache

After changing Entra permissions, delete the token cache and retry.

Troubleshooting

Symptom	Likely cause	Fix
First tool call hangs for minutes	Cold start — parsing ~45k endpoints + one-time ~80MB model download	Expected on first run (~4-6 min). The MCP server is responsive; the index loads in the background. Subsequent calls are instant until restart.
git ... not recognized / spec never clones	git not on PATH, or no internet	Install git and ensure it's on PATH; GraphMind shells out to git clone. Or clone manually: git clone https://github.com/microsoftgraph/msgraph-metadata ./msgraph-metadata
graphmind is not recognized	The venv is not activated, or its Scripts folder is not on PATH	Activate .venv, or run python -m graphmind.cli stats with that venv's Python
AADSTS50011 redirect URI mismatch	Interactive app registration is missing http://localhost	Add it under Authentication → Mobile and desktop applications (see docs/entra_setup.md)
No OpenAPI specs found under ./msgraph-metadata	Auto-clone disabled or wrong path	Set SPEC_AUTO_CLONE=true, or run graphmind bootstrap, or point SPEC_REPO_PATH at an existing clone
KeyError: 'CLIENT_SECRET' or auth fails at startup	AUTH_MODE=client_secret/certificate without the matching value	Set CLIENT_SECRET / CERT_PATH, or use AUTH_MODE=interactive for local dev (no secret needed)
AADSTS65001 / consent or 403 Forbidden on calls	App lacks the permission, or admin consent not granted	Add the permission in Entra and click Grant admin consent (see docs/entra_setup.md). Then delete .graphmind_token_cache.json and retry
Calls still 403 after adding permissions	Stale cached token without new claims	Delete .graphmind_token_cache.json so MSAL acquires a fresh token
404 Not Found on a beta path	Endpoint is v1.0-only, or path is wrong	Retry with api_version='v1.0', or run search_graph_api again — 404s suggest related endpoints from the local index
pip install fails on numpy/torch	Resolver conflict or unsupported Python	Use Python 3.11+ in a clean virtualenv. numpy is pinned <2 for sentence-transformers compatibility
Server has no attribute list_tools	MCP 2.x was installed	Reinstall from this repo. GraphMind requires MCP 1.x (mcp>=1.27.1,<2)
search_graph_api returns no results	Filters too narrow	Broaden the query, drop tags/method, or set api_version='both'
MCP server not appearing in the client	Wrong cwd or command	Launch from the repo root (cwd) so ./msgraph-metadata and .env resolve. Set command to the venv interpreter, then verify python -m graphmind.mcp.server runs with that same Python

For a quick non-MCP sanity check, run python -m graphmind.cli stats (loads the index) and python -m graphmind.cli search "list all users" (exercises the funnel) from the repo root.

GitHub Actions

• .github/workflows/test.yml — runs on push/PR: compileall + pytest
• .github/workflows/refresh.yml — daily at 02:00 AEST, pulls latest msgraph-metadata, diffs against the stored manifest, and commits changes. No auth secrets required for the spec refresh job.

Development

From the activated Quick Start virtual environment:

pip install -e ".[dev]"
python -m pytest tests/ -v
python -m compileall graphmind

Contributing & community

Contributions are welcome. Please read:

• CONTRIBUTING.md — dev setup, checks, branch/PR conventions
• CODE_OF_CONDUCT.md — community expectations
• SECURITY.md — how to report vulnerabilities (do not open a public issue)
• CHANGELOG.md — notable changes per release

Use the issue templates for bug reports and feature requests, and the pull request template when opening a PR.

License

GraphMind is released under the MIT License.