Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/server.ts:1436-1490 (registration)

  Registers the manage_graph_subscriptions tool with inline handler logic that uses GraphAdvancedFeatures class methods based on the 'action' parameter (create, update, delete, list). Includes inline input schema.
  const graphSubscriptionsMeta = getToolMetadata("manage_graph_subscriptions")!; this.server.tool( "manage_graph_subscriptions", graphSubscriptionsMeta.description, z.object({ action: z.enum(['create', 'update', 'delete', 'list']).describe('Subscription management action'), subscriptionId: z.string().optional().describe('Subscription ID for update/delete operations'), subscription: webhookSubscriptionSchema.optional().describe('Subscription details for create/update'), updates: webhookSubscriptionSchema.partial().optional().describe('Updates for existing subscription') }).shape, graphSubscriptionsMeta.annotations || {}, wrapToolHandler(async (args: any) => { this.validateCredentials(); try { const advancedFeatures = new GraphAdvancedFeatures(this.getGraphClient(), this.getAccessToken.bind(this)); let result: any; switch (args.action) { case 'create': if (!args.subscription) { throw new McpError(ErrorCode.InvalidParams, 'Subscription details required for create action'); } result = await advancedFeatures.createSubscription(args.subscription); break; case 'update': if (!args.subscriptionId || !args.updates) { throw new McpError(ErrorCode.InvalidParams, 'Subscription ID and updates required for update action'); } result = await advancedFeatures.updateSubscription(args.subscriptionId, args.updates); break; case 'delete': if (!args.subscriptionId) { throw new McpError(ErrorCode.InvalidParams, 'Subscription ID required for delete action'); } result = await advancedFeatures.deleteSubscription(args.subscriptionId); break; case 'list': result = await advancedFeatures.listSubscriptions(); break; default: throw new McpError(ErrorCode.InvalidParams, `Invalid action: ${args.action}`); } return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }; } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError( ErrorCode.InternalError, `Error managing subscriptions: ${error instanceof Error ? error.message : 'Unknown error'}` ); } }) );
• src/utils/graph-advanced-features.ts:102-213 (handler)

  Core handler methods in GraphAdvancedFeatures class for managing Microsoft Graph webhook subscriptions: createSubscription, updateSubscription, deleteSubscription, listSubscriptions. Called by the tool handler in server.ts.
  async createSubscription(subscription: WebhookSubscription): Promise<SubscriptionResponse> { const subscriptionPayload: any = { changeType: subscription.changeTypes.join(','), notificationUrl: subscription.notificationUrl, resource: subscription.resource, expirationDateTime: subscription.expirationDateTime || this.getDefaultExpiration(), clientState: subscription.clientState, latestSupportedTlsVersion: subscription.tlsVersion || 'v1_2' }; // Add lifecycle notification URL if provided if (subscription.lifecycleNotificationUrl) { subscriptionPayload.lifecycleNotificationUrl = subscription.lifecycleNotificationUrl; } try { const response = await this.graphClient .api('/subscriptions') .post(subscriptionPayload); return { id: response.id, resource: response.resource, changeType: response.changeType, notificationUrl: response.notificationUrl, expirationDateTime: response.expirationDateTime, clientState: response.clientState, createdAt: new Date().toISOString() }; } catch (error) { throw new McpError( ErrorCode.InternalError, `Failed to create subscription: ${error instanceof Error ? error.message : 'Unknown error'}` ); } } // Update existing subscription async updateSubscription(subscriptionId: string, updates: Partial<WebhookSubscription>): Promise<SubscriptionResponse> { const updatePayload: any = {}; if (updates.expirationDateTime) { updatePayload.expirationDateTime = updates.expirationDateTime; } if (updates.notificationUrl) { updatePayload.notificationUrl = updates.notificationUrl; } try { const response = await this.graphClient .api(`/subscriptions/${subscriptionId}`) .patch(updatePayload); return { id: response.id, resource: response.resource, changeType: response.changeType, notificationUrl: response.notificationUrl, expirationDateTime: response.expirationDateTime, clientState: response.clientState, updatedAt: new Date().toISOString() }; } catch (error) { throw new McpError( ErrorCode.InternalError, `Failed to update subscription: ${error instanceof Error ? error.message : 'Unknown error'}` ); } } // Delete subscription async deleteSubscription(subscriptionId: string): Promise<{ deleted: boolean; deletedAt: string }> { try { await this.graphClient .api(`/subscriptions/${subscriptionId}`) .delete(); return { deleted: true, deletedAt: new Date().toISOString() }; } catch (error) { throw new McpError( ErrorCode.InternalError, `Failed to delete subscription: ${error instanceof Error ? error.message : 'Unknown error'}` ); } } // List all subscriptions async listSubscriptions(): Promise<SubscriptionResponse[]> { try { const response = await this.graphClient .api('/subscriptions') .get(); return response.value.map((sub: any) => ({ id: sub.id, resource: sub.resource, changeType: sub.changeType, notificationUrl: sub.notificationUrl, expirationDateTime: sub.expirationDateTime, clientState: sub.clientState })); } catch (error) { throw new McpError( ErrorCode.InternalError, `Failed to list subscriptions: ${error instanceof Error ? error.message : 'Unknown error'}` ); } }
• src/utils/graph-advanced-features.ts:415-423 (schema)

  Zod schema for WebhookSubscription input parameters, used directly in the tool's inline schema (as subscription and updates).
  export const webhookSubscriptionSchema = z.object({ resource: z.string().describe('Graph resource to monitor'), changeTypes: z.array(z.enum(['created', 'updated', 'deleted'])).describe('Types of changes to monitor'), notificationUrl: z.string().url().describe('Webhook endpoint URL'), expirationDateTime: z.string().optional().describe('Subscription expiration (ISO 8601)'), clientState: z.string().optional().describe('Client state for validation'), lifecycleNotificationUrl: z.string().url().optional().describe('Lifecycle notification URL'), tlsVersion: z.enum(['v1_0', 'v1_1', 'v1_2', 'v1_3']).optional().describe('Minimum TLS version') });
• src/utils/graph-advanced-features.ts:332-351 (helper)

  TypeScript interfaces for WebhookSubscription input and SubscriptionResponse output used by the subscription management methods.
  export interface WebhookSubscription { resource: string; changeTypes: ('created' | 'updated' | 'deleted')[]; notificationUrl: string; expirationDateTime?: string; clientState?: string; lifecycleNotificationUrl?: string; tlsVersion?: 'v1_0' | 'v1_1' | 'v1_2' | 'v1_3'; } export interface SubscriptionResponse { id: string; resource: string; changeType: string; notificationUrl: string; expirationDateTime: string; clientState?: string; createdAt?: string; updatedAt?: string; }
• src/tool-metadata.ts:218-222 (registration)

  Tool metadata registration providing description, title, and annotations (readOnlyHint, destructiveHint, etc.) for the manage_graph_subscriptions tool, used during tool registration in server.ts.
  manage_graph_subscriptions: { description: "Manage webhook subscriptions for real-time change notifications from Microsoft Graph resources.", title: "Graph Subscription Manager", annotations: { title: "Graph Subscription Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true } },