Skip to main content
Glama
Softeria

Microsoft 365 MCP Server

by Softeria
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

create-subscription

create-subscription
Destructive

Subscribes a listener application to receive change notifications when the requested type of changes occur to the specified resource in Microsoft Graph.

Instructions

Subscribes a listener application to receive change notifications when the requested type of changes occur to the specified resource in Microsoft Graph. To identify the resources for which you can create subscriptions and the limitations on subscriptions, see Set up notifications for changes in resource data: Supported resources. Some resources support rich notifications, that is, notifications that include resource data. For more information about these resources, see Set up change notifications that include resource data: Supported resources.

šŸ’” TIP: Creates a webhook subscription for change notifications. Required body: { changeType (comma-separated: 'created,updated,deleted'), notificationUrl (HTTPS, must validate with token echo), resource (e.g. '/me/mailFolders/inbox/messages', '/users/{id}/events', '/teams/{id}/channels/{id}/messages'), expirationDateTime (ISO 8601, max varies by resource type ā€” 1 hour for calls, 24h for messages, 3 days for mail), clientState (opaque string returned in notifications, for validation) }. Optional: includeResourceData (true enables rich notifications, requires encryptionCertificate + encryptionCertificateId). No dedicated scope ā€” caller must have a read permission for the target resource (e.g. Mail.Read, Calendars.Read, ChannelMessage.Read.All, Files.Read.All).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
bodyYes
confirmNoFor destructive operations when the confirm gate is enabled (MS365_MCP_REQUIRE_CONFIRM=true; off by default). Set to true only after the user has explicitly approved this action. When the gate is on, calls without confirm: true return { error: "confirmation_required" } without touching user data.
includeHeadersNoInclude response headers (including ETag) in the response metadata
excludeResponseNoExclude the full response body and only return success or failure indication

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.166.0
    • addedInput schema / properties / body / properties / vapidPublicKey
      Added value: +{
+  "description": "Optional. The application server's VAPID public key, base64url-encoded (P-256 uncompressed point, 65 bytes pre-encoding). Obtained by calling the getVapidPublicKey function on the subscription collection. The browser passes this value to PushManager.subscribe({ applicationServerKey: vapidPublicKey }) to bind the push subscription to this server identity. Required when notificationUrl targets a known Web Push service origin (for example, *.push.apple.com, fcm.googleapis.com, updates.push.services.mozilla.com); rejected with 400 Bad Request if supplied on a standard webhook subscription. For more information, see RFC 8292.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • addedInput schema / properties / body / properties / webPushEncryptionP256dhPublicKey
      Added value: +{
+  "description": "Optional. The subscriber's ECDH public key, base64url-encoded (P-256 uncompressed point, 65 bytes pre-encoding). Obtained from the browser via PushSubscription.getKey('p256dh'). Used as the peer public key during ECDH key agreement to derive the per-message content encryption key for RFC 8291 payload encryption. Required when notificationUrl targets a known Web Push service origin; rejected with 400 Bad Request if supplied on a standard webhook subscription. For more information, see RFC 8291 Section 3.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • addedInput schema / properties / body / properties / webPushEncryptionSecret
      Added value: +{
+  "description": "Optional. The subscriber's auth secret, base64url-encoded (16 bytes pre-encoding). Obtained from the browser via PushSubscription.getKey('auth'). Used as the HMAC-SHA-256 salt for the HKDF combine step that derives key material for RFC 8291 payload encryption. Write-only: this value is never returned in GET responses (returned as null). Treat as a secret. Required when notificationUrl targets a known Web Push service origin; rejected with 400 Bad Request if supplied on a standard webhook subscription. For more information, see RFC 8291 Section 3.",
+  "type": [
+    "string",
+    "null"
+  ]
+}
  2. Changed1 schema field changedv0.131.2
    • changedInput schema / additionalProperties
      Previous value: -falseNew value: +true
  3. Changed1 schema field changedv0.131.1
    • addedInput schema / properties / confirm
      Added value: +{
+  "description": "For destructive operations when the confirm gate is enabled (MS365_MCP_REQUIRE_CONFIRM=true; off by default). Set to true only after the user has explicitly approved this action. When the gate is on, calls without confirm: true return { error: \"confirmation_required\" } without touching user data.",
+  "type": "boolean"
+}
  4. Addedv0.114.0
  5. Removedv0.112.2
  6. Addedv0.110.0
  7. Removedv0.108.0
  8. Addedv0.96.0

TDQS

A4.2/5.0
Behavior4/5

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

Annotations declare destructiveHint=true and openWorldHint=true, but the description adds substantial behavioral context beyond them: expiration limits vary per resource (1h calls, 24h messages, 3d mail), notificationUrl must validate via token echo, and rich notifications require encryptionCertificate + encryptionCertificateId. It does not explain what happens on subscription failure or the lifecycle notification handshake, but it goes well beyond the annotations.

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

Conciseness3/5

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

The opening paragraph is largely boilerplate Microsoft documentation with cross-references ('see Set up notifications for changes in resource data: Supported resources') that an agent cannot follow. The TIP block that follows is dense and useful, but it is placed after the boilerplate rather than front-loaded, and there is some redundancy with the schema descriptions.

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

Completeness4/5

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

For a complex nested-object mutation with no output schema, the description covers the required body fields, permission prerequisites, expiration constraints, and rich-notification requirements well. Minor gaps remain around response/return behavior and failure modes, but an agent has enough to call it correctly.

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 coverage is 75%, so the schema already documents most body fields, but the description adds meaning the schema does not: comma-separated changeType values, concrete resource path examples, per-resource expiration ceilings, and the clientState validation purpose. This materially extends parameter understanding beyond the structured fields.

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 specific verb and resource: subscribes a listener application to receive change notifications for a specified resource in Microsoft Graph. It is clearly distinguishable from the subscription siblings (list-, get-, update-, delete-, reauthorize-subscription), which all operate on existing subscriptions rather than creating one.

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

Usage Guidelines4/5

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

Provides concrete usage context ā€” required body shape, HTTPS requirement, the token-echo validation handshake, and the fact that no dedicated scope exists so the caller needs a read permission for the target resource (Mail.Read, Calendars.Read, etc.). It does not explicitly route the agent between this tool and update-subscription/reauthorize-subscription when a subscription already exists, so it stops short of full when/when-not guidance.

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