mcp-gateway

Azure Entra ID Application Roles Setup

Follow these steps to enable application roles, assign them to identities, and pass the role value into adapter/tool definitions for authorization.

1. Enable and Configure Roles on the App Registration

• Open the Azure portal and navigate to Entra ID > App registrations; select the app the gateway trusts (e.g., McpGateway).
• Go to App roles and choose Create app role.
  • Display name: Friendly label shown in the portal (e.g., Adapter Reader).
  • Allowed member type: Users/Groups for people or Applications for service principals.
  • Value: Immutable string used by Mcp Gateway authorization (e.g., mcp.engineer).
  • Provide a meaningful description so administrators know when to grant it.
  • Save the role. Repeat for each logical permission your org needs; you can create any value pattern (e.g., mcp.engineer, mcp.scientist).
• Always create the admin role with the value mcp.admin. This value is used by the gateway to grant elevated write access beyond the resource creator.
• Make sure App roles shows the new entries in the table; this automatically updates the app manifest.

2. Assign Roles to Identities

• In the same app registration, open Enterprise applications (service principal) entry.
• Navigate to Users and groups > Add user/group.
  • Select a user, group, or service principal.
  • Choose the desired application role value.
  • Confirm the assignment.
• Users receive the role via their next sign-in; apps inherit the claims immediately once the service principal is updated.

3. Provide the Role Value When Creating Adapters or Tools

• When calling the management APIs (or CLI) to create adapters/tools, populate the requiredRoles collection with the exact Value strings created above.
• Example payload fragment:

  {
    "name": "sample-adapter",
    // ...
    "requiredRoles": ["mcp.engineer", "mcp.scientist"]
  }
  

• The gateway’s SimplePermissionProvider grants:
  • Read access if the caller is the creator, holds mcp.admin, or matches one of the requiredRoles entries.
  • Write access if the caller is the creator or holds mcp.admin.

  If no requiredRoles is configured, it by default ALLOW ALL READ access.

4. Built-in Agent Tools Are Disabled (bash, read_file, write_file)

Built-in tools are disabled for every caller, including mcp.admin, agent creators, and callers with previously configured built-in roles such as mcp.builtin.

• Agent create/update requests containing builtin: references return 400 Bad Request.
• Built-ins in existing agent definitions are omitted from tool discovery, and previously resolved calls are rejected without execution.
• BuiltinToolSettings:RequiredRoles is retained for configuration compatibility only; neither it nor additional role assignments can enable built-in execution.

Remove built-in references when updating agents. Authorization for registered MCP tools, subagents, adapters, and workload identity is unchanged.

5. Authorize Workload Identity on Adapters and Tools (useWorkloadIdentity)

Setting useWorkloadIdentity: true binds the deployed pod to the cluster’s shared federated identity (the workload-sa service account annotated with azure.workload.identity/client-id). Any container in that pod can then mint Entra ID access tokens for that identity and reach whatever Azure resources it is granted. Because the identity is shared by every workload in the namespace and is not owned by the requester, this is gated on the caller’s role at create and update time, with no creator bypass.

• Default (fail-closed): only callers holding mcp.admin may set useWorkloadIdentity: true. Other callers receive 403 Forbidden; adapters and tools that do not request workload identity are unaffected.

• To grant this without full admin, create a dedicated app role (e.g. mcp.workload), assign it (Section 2), then configure it on the gateway:

  // appsettings.json
  {
    "WorkloadIdentitySettings": {
      "RequiredRoles": [ "mcp.workload" ]
    }
  }
  

  The same setting via environment variables (e.g. in the pod spec) uses the array index form:

  WorkloadIdentitySettings__RequiredRoles__0=mcp.workload
  

  mcp.admin is always permitted in addition to any configured roles. Leaving RequiredRoles empty keeps workload identity admin-only.

This site is open source. Improve this page.