Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers/security-policy-handlers.ts:12-99 (handler)

  The core handler function `handleDefenderPolicies` that implements the logic for managing Microsoft Defender policies. It handles actions like list, get, create, update, delete for different policy types (safeAttachments, safeLinks, antiPhishing, etc.) using Microsoft Graph API endpoints.

  export async function handleDefenderPolicies(
    graphClient: Client,
    args: DefenderPolicyArgs
  ): Promise<{ content: { type: string; text: string }[] }> {
    let apiPath = '';
    let result: any;
  
    // Map policy types to API endpoints
    const policyEndpoints = {
      safeAttachments: '/security/attackSimulation/safeAttachmentPolicies',
      safeLinks: '/security/attackSimulation/safeLinksPolicies',
      antiPhishing: '/security/antiPhishingPolicies',
      antiMalware: '/security/antiMalwarePolicies',
      antiSpam: '/security/antiSpamPolicies'
    };
  
    const endpoint = policyEndpoints[args.policyType];
    if (!endpoint) {
      throw new McpError(ErrorCode.InvalidParams, `Unsupported policy type: ${args.policyType}`);
    }
  
    switch (args.action) {
      case 'list':
        apiPath = endpoint;
        result = await graphClient.api(apiPath).get();
        break;
  
      case 'get':
        if (!args.policyId) {
          throw new McpError(ErrorCode.InvalidParams, 'policyId is required for get action');
        }
        apiPath = `${endpoint}/${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 defenderPolicyPayload: any = {
          displayName: args.displayName,
          description: args.description || '',
          isEnabled: args.isEnabled !== undefined ? args.isEnabled : true,
          settings: args.settings || {},
          appliedTo: args.appliedTo || {}
        };
  
        apiPath = endpoint;
        result = await graphClient.api(apiPath).post(defenderPolicyPayload);
        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.isEnabled !== undefined) updatePayload.isEnabled = args.isEnabled;
        if (args.settings) updatePayload.settings = args.settings;
        if (args.appliedTo) updatePayload.appliedTo = args.appliedTo;
  
        apiPath = `${endpoint}/${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 = `${endpoint}/${args.policyId}`;
        await graphClient.api(apiPath).delete();
        result = { message: `${args.policyType} policy ${args.policyId} deleted successfully` };
        break;
  
      default:
        throw new McpError(ErrorCode.InvalidParams, `Unknown action: ${args.action}`);
    }
  
    return {
      content: [{
        type: 'text',
        text: `Defender ${args.policyType} Policy ${args.action} operation completed:\n\n${JSON.stringify(result, null, 2)}`
      }]
    };
  }

• src/schemas/policy-schemas.ts:174-205 (schema)

  Zod schema `defenderPolicyArgsSchema` defining the input parameters for the manage_defender_policies tool, including action, policyType, policyId, settings, etc.

  export const defenderPolicyArgsSchema = z.object({
    action: z.enum(['list', 'get', 'create', 'update', 'delete']).describe('Action to perform on Defender policy'),
    policyType: z.enum(['safeAttachments', 'safeLinks', 'antiPhishing', 'antiMalware', 'antiSpam']).describe('Type of Defender policy'),
    policyId: z.string().optional().describe('Defender policy ID for specific operations'),
    displayName: z.string().optional().describe('Display name for the policy'),
    description: z.string().optional().describe('Description of the policy'),
    isEnabled: z.boolean().optional().describe('Whether the policy is enabled'),
    settings: z.object({
      action: z.enum(['Block', 'Replace', 'Allow', 'DynamicDelivery']).optional().describe('Safe Attachments action'),
      redirectToRecipients: z.array(z.string()).optional().describe('Redirect recipients for Safe Attachments'),
      actionOnError: z.boolean().optional().describe('Action on error for Safe Attachments'),
      scanUrls: z.boolean().optional().describe('Scan URLs for Safe Links'),
      enableForInternalSenders: z.boolean().optional().describe('Enable Safe Links for internal senders'),
      trackClicks: z.boolean().optional().describe('Track clicks for Safe Links'),
      allowClickThrough: z.boolean().optional().describe('Allow click through for Safe Links'),
      enableMailboxIntelligence: z.boolean().optional().describe('Enable mailbox intelligence for anti-phishing'),
      enableSpoofIntelligence: z.boolean().optional().describe('Enable spoof intelligence'),
      enableUnauthenticatedSender: z.boolean().optional().describe('Enable unauthenticated sender indicators'),
      enableViaTag: z.boolean().optional().describe('Enable via tag'),
      enableFileFilter: z.boolean().optional().describe('Enable file filter for anti-malware'),
      fileTypes: z.array(z.string()).optional().describe('File types to filter'),
      zap: z.boolean().optional().describe('Enable Zero-hour Auto Purge'),
      bulkThreshold: z.number().optional().describe('Bulk email threshold'),
      quarantineRetentionPeriod: z.number().optional().describe('Quarantine retention period in days'),
      enableEndUserSpamNotifications: z.boolean().optional().describe('Enable end user spam notifications'),
    }).optional().describe('Policy settings'),
    appliedTo: z.object({
      recipientDomains: z.array(z.string()).optional().describe('Recipient domains'),
      recipientGroups: z.array(z.string()).optional().describe('Recipient groups'),
      recipients: z.array(z.string()).optional().describe('Individual recipients'),
    }).optional().describe('Policy application scope'),
  });

• src/server.ts:1143-1162 (registration)

  Tool registration in the MCP server: registers 'manage_defender_policies' tool with schema, annotations, and handler `handleDefenderPolicies` wrapped with error handling.

  this.server.tool(
    "manage_defender_policies",
    "Manage Microsoft Defender for Office 365 policies including Safe Attachments, Safe Links, anti-phishing, and anti-malware.",
    defenderPolicyArgsSchema.shape,
    {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false},
    wrapToolHandler(async (args: DefenderPolicyArgs) => {
      this.validateCredentials();
      try {
        return await handleDefenderPolicies(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/tool-metadata.ts:245-248 (schema)

  Tool metadata definition providing description, title, and annotations for the manage_defender_policies tool, used for MCP discovery.

  manage_defender_policies: {
    description: "Manage Microsoft Defender for Office 365 policies including Safe Attachments, Safe Links, anti-phishing, and anti-malware.",
    title: "Defender Policy Manager",
    annotations: { title: "Defender Policy Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }