Authorization

Control what users can access at the MCP server and tool level.

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:

Level	What it controls	Status
Workspace	Which teams can access which MCP servers	Available
MCP Server	Access to specific servers based on claims	Available
Tool	Access to specific tools within a server	Coming 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

Type	Description	Example
exact	Claim value must match exactly	iss must equal "https://your-idp.com"
contains	Claim must include at least one value (OR)	User must be in engineering OR platform group
containsAll	Claim must include all values (AND)	User must have both mcp:read AND mcp:write scopes
regex	Match against a regular expression	Email 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.