get_role_privileges

Retrieve all privileges assigned to a security role to audit permissions and understand what access the role provides to users and teams in Microsoft Dataverse.

Instructions

Retrieves all privileges currently assigned to a security role, showing what permissions the role grants. Use this to audit role permissions and understand what access a role provides to users and teams.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`roleId`	Yes	ID of the role to retrieve privileges for

Implementation Reference

src/tools/role-tools.ts:466-497 (handler)

The core handler function that executes the tool logic: fetches privileges for a given role ID using Dataverse Web API $expand on roleprivileges_association, maps to privilegeId and name, and returns formatted response.

async (params) => {
  try {
    // Get role privileges using the correct Web API approach from Microsoft documentation
    // Using $expand to get the roleprivileges_association collection
    const response = await client.get(`roles(${params.roleId})?$select=roleid&$expand=roleprivileges_association($select=name,privilegeid)&$orderby=name`);

    const rolePrivileges = response.roleprivileges_association || [];
    const privileges = rolePrivileges.map((privilege: any) => ({
      privilegeId: privilege.privilegeid,
      privilegeName: privilege.name
    }));

    return {
      content: [
        {
          type: "text",
          text: `Role privileges (${privileges.length} found):\n\n${JSON.stringify(privileges, null, 2)}`
        }
      ]
    };
  } catch (error) {
    return {
      content: [
        {
          type: "text",
          text: `Error retrieving role privileges: ${error instanceof Error ? error.message : 'Unknown error'}`
        }
      ],
      isError: true
    };
  }
}

src/tools/role-tools.ts:462-464 (schema)
Zod input schema validating the required 'roleId' parameter as a string.
```
inputSchema: {
  roleId: z.string().describe("ID of the role to retrieve privileges for")
}
```

src/tools/role-tools.ts:457-498 (registration)

MCP server tool registration call within getRolePrivilegesTool export function, specifying name, metadata, schema, and handler.

server.registerTool(
  "get_role_privileges",
  {
    title: "Get Dataverse Role Privileges",
    description: "Retrieves all privileges currently assigned to a security role, showing what permissions the role grants. Use this to audit role permissions and understand what access a role provides to users and teams.",
    inputSchema: {
      roleId: z.string().describe("ID of the role to retrieve privileges for")
    }
  },
  async (params) => {
    try {
      // Get role privileges using the correct Web API approach from Microsoft documentation
      // Using $expand to get the roleprivileges_association collection
      const response = await client.get(`roles(${params.roleId})?$select=roleid&$expand=roleprivileges_association($select=name,privilegeid)&$orderby=name`);

      const rolePrivileges = response.roleprivileges_association || [];
      const privileges = rolePrivileges.map((privilege: any) => ({
        privilegeId: privilege.privilegeid,
        privilegeName: privilege.name
      }));

      return {
        content: [
          {
            type: "text",
            text: `Role privileges (${privileges.length} found):\n\n${JSON.stringify(privileges, null, 2)}`
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error retrieving role privileges: ${error instanceof Error ? error.message : 'Unknown error'}`
          }
        ],
        isError: true
      };
    }
  }
);

src/index.ts:190-190 (registration)
Invocation in main index file that calls getRolePrivilegesTool to register the tool with the MCP server instance and Dataverse client.
```
getRolePrivilegesTool(server, dataverseClient);
```

Dataverse MCP Server