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 } },