mcp-entrascopes
A read-only MCP server for exploring published Microsoft Entra first-party application scope metadata.
Search applications by partial name/ID, scope, resource display name/app ID, FOCI status, or public-client status, with exact/contains scope matching.
Retrieve published scope metadata for one exact application ID, optionally filtered by resource and including redirect URIs.
Report dataset provenance, cache/refresh status, and record counts, with an optional forced refresh.
Results are metadata only, not tenant consent, grants, app existence, or token validity. README also advertises revision-history comparison, but that tool is not in the provided schema.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-entrascopes Which apps have the Microsoft Graph scope Application.Read.All?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-entrascopes
A small, read-only Model Context Protocol (MCP) server for querying published Microsoft Entra first-party application scope metadata.
It is inspired by EntraScopes and exposes the underlying scope information in a bounded, agent-friendly form.
It is designed for questions such as:
Which Microsoft first-party applications publish
Application.Read.Allfor Microsoft Graph?What scopes are associated with a known application (client) ID?
Which applications publish a particular reply/redirect URI or target a known API URI?
Which delegated scopes were added or removed in the latest ROADtools dataset revision?
Is an application marked as a public client or a member of a family of client IDs (FOCI)?
Results arenot tenant state. They do not prove that an application exists in a tenant, that an administrator granted consent, or that a token can obtain a listed scope. Verify tenant-specific grants separately with appropriately authorized Microsoft Graph queries.
Why an MCP server instead of a skill?
The primary dataset is several megabytes and changes over time. A skill would either embed a stale snapshot or spend model context searching raw JSON. This server keeps retrieval and indexing outside the model, returns bounded structured results, caches upstream data, and exposes its provenance with every answer.
Related MCP server: Unified Audit Log MCP
Tools
Tool | Purpose |
| Search by application name/ID, delegated scope, resource name/ID/API URI, reply URI, FOCI status, or public-client status. |
| Return filtered, paginated scope metadata for one exact application ID. |
| Compare scope additions and removals between immutable ROADtools revisions. |
| Report source URLs, fetch time, cache state, and record counts; optionally refresh. |
Search responses are capped at 50 applications and support offset pagination. Exact-application responses return 25 resource grants by default, can return up to 100, and also support offset. Exact scope matching is the default; use scope_match: "contains" only when discovery is intended. Full redirect-URI arrays are omitted unless include_redirect_uris is true.
Resource matching understands display names, application IDs, identifier URIs supplied by the upstream data, and a small set of documented built-in aliases for Microsoft Graph, Azure Resource Manager, and Microsoft Defender for Endpoint. Aliases are lookup conveniences and do not assert the valid audience for every API version.
The upstream scopes values are reported as delegated OAuth scope claims (scp). The server does not reinterpret them as application roles (roles) or claim that either permission type is currently valid; accuracy remains bounded by the published source data.
Historical comparison defaults to the latest two ROADtools commits that changed firstpartyscopes.json. Results include both commit SHAs and a GitHub comparison URL, and can be filtered by application, resource/API URI, scope, or change direction. Optional base_ref and head_ref values must be full commit SHAs, keeping reports reproducible; refresh: true bypasses the normal history cache. These diffs identify published metadata changes; they do not prove that Microsoft issues or accepts the corresponding claim in a live token.
Requirements
Node.js 24 or later
Network access to GitHub raw content when the cache is empty or refreshed
No Microsoft identity, Graph permission, secret, or tenant access
Install and run
From a clone
git clone https://github.com/nathanmcnulty/mcp-entrascopes.git E:\mcp-entrascopes
Set-Location E:\mcp-entrascopes
npm ci
npm run build
codex mcp add entrascopes -- node E:\mcp-entrascopes\dist\index.jsRestart the Codex client after adding the server. The Codex desktop app, CLI, and IDE extension share the same host MCP configuration.
Directly from GitHub with npm
codex mcp add entrascopes -- npx -y github:nathanmcnulty/mcp-entrascopesThe package is prepared for npm publication but is not claimed to be published in the npm registry.
Other MCP clients can launch node dist/index.js over stdio.
Data and caching
The server lazily downloads:
firstpartyscopes.jsonfrom ROADtools as the required scope dataset.resources.jsonfrom EntraScopes for optional resource display-name enrichment.
EntraScopes periodically copies the ROADtools scope file into its website repository. This server reads the MIT-licensed ROADtools source directly, while retaining EntraScopes resource-name enrichment and attribution.
The default cache lifetime is 60 minutes. If a refresh fails and an older cache exists, the server returns the stale cache and marks the result cache-stale. The cache is stored under %LOCALAPPDATA%\mcp-entrascopes on Windows or ~/.cache/mcp-entrascopes elsewhere.
Environment variable | Default | Purpose |
|
| Cache freshness interval; |
| OS cache directory | Override the cache directory. |
| ROADtools raw URL | Override the required scope dataset URL. |
| EntraScopes raw URL | Override the optional resource-name dataset URL. |
| unset | Optional token for a higher GitHub API rate limit when resolving ROADtools revision history. |
Dataset URLs are process configuration only; MCP tool callers cannot supply arbitrary URLs.
Provenance and licensing
This repository contains server code only and does not redistribute either dataset. ROADtools is MIT-licensed. The EntraScopes repository did not declare a repository license when this project was created, so its data is fetched from the publisher at runtime and remains subject to the upstream project's terms. The Unlicense in this repository applies only to this repository's code.
This project is an independent integration and is not affiliated with or endorsed by the EntraScopes, ROADtools, or Microsoft maintainers.
Development
npm ci
npm run check
npm test
npm run build
npm pack --dry-runTests use the existing TypeScript compiler to emit source and tests into .test-dist, then run the compiled tests with Node's built-in test runner. npm test clears this directory first; npm run clean:test removes it separately. The production build still emits only source into dist.
The server uses the MCP TypeScript SDK v2 and stdio transport. Never write logs to stdout because stdout is the MCP protocol channel; operational messages go to stderr.
Security
See SECURITY.md. The server has no tenant credentials and makes only read-only HTTP GET requests to its configured dataset URLs. Review custom URL overrides before use because they change the server's network trust boundary.
Available Tools
3 toolsget_entra_applicationGet an Entra applicationARead-onlyIdempotent
Get published scope metadata for one exact Microsoft first-party application ID, optionally narrowed to a resource.
Inputs: app_id (required), resource, include_redirect_uris.
get_entrascopes_data_statusGet EntraScopes data statusARead-onlyIdempotent
Report dataset provenance, refresh time, cache origin, and record counts. Set refresh to bypass the normal cache TTL.
Inputs: refresh.
search_entra_applicationsSearch Entra applications and scopesARead-onlyIdempotent
Search Microsoft first-party applications by app name/ID, published scope, resource name/ID, FOCI status, or public-client status. This is not tenant consent state.
Inputs: foci, limit, query, scope, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Search, exact lookup by application ID, and dataset status are clearly distinct operations with no meaningful overlap. The descriptions make it easy to select the right tool.
All tools use a verb_noun pattern and snake_case. The only minor inconsistency is 'get_entrascopes_data_status' using the server name prefix instead of following the 'entra_application(s)' noun pattern used by the other two tools.
Three tools is well-scoped for a read-only reference dataset: search, exact lookup, and data status. Each tool earns its place without redundancy.
For the stated purpose of exploring Microsoft first-party application scope metadata, the surface covers search, precise retrieval, and dataset freshness/provenance. No CRUD operations are needed since this is a read-only metadata source.
Maintenance
Related MCP Connectors
Read-only AgentiScript concept search, catalog, authenticity, license, and approved asset discovery.
Least-privilege role lookup for Microsoft 365 and Azure built-in roles.
Find, document and execute authenticated API calls across 1000+ apps via one MCP server
Query and manage SquaredUp dashboards, data streams, the knowledge graph, and KPIs (EU region).
Related MCP Servers
- AlicenseAqualityBmaintenanceProvides Microsoft Entra ID / Graph permissions data to AI agents, enabling search and retrieval of application and delegated permissions as well as Microsoft first-party app details.68 npmMIT
- FlicenseNot gradedqualityCmaintenanceRead-only MCP server for querying Microsoft Purview unified audit logs across M365 workloads, wrapping the Graph API's asynchronous audit log search.-
- FlicenseNot gradedqualityCmaintenanceProvides read-only access to Microsoft Intune through the Microsoft Graph API, enabling MCP clients to query managed devices, apps, compliance policies, and configuration profiles.-
- AlicenseAqualityCmaintenanceEnables AI assistants to securely search Microsoft 365 files and list items using delegated authentication, ensuring results are trimmed to the signed-in user's permissions.39 npm2MIT