Skip to main content
Glama
devyhan

ms-graph-mcp

by devyhan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Call Microsoft Graph directly

graph_request
Read-onlyIdempotent

Send an arbitrary Microsoft Graph API request and get the raw JSON response, useful when no dedicated tool covers the endpoint.

Instructions

Sends an arbitrary request to Microsoft Graph and returns the raw JSON response. Use this only when no purpose-built tool covers the endpoint: the dedicated tools project and trim their results, while this one returns everything Graph sends, which is often far more text. The host is fixed to this tenant's Graph endpoint and path must be relative, so an absolute URL is rejected. GET is always available; the write methods require --allow-generic-write. Pass maxPages to follow @odata.nextLink, and prefer $select and $top in query to keep the response small. The call authenticates with the minimal scope guessed from path, so a path whose scope is granted succeeds even when an unrelated scope is missing; pass scopes to override the guess.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
bodyNoRequest body for a write method, as JSON. Ignored for GET. A string is sent as raw bytes (which is what Graph content endpoints expect); anything else is JSON-encoded.
pathYesGraph-relative path beginning with "/", e.g. "/me/messages" or "/users/alice@contoso.com/drive/root/children". Never a full URL: the host is fixed and an absolute URL is rejected. A "?query" suffix is accepted and merged with the `query` argument, but passing options in `query` is clearer.
queryNoQuery string parameters, e.g. {"$select":"id,subject","$top":"10"}. Values are sent verbatim, so OData operators belong here rather than spliced into `path`.
methodNoHTTP method. Defaults to GET. The write methods are refused unless the server was started with --allow-generic-write, and always under --read-only.
scopesNoScopes to request a token for. Defaults to the minimal scope guessed from `path` (Mail.Read for a mail path, Chat.Read for a chat path, and so on), falling back to the union of every enabled group when the path matches nothing known. Pass an explicit list only when the endpoint needs a scope the guess does not cover.
versionNoGraph endpoint. Defaults to the server default (v1.0). "beta" is refused unless the server was started with --beta; beta resources can change without notice.
maxPagesNoHow many pages of a collection to follow via @odata.nextLink, 1-5. Defaults to 1 (no paging). Pages are merged into a single value array.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.0
    • addedInput schema / properties / scopes
      Added value: +{
+  "description": "Scopes to request a token for. Defaults to the minimal scope guessed from `path` (Mail.Read for a mail path, Chat.Read for a chat path, and so on), falling back to the union of every enabled group when the path matches nothing known. Pass an explicit list only when the endpoint needs a scope the guess does not cover.",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "minItems": 1,
+  "type": "array"
+}
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description reconciles the safety profile rather than contradicting it: it discloses that GET is unconditional while write methods are gated behind --allow-generic-write, consistent with readOnlyHint/destructiveHint being defaults. It also adds behavior no structured field carries — absolute URLs are rejected, maxPages follows @odata.nextLink, and the token scope is guessed from `path` with a fallback to the union of enabled groups.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose then constraints, and nearly every sentence carries a distinct fact (alternatives, host/path rule, method gating, paging, scope resolution). The prose is dense with semicolon-joined clauses, which is slightly wall-of-text, but appropriate for a 7-parameter generic tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by characterizing the return value (raw JSON, often far more text than the purpose-built tools). For a tool with nested objects, enums, and configuration-dependent write/auth behavior, all decision-relevant facts — path form, write gating, beta gating, paging limit, scope override — are present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description earns one extra point by adding operational meaning on top of field docs — which parameters matter ($select/$top in `query`, `maxPages` for paging) and that `scopes` exists specifically to override the path-based guess. It stops short of adding syntax detail the schema doesn't already give.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource ("sends an arbitrary request to Microsoft Graph and returns the raw JSON response") and immediately distinguishes itself from the large set of purpose-built siblings ("the dedicated tools project and trim their results, while this one returns everything Graph sends"). An agent can tell this is the generic escape hatch without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly scopes when to use it: "Use this only when no purpose-built tool covers the endpoint," which names the alternative category (47 purpose-built siblings) and the condition that selects this tool. It also states the write-method prerequisite (--allow-generic-write / --read-only) and gives efficiency advice ($select, $top) — real operational guidance, not just context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools