Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers/conditional-access-handler.ts:6-112 (handler)

  The core handler function implementing the tool logic. Handles actions: list, get, create, update, delete, enable, disable Conditional Access policies using Microsoft Graph API endpoints.
  export async function handleConditionalAccessPolicies( graphClient: Client, args: ConditionalAccessPolicyArgs ): Promise<{ content: { type: string; text: string }[] }> { let apiPath = ''; let result: any; switch (args.action) { case 'list': // List all Conditional Access policies apiPath = '/identity/conditionalAccess/policies'; result = await graphClient.api(apiPath).get(); break; case 'get': if (!args.policyId) { throw new McpError(ErrorCode.InvalidParams, 'policyId is required for get action'); } apiPath = `/identity/conditionalAccess/policies/${args.policyId}`; result = await graphClient.api(apiPath).get(); break; case 'create': if (!args.displayName) { throw new McpError(ErrorCode.InvalidParams, 'displayName is required for create action'); } const caPolicyPayload: any = { displayName: args.displayName, description: args.description || '', state: args.state || 'disabled', conditions: args.conditions || { users: { includeUsers: ['All'] }, applications: { includeApplications: ['All'] } }, grantControls: args.grantControls || { operator: 'OR', builtInControls: ['mfa'] } }; // Add session controls if provided if (args.sessionControls) { caPolicyPayload.sessionControls = args.sessionControls; } apiPath = '/identity/conditionalAccess/policies'; result = await graphClient.api(apiPath).post(caPolicyPayload); break; case 'update': if (!args.policyId) { throw new McpError(ErrorCode.InvalidParams, 'policyId is required for update action'); } const updatePayload: any = {}; if (args.displayName) updatePayload.displayName = args.displayName; if (args.description) updatePayload.description = args.description; if (args.state) updatePayload.state = args.state; if (args.conditions) updatePayload.conditions = args.conditions; if (args.grantControls) updatePayload.grantControls = args.grantControls; if (args.sessionControls) updatePayload.sessionControls = args.sessionControls; apiPath = `/identity/conditionalAccess/policies/${args.policyId}`; result = await graphClient.api(apiPath).patch(updatePayload); break; case 'delete': if (!args.policyId) { throw new McpError(ErrorCode.InvalidParams, 'policyId is required for delete action'); } apiPath = `/identity/conditionalAccess/policies/${args.policyId}`; await graphClient.api(apiPath).delete(); result = { message: `Conditional Access policy ${args.policyId} deleted successfully` }; break; case 'enable': if (!args.policyId) { throw new McpError(ErrorCode.InvalidParams, 'policyId is required for enable action'); } apiPath = `/identity/conditionalAccess/policies/${args.policyId}`; result = await graphClient.api(apiPath).patch({ state: 'enabled' }); break; case 'disable': if (!args.policyId) { throw new McpError(ErrorCode.InvalidParams, 'policyId is required for disable action'); } apiPath = `/identity/conditionalAccess/policies/${args.policyId}`; result = await graphClient.api(apiPath).patch({ state: 'disabled' }); break; default: throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${args.action}`); } return { content: [{ type: 'text', text: `Conditional Access Policy ${args.action} operation completed:\n\n${JSON.stringify(result, null, 2)}` }] }; }
• src/server.ts:1122-1140 (registration)

  MCP server tool registration for 'manage_conditional_access_policies', specifying schema, annotations, and linking to the handler function.
  "manage_conditional_access_policies", "Manage Azure AD conditional access policies for zero-trust security including MFA, device compliance, and location-based controls.", conditionalAccessPolicyArgsSchema.shape, {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false}, wrapToolHandler(async (args: ConditionalAccessPolicyArgs) => { this.validateCredentials(); try { return await handleConditionalAccessPolicies(this.getGraphClient(), args); } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError( ErrorCode.InternalError, `Error executing tool: ${error instanceof Error ? error.message : 'Unknown error'}` ); } }) );
• src/schemas/policy-schemas.ts:108-171 (schema)

  Zod input schema (conditionalAccessPolicyArgsSchema) for tool parameter validation, including detailed structures for conditions, grant controls, and session controls.
  export const conditionalAccessPolicyArgsSchema = z.object({ action: z.enum(['list', 'get', 'create', 'update', 'delete', 'enable', 'disable']).describe('Action to perform on Conditional Access policy'), policyId: z.string().optional().describe('Conditional Access policy ID for specific operations'), displayName: z.string().optional().describe('Display name for the policy'), description: z.string().optional().describe('Description of the policy'), state: z.enum(['enabled', 'disabled', 'enabledForReportingButNotEnforced']).optional().describe('Policy state'), conditions: z.object({ users: z.object({ includeUsers: z.array(z.string()).optional().describe('Users to include'), excludeUsers: z.array(z.string()).optional().describe('Users to exclude'), includeGroups: z.array(z.string()).optional().describe('Groups to include'), excludeGroups: z.array(z.string()).optional().describe('Groups to exclude'), includeRoles: z.array(z.string()).optional().describe('Roles to include'), excludeRoles: z.array(z.string()).optional().describe('Roles to exclude'), }).optional().describe('User conditions'), applications: z.object({ includeApplications: z.array(z.string()).optional().describe('Applications to include'), excludeApplications: z.array(z.string()).optional().describe('Applications to exclude'), includeUserActions: z.array(z.string()).optional().describe('User actions to include'), }).optional().describe('Application conditions'), locations: z.object({ includeLocations: z.array(z.string()).optional().describe('Locations to include'), excludeLocations: z.array(z.string()).optional().describe('Locations to exclude'), }).optional().describe('Location conditions'), devices: z.object({ includeDevices: z.array(z.string()).optional().describe('Devices to include'), excludeDevices: z.array(z.string()).optional().describe('Devices to exclude'), deviceFilter: z.object({ mode: z.enum(['include', 'exclude']).describe('Filter mode'), rule: z.string().describe('Filter rule'), }).optional().describe('Device filter'), }).optional().describe('Device conditions'), platforms: z.object({ includePlatforms: z.array(z.string()).optional().describe('Platforms to include'), excludePlatforms: z.array(z.string()).optional().describe('Platforms to exclude'), }).optional().describe('Platform conditions'), signInRisk: z.object({ riskLevels: z.array(z.enum(['low', 'medium', 'high', 'none'])).describe('Sign-in risk levels'), }).optional().describe('Sign-in risk conditions'), userRisk: z.object({ riskLevels: z.array(z.enum(['low', 'medium', 'high', 'none'])).describe('User risk levels'), }).optional().describe('User risk conditions'), }).optional().describe('Policy conditions'), grantControls: z.object({ operator: z.enum(['AND', 'OR']).describe('Grant controls operator'), builtInControls: z.array(z.enum(['block', 'mfa', 'compliantDevice', 'domainJoinedDevice', 'approvedApplication', 'compliantApplication'])).optional().describe('Built-in controls'), customAuthenticationFactors: z.array(z.string()).optional().describe('Custom authentication factors'), termsOfUse: z.array(z.string()).optional().describe('Terms of use'), }).optional().describe('Grant controls'), sessionControls: z.object({ applicationEnforcedRestrictions: z.boolean().optional().describe('Application enforced restrictions'), cloudAppSecurity: z.object({ isEnabled: z.boolean().describe('Enable cloud app security'), cloudAppSecurityType: z.enum(['mcasConfigured', 'monitorOnly', 'blockDownloads']).optional().describe('Cloud app security type'), }).optional().describe('Cloud app security controls'), signInFrequency: z.object({ value: z.number().describe('Sign-in frequency value'), type: z.enum(['hours', 'days']).describe('Sign-in frequency type'), }).optional().describe('Sign-in frequency controls'), persistentBrowser: z.object({ mode: z.enum(['always', 'never']).describe('Persistent browser mode'), }).optional().describe('Persistent browser controls'), }).optional().describe('Session controls'), });
• src/types/policy-types.ts:109-172 (schema)

  TypeScript type definition (ConditionalAccessPolicyArgs) used by the handler for type safety.
  export interface ConditionalAccessPolicyArgs { action: 'list' | 'get' | 'create' | 'update' | 'delete' | 'enable' | 'disable'; policyId?: string; displayName?: string; description?: string; state?: 'enabled' | 'disabled' | 'enabledForReportingButNotEnforced'; conditions?: { users?: { includeUsers?: string[]; excludeUsers?: string[]; includeGroups?: string[]; excludeGroups?: string[]; includeRoles?: string[]; excludeRoles?: string[]; }; applications?: { includeApplications?: string[]; excludeApplications?: string[]; includeUserActions?: string[]; }; locations?: { includeLocations?: string[]; excludeLocations?: string[]; }; devices?: { includeDevices?: string[]; excludeDevices?: string[]; deviceFilter?: { mode: 'include' | 'exclude'; rule: string; }; }; platforms?: { includePlatforms?: string[]; excludePlatforms?: string[]; }; signInRisk?: { riskLevels: ('low' | 'medium' | 'high' | 'none')[]; }; userRisk?: { riskLevels: ('low' | 'medium' | 'high' | 'none')[]; }; }; grantControls?: { operator: 'AND' | 'OR'; builtInControls?: ('block' | 'mfa' | 'compliantDevice' | 'domainJoinedDevice' | 'approvedApplication' | 'compliantApplication')[]; customAuthenticationFactors?: string[]; termsOfUse?: string[]; }; sessionControls?: { applicationEnforcedRestrictions?: boolean; cloudAppSecurity?: { isEnabled: boolean; cloudAppSecurityType?: 'mcasConfigured' | 'monitorOnly' | 'blockDownloads'; }; signInFrequency?: { value: number; type: 'hours' | 'days'; }; persistentBrowser?: { mode: 'always' | 'never'; }; }; }
• src/tool-metadata.ts:235-238 (helper)

  Tool metadata providing description, title, and annotations for UI/tool discovery.
  manage_conditional_access_policies: { description: "Manage Azure AD conditional access policies for zero-trust security including MFA, device compliance, and location-based controls.", title: "Conditional Access Policy Manager", annotations: { title: "Conditional Access Policy Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }