Skip to main content
Authorization determines what authenticated users can access. While authentication verifies who a user is, authorization controls what they can do.

​
Authorization Layers

MCP Gateway provides authorization at multiple levels:
LevelWhat it controlsStatus
WorkspaceWhich teams can access which MCP serversAvailable
MCP ServerAccess to specific servers based on claimsAvailable
ToolAccess to specific tools within a serverComing soon

​
Server-Level Claim-Based Authorization

Control access to MCP servers based on JWT claims. This is configured through JWT Validation using requiredClaims and claimValues.

​
Require Specific Claims

Ensure tokens include specific claims before allowing access: 
{
  "jwt_validation": {
    "jwksUri": "https://your-idp.com/.well-known/jwks.json",
    "requiredClaims": ["sub", "email", "groups"]
  }
}
If a token is missing any required claim, access is denied.

​
Validate Claim Values

Authorize based on claim values—group membership, roles, or other attributes: 
{
  "jwt_validation": {
    "jwksUri": "https://your-idp.com/.well-known/jwks.json",
    "claimValues": {
      "groups": {
        "values": ["engineering", "platform"],
        "matchType": "contains"
      },
      "iss": {
        "values": "https://your-idp.com",
        "matchType": "exact"
      }
    }
  }
}
Users whose tokens don’t match the required claim values receive an authorization error.

​
Match Types

TypeDescriptionExample
exactClaim value must match exactlyiss must equal "https://your-idp.com"
containsClaim must include at least one value (OR)User must be in engineering OR platform group
containsAllClaim must include all values (AND)User must have both mcp:read AND mcp:write scopes
regexMatch against a regular expressionEmail must match @yourcompany\.com$

​
Example: Restrict to Engineering Team

Only allow users in the engineering group: 
{
  "jwt_validation": {
    "jwksUri": "https://your-idp.com/.well-known/jwks.json",
    "requiredClaims": ["sub", "groups"],
    "claimValues": {
      "groups": {
        "values": ["engineering"],
        "matchType": "contains"
      }
    }
  }
}

​
Example: Require Admin Role

Only allow users with admin role: 
{
  "jwt_validation": {
    "jwksUri": "https://your-idp.com/.well-known/jwks.json",
    "claimValues": {
      "role": {
        "values": "admin",
        "matchType": "exact"
      }
    }
  }
}

​
Example: Restrict by Email Domain

Only allow users from your company domain: 
{
  "jwt_validation": {
    "jwksUri": "https://your-idp.com/.well-known/jwks.json",
    "claimValues": {
      "email": {
        "values": "@yourcompany\\.com$",
        "matchType": "regex"
      }
    }
  }
}
See JWT Validation for complete configuration options.

​
Tool-Level Authorization

Tool-level claim-based authorization is coming in a future release.
Fine-grained authorization at the tool level based on JWT claims. Control tool access by user attributes: 
{
  "tool_authorization": {
    "delete_issue": {
      "required_claims": {
        "role": {
          "values": ["admin", "maintainer"],
          "matchType": "contains"
        }
      }
    }
  }
}
Enables scenarios like:
  • Allow read tools for all users, write tools for specific roles
  • Restrict dangerous operations to admins
  • Enable different tool sets for different teams

​
Webhooks for Authorization

Webhook-based authorization is coming in a future release.
Call your custom authorization service before each MCP request. Implement dynamic, context-aware access decisions. 
{
  "authorization_webhook": {
    "url": "https://your-service.com/authorize",
    "timeout_ms": 1000,
    "on_error": "deny"
  }
}
Your webhook will receive:
  • User identity and claims
  • Target MCP server
  • Tool being called
  • Request parameters
Return allow or deny with an optional reason. Enables:
  • Dynamic authorization based on external systems
  • Context-aware decisions (time of day, request patterns)
  • Integration with existing authorization infrastructure
  • Custom business logic for access control

​
Combining with Team Provisioning

Authorization works alongside Team Provisioning:
  1. Team Provisioning controls which workspaces see which servers
  2. JWT Validation adds claim-based rules on top
A user must pass both checks to access an MCP server. 
User Request
    │
    ▼
┌─────────────────────────────┐
│   Team Provisioning Check   │  Is server provisioned to user's workspace?
└─────────────────────────────┘
    │ ✓
    ▼
┌─────────────────────────────┐
│   JWT Claim Validation      │  Does token have required claims/values?
└─────────────────────────────┘
    │ ✓
    ▼
   Access Granted

​
Next Steps

JWT Validation

Configure claim validation for authorization.

Team Provisioning

Control workspace access to MCP servers.

Identity Forwarding

Pass user identity to MCP servers for downstream authorization.

Tool Provisioning

Enable or disable specific tools.
Last modified on January 28, 2026