Set Up Capability RBAC

Configure capability RBAC to control access to individual tools, prompts, and resources within an MCP server.

Prerequisites

Control Plane
YAML

Golf Control Plane account with Admin role
Server RBAC configured (Set Up Server RBAC)
Groups synced from your identity provider

How it works

Capability RBAC extends server RBAC to control access to individual:

Tools - Functions the AI can call
Prompts - Prompt templates
Resources - Data sources

4-layer policy merge

Capability RBAC uses a 4-layer policy merge to determine access:

Layer	Where Configured	Purpose
1. Organization	Control Plane > Settings > Policies	Base annotation defaults
2. Gateway	Control Plane > Gateway > Policies	Override org defaults
3. Annotation	From MCP server tool metadata	Selects which policy category applies
4. Capability	Per-server capability overrides	Most specific per-tool rules

Each layer can only make access more restrictive, never less. The final access decision is the intersection of all layers.

Tool annotations

MCP servers provide annotations that describe each tool’s behavior. Golf Gateway uses these to apply the appropriate access policy automatically:

Annotation	Meaning	Default Policy
`readOnlyHint: true`	Tool only reads data, no side effects	More permissive
`destructiveHint: true`	Tool may delete or overwrite data	More restrictive
Neither	Tool behavior is unspecified	Configurable default

Example: How annotations affect access

With these organization defaults:

read_only.allowed_groups = ["all-users"]
destructive.allowed_groups = ["admins"]
unspecified.allowed_groups = ["developers", "admins"]

When a user invokes a tool:

list_files (readOnlyHint: true) → Allowed for all users
delete_file (destructiveHint: true) → Requires admin group
send_message (no annotations) → Requires developers or admins

Enable capability RBAC

Control Plane
YAML

Go to MCP Servers > select a server
Navigate to the Policies tab > Permissions section
Click Enabled to turn on capability RBAC
Go to the Capabilities tab to view discovered tools, prompts, and resources
Use Review Changes to review and approve pending capabilities

servers:
  - name: github-mcp
    url: http://localhost:3001
    rbac_enabled: true
    allowed_groups: [developers]
    capability_rbac_enabled: true  # Enable per-capability RBAC

Configure annotation-based defaults

Set default access groups for each annotation category. These defaults apply to all capabilities that match the annotation.

Control Plane
YAML

Organization-level defaults:

Go to Settings > Policies
Find the Capability RBAC section
Configure default groups for each category:
- Read-only tools - Tools with readOnlyHint: true
- Destructive tools - Tools with destructiveHint: true
- Unspecified tools - Tools without annotations
Click Save

Gateway-level overrides:

Go to Gateways > select a gateway > Policies
Find the Capability RBAC section
Override organization defaults as needed (can only be more restrictive)
Click Save

Configure at the gateway level in gateway_policy:

gateway_policy:
  capability_rbac:
    read_only:
      default_groups: [all-users]        # Permissive for read-only
    destructive:
      default_groups: [admins]           # Restrictive for destructive
    unspecified:
      default_groups: [developers, admins]

Organization-level annotation defaults are configured in the Control Plane UI, even when using Distributed mode. The gateway_policy in YAML provides gateway-level overrides.

Configure per-capability overrides

For specific tools that need different access than their annotation category, configure per-capability overrides:

Control Plane
YAML

Go to MCP Servers > select a server > Capabilities tab
Find the capability you want to restrict
Click the capability row to expand details
Click Edit Permissions
Enable Custom Access to override annotation defaults
Select allowed groups for this specific capability
Click Save

Use capability_overrides on the server to set per-capability rules:

servers:
  - name: github-mcp
    url: http://localhost:3001
    capability_rbac_enabled: true
    capability_overrides:
      # Restrict delete operations to repo admins only
      - capability: "tools/delete_repo"
        rbac_enabled: true
        rbac_mode: allow
        allowed_groups: [repo-admins]

      # Allow all users to list repositories
      - capability: "tools/list_repos"
        rbac_enabled: true
        allowed_groups: [all-users]

      # Use wildcards for patterns
      - capability: "tools/delete_*"
        allowed_groups: [admins]

Capability patterns:

tools/exact_name - Match specific tool
tools/prefix_* - Match tools starting with prefix
resources/* - Match all resources
prompts/category/* - Match prompts in category

Pending approval workflow

When capability versioning is enabled, new or modified capabilities require admin approval before becoming active:

Control Plane
YAML

Gateway discovers new tool/prompt/resource during connection
Capability appears in the Capabilities tab with New or Changed badge
Click Review Changes to see all pending capabilities
Review the capability schema and intended behavior
Click Approve All or approve individual changes
Users can now access the approved capabilities

To disable pending approval and auto-approve new capabilities:

servers:
  - name: github-mcp
    capability_versioning_enabled: false  # Auto-approve new capabilities

Disabling capability versioning means new tools are immediately available to users. Only disable this for trusted internal MCP servers.

Complete example

Here’s a complete configuration showing all capability RBAC features:

# Gateway-level annotation defaults
gateway_policy:
  capability_rbac:
    read_only:
      default_groups: [all-users]
    destructive:
      default_groups: [senior-developers, admins]
    unspecified:
      default_groups: [developers, admins]

servers:
  - name: github-mcp
    url: http://localhost:3001
    rbac_enabled: true
    allowed_groups: [engineering]
    idp: auth0

    # Enable capability RBAC
    capability_rbac_enabled: true

    # Per-capability overrides
    capability_overrides:
      # Only repo admins can delete repositories
      - capability: "tools/delete_repo"
        allowed_groups: [repo-admins]

      # Only security team can manage secrets
      - capability: "tools/*_secret"
        allowed_groups: [security-team]

    # Require approval for new capabilities
    capability_versioning_enabled: true

Verify capability RBAC

Connect your MCP client (Claude Desktop, Cursor, etc.) to the gateway as an authorized user
Ask the AI to list available tools - verify restricted tools are filtered from the response
Try to use a restricted tool (e.g., delete_repo) - verify you receive an access denied error
Check audit log in Admin Portal > Audit Logs for the blocked request

Troubleshooting

Tool not appearing: Check if capability versioning is enabled and the tool is pending approval
Access denied with correct groups: Verify all layers (org, gateway, capability override) - access is the intersection of all
Wildcard not matching: Patterns use prefix matching with *, ensure your pattern is correct

Set Up Server RBAC - Server-level access control
Golf Gateway Overview - Policy engine architecture

Overview

Guides

Reference

Support

Prerequisites

How it works

4-layer policy merge

Tool annotations

Enable capability RBAC

Configure annotation-based defaults

Configure per-capability overrides

Pending approval workflow

Complete example

Verify capability RBAC

Troubleshooting

​Prerequisites

​How it works

​4-layer policy merge

​Tool annotations

​Enable capability RBAC

​Configure annotation-based defaults

​Configure per-capability overrides

​Pending approval workflow

​Complete example

​Verify capability RBAC

​Troubleshooting

​Related guides

Prerequisites

How it works

4-layer policy merge

Tool annotations

Enable capability RBAC

Configure annotation-based defaults

Configure per-capability overrides

Pending approval workflow

Complete example

Verify capability RBAC

Troubleshooting

Related guides