Skip to main content
Glama
mcp-entrascopes

mcp-entrascopes

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.All for 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)?

IMPORTANT

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_entra_applications

Search by application name/ID, delegated scope, resource name/ID/API URI, reply URI, FOCI status, or public-client status.

get_entra_application

Return filtered, paginated scope metadata for one exact application ID.

compare_entrascopes_scope_history

Compare scope additions and removals between immutable ROADtools revisions.

get_entrascopes_data_status

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.js

Restart 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-entrascopes

The 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:

  1. firstpartyscopes.json from ROADtools as the required scope dataset.

  2. resources.json from 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

ENTRASCOPES_CACHE_TTL_MINUTES

60

Cache freshness interval; 0 refreshes on each request.

ENTRASCOPES_CACHE_DIR

OS cache directory

Override the cache directory.

ENTRASCOPES_SCOPES_URL

ROADtools raw URL

Override the required scope dataset URL.

ENTRASCOPES_RESOURCES_URL

EntraScopes raw URL

Override the optional resource-name dataset URL.

GITHUB_TOKEN

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-run

Tests 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 tools
get_entra_applicationGet an Entra applicationA
Read-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 statusA
Read-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 scopesA
Read-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

    A4.4/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    Three tools is well-scoped for a read-only reference dataset: search, exact lookup, and data status. Each tool earns its place without redundancy.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides 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.
      6
      8 npm
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Read-only MCP server for querying Microsoft Purview unified audit logs across M365 workloads, wrapping the Graph API's asynchronous audit log search.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Provides read-only access to Microsoft Intune through the Microsoft Graph API, enabling MCP clients to query managed devices, apps, compliance policies, and configuration profiles.
      -