Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers.ts:518-571 (handler)

  The core handler function implementing the manage_service_principals tool logic. Handles actions like listing service principals (GET /servicePrincipals), getting specific SP, adding/removing owners via Graph API.

  export async function handleServicePrincipals(
    graphClient: Client,
    args: AzureAdSpArgs
  ): Promise<{ content: { type: string; text: string }[] }> {
    let apiPath = '';
    let result: any;
  
    switch (args.action) {
      case 'list_sps':
        apiPath = '/servicePrincipals';
        if (args.filter) {
          apiPath += `?$filter=${encodeURIComponent(args.filter)}`;
        }
        result = await graphClient.api(apiPath).get();
        break;
  
      case 'get_sp':
        if (!args.spId) {
          throw new McpError(ErrorCode.InvalidParams, 'spId is required for get_sp');
        }
        apiPath = `/servicePrincipals/${args.spId}`;
        result = await graphClient.api(apiPath).get();
        break;
  
      case 'add_owner':
        if (!args.spId || !args.ownerId) {
          throw new McpError(ErrorCode.InvalidParams, 'spId and ownerId are required for add_owner');
        }
        // Requires Application.ReadWrite.All or Directory.ReadWrite.All
        apiPath = `/servicePrincipals/${args.spId}/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 to Service Principal' };
        break;
  
      case 'remove_owner':
        if (!args.spId || !args.ownerId) {
          throw new McpError(ErrorCode.InvalidParams, 'spId and ownerId are required for remove_owner');
        }
        // Requires Application.ReadWrite.All or Directory.ReadWrite.All
        // Similar to app owners, requires the directoryObject ID of the owner relationship
        apiPath = `/servicePrincipals/${args.spId}/owners/${args.ownerId}/$ref`;
        await graphClient.api(apiPath).delete();
        result = { message: 'Owner removed successfully from Service Principal' };
        break;
  
      default:
        throw new McpError(ErrorCode.InvalidParams, `Invalid action: ${args.action}`);
    }
  
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  }

• src/server.ts:587-607 (registration)

  Registers the 'manage_service_principals' tool with the MCP server, associating it with the handleServicePrincipals handler, input schema (azureAdSpSchema), and metadata annotations.

  this.server.tool(
    "manage_service_principals",
    "Manage service principals for application access including permissions, credentials, and enterprise applications.",
    azureAdSpSchema.shape,
    {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false},
    wrapToolHandler(async (args: AzureAdSpArgs) => {
      // Validate credentials only when tool is executed (lazy loading)
      this.validateCredentials();
      try {
        return await handleServicePrincipals(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:156-161 (schema)

  Zod schema defining the input parameters and validation for the manage_service_principals tool (azureAdSpSchema), used in tool registration.

  export const azureAdSpSchema = z.object({
    action: z.enum(['list_sps', 'get_sp', 'add_owner', 'remove_owner']).describe('Service principal management action'),
    spId: z.string().optional().describe('Object ID of the Service Principal'),
    ownerId: z.string().optional().describe('Object ID of the user to add/remove as owner'),
    filter: z.string().optional().describe('OData filter string'),
  });

• src/tool-metadata.ts:84-88 (schema)

  Tool metadata providing description, title, and MCP annotations (readOnlyHint, destructiveHint, etc.) for 'manage_service_principals'.

  manage_service_principals: {
    description: "Manage service principals for application access including permissions, credentials, and enterprise applications.",
    title: "Service Principal Manager",
    annotations: { title: "Service Principal Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }
  },