Microsoft Graph Atlas MCP

An MCP server that tracks schema changes across the Microsoft Graph API — both the changes Microsoft documents and the ones it doesn't. Covers the full Entra ID, Entra ID Governance, Identity & Access Management, Entra Agent ID, and Information Protection surface, seeded with a year of history at launch. Ships with an interactive schema visualiser rendered inside the MCP client via MCP Apps.

Why

Microsoft Graph evolves continuously across v1.0 and beta. The official changelog is curated and incomplete — undocumented schema changes (new properties, removed relationships, new enum values) land in production before they're announced. This MCP closes that gap by diffing the actual $metadata CSDL daily, and backfills a year of history from both a public community tracker and the official changelog.

Data sources

Two further tables enrich every change with real-world permission/role context: permissions (1,036 scopes scraped from Merill's Graph Permissions Explorer) and roles (135 Entra built-in roles and their microsoft.directory/* actions, from the Microsoft Learn permissions reference), cross-referenced into role_permission_map.

Quick start (npx)

Requires Node.js 22+ (uses the built-in node:sqlite). Add to your MCP client — e.g. Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "graph-atlas": {
      "command": "npx",
      "args": ["-y", "graph-atlas-mcp"]
    }
  }
}

That's the whole setup: on first launch the server auto-downloads the latest published database (change history, permissions, roles, embeddings) from this repo's GitHub Releases into ~/.graph-atlas-mcp/, and keeps it current against the daily release cadence.

Developing from source

git clone https://github.com/darrenjrobinson/graph-atlas-mcp.git
cd graph-atlas-mcp
npm install
npm run build

Populate the database (first run)

npm run seed                # one-off: import changes.entra.ms's ~1,600 historical records
npm run backfill            # re-runnable: scrape the official changelog for the 8 IAM families
npm run collect             # fetch v1.0 + beta $metadata, establish today's baseline snapshot
npm run collect-permissions # re-runnable, ~9 min: scrape ~1,036 Graph permission pages
npm run collect-roles       # re-runnable, ~1 min: scrape 135 Entra built-in roles + actions
npm run build-role-map      # re-runnable: cross-reference roles <-> permissions (see limitations)

This produces graph-atlas.db in the project root. npm run seed uses a gitignored, one-off local script (scripts/seed-from-entra-ms.js) — it isn't part of the committed repo.

The DB uses WAL journal mode so these collection scripts can run concurrently with an MCP client that already has the file open (e.g. Claude Desktop) without lock contention.

Optional: semantic search

search_changes runs in hybrid (keyword + semantic) mode automatically if OPENAI_API_KEY is set, and degrades to keyword-only otherwise:

export OPENAI_API_KEY=sk-...
npm run embed      # generates embeddings for any change records that don't have one yet

Re-running npm run embed after a collect only embeds new records — it's incremental, not a full re-embed.

Connect a source checkout to an MCP client

When developing, point the client at your build and local DB instead of the npm package:

{
  "mcpServers": {
    "graph-atlas": {
      "command": "node",
      "args": ["--experimental-sqlite", "/absolute/path/to/graph-atlas-mcp/dist/index.js"],
      "env": {
        "GRAPH_ATLAS_DB": "/absolute/path/to/graph-atlas-mcp/graph-atlas.db"
      }
    }
  }
}

GRAPH_ATLAS_DB points the server at an explicit DB file. Without it, the server looks for ~/.graph-atlas-mcp/graph-atlas.db (auto-downloaded from the latest GitHub Release), then falls back to ./graph-atlas.db in the current working directory.

Tools

Example queries

• "What are the recent changes to Agent ID Graph APIs?"
• "Have there been changes to groups APIs for nesting?"
• "What's the history of the accessPackageSuggestion resource?"
• "What changed in the last 7 days on the beta endpoint?"
• "Show me sensitivity label or DLP policy changes"

Schema visualiser

visualize_schema_graph opens the Graph Atlas visualiser — a d3 force-directed SVG graph rendered directly inside the MCP client via MCP Apps (Claude Desktop, ChatGPT, VS Code, and other compliant hosts). Its architecture and look & feel are ported from EntraPulse Polyarchy:

• Dark-themed chrome (light theme follows the host): pill view tabs, glass panels, a bottom status bar with live node/edge/tool-call counts.
• Additive canvas + session cache — the graph accumulates as you explore. Double-click any node (or the panel's Set as focus button) to flip context to it: hop distances re-anchor, the canvas glides to center it, and its neighborhood expands. Anything already fetched this session re-expands instantly from cache with zero repeat tool calls. Reset clears the canvas but keeps the cache.
• Search — the toolbar search box (backed by search_schema_objects) matches entity types, permissions, and roles by name and flips focus to your pick.
• Detail panel — per-kind fields (properties/navigations/changes for entities, split app/delegated consent + description for permissions, blast radius/published actions/template id for roles), plus an in-panel change-history timeline (backed by get_node_timeline).
• Rearrangeable layout — drag a node and it stays pinned where you drop it, so you can pull clusters apart to read dense neighborhoods; new expansions bloom out of the node they came from.
• Color language — entity types shade by distance from the focus (blue ramp); permissions and roles wear their relationship colour (green touches / amber grants), faded with distance. Red is reserved as a signal: a solid red ring marks privileged roles and admin-consent permissions, and an amber/red activity dot marks recently-changed entities. A legend (bottom-left) doubles as a visibility filter — unchecking a relationship or object type dims it.
• Model awareness — the app pushes updateModelContext after every focus/expansion, so the assistant knows what's on screen without extra tool calls.

Three pivot dimensions, chosen via view (or the in-app tabs) so you can start wherever the question starts — a Role, a Permission, or an entity/API: