Graph Atlas MCP

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:

• `entity` — Graph entity types; edges are navigation properties and inheritance. focus_object = an entity like group. Expanding an entity on the Permission tab reveals the permissions that touch it; on the Role tab it goes two hops — those permissions plus the roles that grant them (so expanding user surfaces User Administrator, Helpdesk Administrator, and friends).
• `permission` — a permission scope, the entities it touches, and the roles that grant it. focus_object = a permission like User.Invite.All.
• `role` — an Entra role, the permissions it grants, and the entities those touch (two hops). focus_object = a role like User Administrator. This is the one that answers "what can this role actually do" / least-privilege comparison questions.

Build it with npm run build (server tsc, an app-ui typecheck, then esbuild bundles app-ui/atlas-app/ into a single self-contained dist/app-ui/atlas-app.html — MCP App resources must be one blob with no external network dependencies; the resource URI is ui://graph-atlas/atlas-app.html). The server reads the built HTML once at startup, so restart your MCP client (or the server connection) after rebuilding.

Testing with MCP Jam

# published package

npx @mcpjam/inspector@latest npx -y graph-atlas-mcp

or a source checkout

GRAPH_ATLAS_DB=/absolute/path/to/graph-atlas.db \ npx @mcpjam/inspector@latest node --experimental-sqlite /absolute/path/to/dist/index.js

For source checkouts all paths must be absolute — MCP Jam spawns the server from its own working directory. Two MCP Jam (v2.34) quirks to know about: widgets only render under the MCP Jam host profile (the "Claude" host-emulation profile leaves the widget iframe stuck at "loading"), and the widget's Sandbox tab / debug/widget-visibility trace events are the fastest way to diagnose a blank widget.

Note: entity node ids are lowercase everywhere (accessreview), with display labels keeping CSDL casing (accessReview) — entity names aren't consistently cased across the CSDL and the permission source data, and a canonical id is what lets one entity stay one node across all views.

Real bugs caught and fixed while building this:

• CSDL's short graph. namespace alias wasn't stripped (silently produced zero edges).
• permissions.resources entity names aren't consistently cased across Merill's pages (would have silently split one entity into two duplicate-l