Authorize Tools in a Virtual Server Using RBAC¶

This guide walks through configuring RBAC so that specific users can list and execute tools exposed through a virtual server, while others are restricted to read-only access or blocked entirely. The scenario used throughout is an analytics team with data-query tools — such as run-query and db-migrate — on a production virtual server. Developers on the team need to both list and execute tools. Viewers should be able to browse available tools but not execute them. A sensitive db-migrate tool should be restricted by controlling who holds the tools.execute permission.

Prerequisites¶

How the Two-Layer Model Applies to Tools¶

ContextForge enforces a two-layer security model on every tool operation. Layer 1 — token scoping — uses the teams claim in the caller's JWT to determine which tools the user can see, based on each tool's visibility setting and team_id. Layer 2 — RBAC — checks the user's role permissions (tools.read, tools.execute) to determine which actions are allowed on the tools that passed Layer 1. Both layers must pass for a tool call to succeed; a user who can see a tool but lacks the tools.execute permission will receive a 403 Forbidden response. Conversely, a user with the correct role but a token scoped to the wrong team will not see the tool at all.

Request --> Token Scoping (Can see this tool?) --> RBAC Check (Can execute?) --> Tool runs

In the analytics scenario, this means a developer's JWT must contain the analytics team UUID in its teams claim (Layer 1) and the developer must hold a role that includes tools.execute (Layer 2). A viewer on the same team passes Layer 1 but is stopped at Layer 2 when attempting execution.

For the full reference on roles, permissions, and token scoping semantics, see RBAC Configuration.

Step 1: Set Tool Visibility¶

Tools inherit their visibility from how they are registered, defaulting to private. A private tool is visible only to its owner and platform administrators with bypass tokens. For team members to see a tool, set its visibility to team — this restricts discovery to users whose JWT contains the matching team UUID. To make a tool visible to all authenticated users regardless of team membership, set visibility to public.

For the analytics scenario, set the data-query tools to team visibility so that only analytics team members can discover them.

curl -X PUT "$GATEWAY_URL/tools/$TOOL_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"visibility": "team"}'

Step 2: Assign an RBAC Role¶

The three built-in roles most relevant to tool access are:

Assign the developer role to users who need to execute tools, and the viewer role to users who should only browse. Roles are scoped to a specific team, so the same user can hold different roles on different teams — for example, developer on the analytics team but viewer on the infrastructure team.

curl -X POST "$GATEWAY_URL/rbac/users/analyst@example.com/roles" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role_id": "developer", "scope": "team", "scope_id": "<analytics-team-uuid>"}'

Step 3: Generate a Scoped Token¶

API tokens must include the team in the teams JWT claim so that Layer 1 (token scoping) grants visibility to team-scoped resources. Without the correct team UUID in the token, the user will only see public tools — regardless of their RBAC role. Session tokens created through the Admin UI login flow resolve team memberships automatically from the database, so this step applies primarily to programmatic API access and CI/CD integrations.

python3 -m mcpgateway.utils.create_jwt_token \
  --data '{"sub":"analyst@example.com","is_admin":false,"teams":["<analytics-team-uuid>"],"token_use":"api"}' \
  --exp 60 \
  --secret "$JWT_SECRET_KEY"

export TOKEN="<output-from-above>"

Step 4: Verify Access¶

Run the following checks to confirm that the two-layer model is enforcing access as expected. These four scenarios cover the primary access patterns: successful listing, successful execution, permission denial, and team isolation.

Developer lists tools¶

A developer's token scoped to the analytics team should return team-scoped tools:

curl -s "$GATEWAY_URL/tools" \
  -H "Authorization: Bearer $DEVELOPER_TOKEN" | jq '.[].name'

Expected result: the response includes the analytics team's tools such as run-query.

Developer executes a tool¶

The developer should be able to invoke a tool successfully. Tool invocation uses JSON-RPC 2.0 via the /rpc endpoint:

curl -X POST "$GATEWAY_URL/rpc" \
  -H "Authorization: Bearer $DEVELOPER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "run-query", "arguments": {"sql": "SELECT count(*) FROM events"}}}'

Expected result: a JSON-RPC response with the tool's output in the result field.

Viewer attempts execution¶

A viewer has tools.read but not tools.execute, so the same call should be rejected:

curl -X POST "$GATEWAY_URL/rpc" \
  -H "Authorization: Bearer $VIEWER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "run-query", "arguments": {"sql": "SELECT count(*) FROM events"}}}'
# Expected: JSON-RPC error with code -32603 (403 Forbidden)

Expected result: a JSON-RPC error response. The viewer can list tools but cannot invoke them.

User from another team¶

A token scoped to a different team should not see team-scoped analytics tools at all:

curl -s "$GATEWAY_URL/tools" \
  -H "Authorization: Bearer $OTHER_TEAM_TOKEN" | jq '.[].name'

Expected result: the analytics team's tools are absent from the response. Only tools with public visibility appear. This confirms that Layer 1 (token scoping) is filtering correctly based on the teams claim.

echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq .

Troubleshooting¶

For more details, see Troubleshooting in the RBAC reference.

Related Documentation¶

• RBAC Configuration — Full reference for roles, permissions, and token scoping
• Team Management — Creating teams and SSO group mapping
• Security Configuration — Authentication setup and token lifecycle
• Multi-Tenancy Architecture — Visibility model and resource scoping