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.
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?
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.
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: Entra Permissions MCP Server
Tool | Purpose |
| Search by application name/ID, scope, resource name/ID, FOCI status, or public-client status. |
| Return published scope metadata for one exact application ID. |
| Report source URLs, fetch time, cache state, and record counts; optionally refresh. |
Search responses are capped at 50 applications. Exact scope matching is the default; use scope_match: "contains" only when discovery is intended.
Node.js 20 or later
Network access to GitHub raw content when the cache is empty or refreshed
No Microsoft identity, Graph permission, secret, or tenant access
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.
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.
The server lazily downloads:
firstpartyscopes.json from ROADtools as the required scope dataset.
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 |
|
| 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. |
Dataset URLs are process configuration only; MCP tool callers cannot supply arbitrary URLs.
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.
npm ci
npm run check
npm test
npm run build
npm pack --dry-runThe 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.
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.
Get published scope metadata for one exact Microsoft first-party application ID, optionally narrowed to a resource.
| Name | Required | Description | Default |
|---|---|---|---|
| app_id | Yes | Exact application (client) ID. | |
| resource | No | Optional resource display name or resource app ID filter. | |
| include_redirect_uris | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior, lowering the burden. The description adds useful context beyond that: it specifies the output is 'published scope metadata' and that the tool applies to 'Microsoft first-party application' IDs, which are behavioral constraints not present in the annotations. It doesn't mention auth or rate limits, but those are less critical given the annotation profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the main action, scope, and optional parameter without any fluff or repetition. Every word contributes to understanding the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no output schema, and annotations covering safety, the description provides the essential purpose, the exact-match behavior, and the optional resource filter. However, it omits any mention of the include_redirect_uris parameter, which lacks a schema description, leaving a small but meaningful gap for an agent deciding whether to set it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (app_id and resource have descriptions, include_redirect_uris does not). The description adds meaning to app_id (exact, first-party) and resource (optional narrowing), but it does not compensate for include_redirect_uris, which remains undocumented in both schema and description. This is adequate but partial, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), resource ('published scope metadata'), and target ('one exact Microsoft first-party application ID'), and notes an optional narrowing ('optionally narrowed to a resource'). This clearly distinguishes it from siblings like search_entra_applications (search vs exact lookup) and get_entrascopes_data_status (status vs metadata).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes its usage context explicit by specifying it is for 'one exact Microsoft first-party application ID', which implies this is for precise lookups when the ID is known. However, it does not explicitly mention alternative tools or when not to use it, stopping short of a full when/when-not comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report dataset provenance, refresh time, cache origin, and record counts. Set refresh to bypass the normal cache TTL.
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations by explaining that setting 'refresh' bypasses the normal cache TTL, giving the agent an understanding of cache behavior. It does not mention additional side effects, but the annotation coverage lowers the bar and this context is genuinely useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero wasted words. The first sentence front-loads what the tool reports, and the second gives the only behavioral note. Every sentence earns its place, and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description appropriately lists the return information categories (provenance, refresh time, cache origin, record counts). The tool has only one optional parameter, and annotations cover idempotency and read-only behavior. There is no missing information an agent needs to call this tool correctly; the description is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the missing parameter documentation. It does so by explaining the sole parameter: 'Set refresh to bypass the normal cache TTL.' This adds meaning beyond the bare boolean type and default value in the schema. It does not fully explain the default behavior (e.g., what happens when refresh is false) but the default is implicit in the schema and the description gives the key semantic.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Report') and a well-defined resource ('dataset provenance, refresh time, cache origin, and record counts'). This clearly distinguishes it from sibling tools, which target application lookups (search_entra_applications, get_entra_application). An agent immediately understands the tool's purpose without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: call this tool when you need dataset status information. It does not explicitly mention alternatives or provide when-not-to-use guidance, though the sibling names make the distinction obvious. The 'Set refresh' tip is a parameter usage note, not a tool-selection criterion, so guidance is only implied, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| foci | No | Filter family-of-client-IDs applications. | |
| limit | No | ||
| query | No | Partial application name or app ID. | |
| scope | No | OAuth scope name to match. | |
| resource | No | Partial resource display name or resource app ID. | |
| scope_match | No | exact | |
| public_client | No | Filter public client applications. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by limiting the search to 'Microsoft first-party applications' and explicitly stating it is not tenant consent state, which prevents misuse. It does not mention rate limits, pagination, or result-set behavior, but given the strong annotation coverage, the added context justifies a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first front-loads the verb and resource with an efficient list of filter dimensions; the second adds a crucial distinction without fluff. Every sentence earns its place, and there is zero redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 7 optional parameters and no output schema, the description clearly states the search scope and a key exclusion, which is the core information an agent needs. It does not explicitly describe the return format (list of applications) or how filters combine (AND vs OR), but the tool's name and sibling context imply a list result. The omission of result semantics and filter combination logic keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 71%, and the description maps the search dimensions to most parameters (query, scope, resource, foci, public_client), reinforcing their purpose. However, it adds little beyond the schema's own parameter descriptions, and it does not clarify the 'limit' parameter or the meaning of 'scope_match' (exact vs contains). The description partially compensates but leaves gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Search') and resource (Microsoft first-party applications), then enumerates the search dimensions: app name/ID, published scope, resource name/ID, FOCI status, and public-client status. The closing sentence ('This is not tenant consent state') distinguishes the tool from what it does not do, making it easy to differentiate from the sibling get_entrascapes_data_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states what the tool searches and lists the filter dimensions, giving an agent a solid sense of when to invoke it. It also calls out a critical exclusion ('This is not tenant consent state'), but it does not explicitly name sibling tools or say 'use get_entra_application instead when you need a specific app's details.' This is clear context but lacks explicit alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_entra_applicationget_entrascopes_data_statussearch_entra_applicationsScored 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.
Read-only AgentiScript concept search, catalog, authenticity, license, and approved asset discovery.
Read-only ArcadeOps discovery for developer docs, OAuth, OpenAPI and synthetic sandbox.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Remote MCP for A2A caller identity, scope policy, verdict receipts, and audit history.
