create_dataverse_role
Create custom security roles in Dataverse to define user permissions and access levels, controlling what users can see and do within the system for different job functions.
Instructions
Creates a new security role in Dataverse to define permissions and access levels for users and teams. Security roles control what users can see and do within the system. Use this to establish custom permission sets for different user types or job functions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| appliesTo | No | Personas/Licenses the security role applies to | |
| businessUnitId | No | Business unit ID to associate the role with (defaults to root business unit) | |
| description | No | Description of the security role | |
| isAutoAssigned | No | Whether the role is auto-assigned based on user license | |
| isInherited | No | 0 = Team privileges only, 1 = Direct User access level and Team privileges | 1 |
| name | Yes | Name of the security role | |
| summaryOfCoreTablePermissions | No | Summary of Core Table Permissions of the Role |
Implementation Reference
- src/tools/role-tools.ts:41-89 (handler)The asynchronous handler function that implements the core logic for the 'create_dataverse_role' tool. It constructs role data, handles business unit association (defaulting to root if not provided), posts to the 'roles' endpoint via DataverseClient, extracts the role ID from response, and returns formatted success or error content.async (params) => { try { const roleData: any = { name: params.name, description: params.description || '', appliesto: params.appliesTo, isautoassigned: params.isAutoAssigned ? 1 : 0, isinherited: parseInt(params.isInherited), summaryofcoretablepermissions: params.summaryOfCoreTablePermissions }; // If businessUnitId is provided, use it; otherwise, get the root business unit if (params.businessUnitId) { roleData['businessunitid@odata.bind'] = `/businessunits(${params.businessUnitId})`; } else { // Get the root business unit const businessUnits = await client.get('businessunits?$filter=parentbusinessunitid eq null&$select=businessunitid'); if (businessUnits.value && businessUnits.value.length > 0) { roleData['businessunitid@odata.bind'] = `/businessunits(${businessUnits.value[0].businessunitid})`; } } const response = await client.post('roles', roleData); // The response might have the ID in different formats const roleId = response.roleid || response.id || response['@odata.id']?.split('(')[1]?.split(')')[0] || 'Created successfully'; return { content: [ { type: "text", text: `Successfully created security role '${params.name}'.\n\nRole ID: ${roleId}\n\nResponse: ${JSON.stringify(response, null, 2)}` } ] }; } catch (error) { return { content: [ { type: "text", text: `Error creating security role: ${error instanceof Error ? error.message : 'Unknown error'}` } ], isError: true }; } } );
- src/tools/role-tools.ts:28-40 (schema)The tool metadata including title, description, and Zod inputSchema defining parameters: name (required), description, businessUnitId, appliesTo, isAutoAssigned, isInherited, summaryOfCoreTablePermissions.{ title: "Create Dataverse Security Role", description: "Creates a new security role in Dataverse to define permissions and access levels for users and teams. Security roles control what users can see and do within the system. Use this to establish custom permission sets for different user types or job functions.", inputSchema: { name: z.string().max(100).describe("Name of the security role"), description: z.string().max(2000).optional().describe("Description of the security role"), businessUnitId: z.string().optional().describe("Business unit ID to associate the role with (defaults to root business unit)"), appliesTo: z.string().max(2000).optional().describe("Personas/Licenses the security role applies to"), isAutoAssigned: z.boolean().default(false).describe("Whether the role is auto-assigned based on user license"), isInherited: z.enum(['0', '1']).default('1').describe("0 = Team privileges only, 1 = Direct User access level and Team privileges"), summaryOfCoreTablePermissions: z.string().max(2000).optional().describe("Summary of Core Table Permissions of the Role") } },
- src/tools/role-tools.ts:25-90 (registration)The createRoleTool function that registers the 'create_dataverse_role' tool with the MCP server, including schema and handler.export function createRoleTool(server: McpServer, client: DataverseClient) { server.registerTool( "create_dataverse_role", { title: "Create Dataverse Security Role", description: "Creates a new security role in Dataverse to define permissions and access levels for users and teams. Security roles control what users can see and do within the system. Use this to establish custom permission sets for different user types or job functions.", inputSchema: { name: z.string().max(100).describe("Name of the security role"), description: z.string().max(2000).optional().describe("Description of the security role"), businessUnitId: z.string().optional().describe("Business unit ID to associate the role with (defaults to root business unit)"), appliesTo: z.string().max(2000).optional().describe("Personas/Licenses the security role applies to"), isAutoAssigned: z.boolean().default(false).describe("Whether the role is auto-assigned based on user license"), isInherited: z.enum(['0', '1']).default('1').describe("0 = Team privileges only, 1 = Direct User access level and Team privileges"), summaryOfCoreTablePermissions: z.string().max(2000).optional().describe("Summary of Core Table Permissions of the Role") } }, async (params) => { try { const roleData: any = { name: params.name, description: params.description || '', appliesto: params.appliesTo, isautoassigned: params.isAutoAssigned ? 1 : 0, isinherited: parseInt(params.isInherited), summaryofcoretablepermissions: params.summaryOfCoreTablePermissions }; // If businessUnitId is provided, use it; otherwise, get the root business unit if (params.businessUnitId) { roleData['businessunitid@odata.bind'] = `/businessunits(${params.businessUnitId})`; } else { // Get the root business unit const businessUnits = await client.get('businessunits?$filter=parentbusinessunitid eq null&$select=businessunitid'); if (businessUnits.value && businessUnits.value.length > 0) { roleData['businessunitid@odata.bind'] = `/businessunits(${businessUnits.value[0].businessunitid})`; } } const response = await client.post('roles', roleData); // The response might have the ID in different formats const roleId = response.roleid || response.id || response['@odata.id']?.split('(')[1]?.split(')')[0] || 'Created successfully'; return { content: [ { type: "text", text: `Successfully created security role '${params.name}'.\n\nRole ID: ${roleId}\n\nResponse: ${JSON.stringify(response, null, 2)}` } ] }; } catch (error) { return { content: [ { type: "text", text: `Error creating security role: ${error instanceof Error ? error.message : 'Unknown error'}` } ], isError: true }; } } ); }
- src/index.ts:180-180 (registration)The call to createRoleTool in the main index.ts that performs the actual registration of the tool during server initialization.createRoleTool(server, dataverseClient);