Microsoft 365 Core MCP Server

Instructions

Implementation Reference

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

  The core handler function implementing manage_service_principals tool logic. Handles actions: list_sps (GET /servicePrincipals), get_sp (GET /servicePrincipals/{id}), add_owner (POST /servicePrincipals/{id}/owners/$ref), remove_owner (DELETE /servicePrincipals/{id}/owners/{ownerId}/$ref). Uses Microsoft Graph Client for API calls.
  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)

  MCP server registration of the 'manage_service_principals' tool, linking to handleServicePrincipals handler with azureAdSpSchema input validation and error handling.
  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 input parameters for manage_service_principals: action (enum: list_sps|get_sp|add_owner|remove_owner), spId (optional string), ownerId (optional string), filter (optional OData filter). Used for tool input validation.
  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/types.ts:155-160 (helper)

  TypeScript interface AzureAdSpArgs defining the typed arguments for the service principals handler, matching the Zod schema for type safety.
  export interface AzureAdSpArgs { action: 'list_sps' | 'get_sp' | 'add_owner' | 'remove_owner'; spId?: string; ownerId?: string; filter?: string; }
• src/tool-metadata.ts:84-87 (helper)

  Tool metadata providing description, title 'Service Principal Manager', and annotations (readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true) for client-side tool discovery and UI hints.
  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 }