Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers.ts:397-459 (handler)

  Handler function that implements the core logic for managing Azure AD applications. Handles actions like list_apps, get_app, update_app, add_owner, and remove_owner using Microsoft Graph API.

  export async function handleAzureAdApps(
    graphClient: Client,
    args: AzureAdAppArgs
  ): Promise<{ content: { type: string; text: string }[] }> {
    let apiPath = '';
    let result: any;
  
    switch (args.action) {
      case 'list_apps':
        apiPath = '/applications';
        if (args.filter) {
          apiPath += `?$filter=${encodeURIComponent(args.filter)}`;
        }
        result = await graphClient.api(apiPath).get();
        break;
  
      case 'get_app':
        if (!args.appId) {
          throw new McpError(ErrorCode.InvalidParams, 'appId is required for get_app');
        }
        apiPath = `/applications/${args.appId}`;
        result = await graphClient.api(apiPath).get();
        break;
  
      case 'update_app':
        if (!args.appId || !args.appDetails) {
          throw new McpError(ErrorCode.InvalidParams, 'appId and appDetails are required for update_app');
        }
        apiPath = `/applications/${args.appId}`;
        await graphClient.api(apiPath).patch(args.appDetails);
        result = { message: 'Application updated successfully' };
        break;
  
      case 'add_owner':
        if (!args.appId || !args.ownerId) {
          throw new McpError(ErrorCode.InvalidParams, 'appId and ownerId are required for add_owner');
        }
        apiPath = `/applications/${args.appId}/owners/$ref`;
        const ownerPayload = {
          '@odata.id': `https://graph.microsoft.com/v1.0/users/${args.ownerId}`
        };
        await graphClient.api(apiPath).post(ownerPayload);
        result = { message: 'Owner added successfully' };
        break;
  
      case 'remove_owner':
        if (!args.appId || !args.ownerId) {
          throw new McpError(ErrorCode.InvalidParams, 'appId and ownerId are required for remove_owner');
        }
        // Need to get the specific owner reference ID first, as Graph requires the owner's directoryObject ID from the owners collection
        // This is a simplification; a real implementation might need to list owners first to find the correct reference ID.
        // For now, we'll assume ownerId is the directoryObject ID of the owner within the app's owners collection.
        apiPath = `/applications/${args.appId}/owners/${args.ownerId}/$ref`;
        await graphClient.api(apiPath).delete();
        result = { message: 'Owner removed successfully' };
        break;
  
      default:
        throw new McpError(ErrorCode.InvalidParams, `Invalid action: ${args.action}`);
    }
  
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  }

• src/server.ts:541-561 (registration)

  MCP server tool registration for manage_azure_ad_apps, linking to the handler function and schema.

  this.server.tool(
    "manage_azure_ad_apps",
    "Manage Azure AD application registrations including app permissions, credentials, and OAuth configurations.",
    azureAdAppSchema.shape,
    {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false},
    wrapToolHandler(async (args: AzureAdAppArgs) => {
      // Validate credentials only when tool is executed (lazy loading)
      this.validateCredentials();
      try {
        return await handleAzureAdApps(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-definitions.ts:137-146 (schema)

  Zod schema defining input parameters for the manage_azure_ad_apps tool.

  export const azureAdAppSchema = z.object({
    action: z.enum(['list_apps', 'get_app', 'update_app', 'add_owner', 'remove_owner']).describe('Azure AD application management action'),
    appId: z.string().optional().describe('Object ID of the application'),
    ownerId: z.string().optional().describe('Object ID of the user to add/remove as owner'),
    appDetails: z.object({
      displayName: z.string().optional().describe('Application display name'),
      signInAudience: z.string().optional().describe('Sign-in audience setting'),
    }).optional().describe('Application details for updates'),
    filter: z.string().optional().describe('OData filter string'),
  });

• src/tool-metadata.ts:74-77 (schema)

  Tool metadata providing description, title, and annotations (hints) for the manage_azure_ad_apps tool.

  manage_azure_ad_apps: {
    description: "Manage Azure AD application registrations including app permissions, credentials, and OAuth configurations.",
    title: "Azure AD App Manager",
    annotations: { title: "Azure AD App Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }