--- title: Fine-Grain Authorization | Keycard description: Write Policies that permit or deny individual MCP tool calls through a Unified Access Gateway --- Fine-grain authorization lets you govern a [Unified Access Gateway](/admin/unified-access-gateway/index.md) at the level of individual MCP tool calls. On every tool call the gateway forwards, Keycard evaluates your Zone’s active [Access Policies](/admin/access-policies/index.md) to verify that the specific action is allowed, and you can configure different permissions for different sets of users. For example, permit read-only tools to everyone while restricting write or delete tools to a smaller cohort. ## How it works The gateway checks the MCP method and tool name against your Policies before forwarding the request to the upstream MCP server. A denial blocks the call before it ever reaches the upstream, and every decision is recorded in the audit log. MCP activity maps onto Cedar actions as follows: | MCP activity | Cedar action | | -------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | Tool call (`tools/call`) | `Keycard::Action::"mcp::tools/call::"` | | Prompt (`prompts/get`) | `Keycard::Action::"mcp::prompts/get::"` | | Resource (`resources/read`) | `Keycard::Action::"mcp::resources/read::"` | | Discovery (`tools/list`, `prompts/list`, `resources/list`, `resources/templates/list`) | Actions in the `Keycard::ActionGroup::"MCPProtocol"` group | ## Prerequisites - A Unified Access Gateway with upstream MCP servers attached (see [Unified Access Gateway](/admin/unified-access-gateway/index.md)) - **Manager** access to the Zone (see [Roles & Permissions](/admin/roles-and-permissions/index.md)) - Familiarity with authoring and activating Policies (see [Access Policies](/admin/access-policies/index.md)) ## Create fine-grain Policies 1. **Identify the tools to gate** Reference each upstream MCP server’s documentation for the tool names it exposes. To construct the Cedar action for a tool, prepend `mcp::tools/call::` to the tool name exactly as the upstream publishes it. For example, a tool named `create_event` becomes: ``` Keycard::Action::"mcp::tools/call::create_event" ``` Use the bare tool name from the upstream, not the `__` prefixed name shown in the gateway’s aggregated tool list, which is presentation only. Prompts and MCP resources follow the same pattern with the `mcp::prompts/get::` and `mcp::resources/read::` prefixes, as shown in the mapping table above. Note Tool discovery and management in the Console is coming soon: you will be able to browse the tools each upstream exposes and review tool call activity directly in Keycard. 2. **Permit sign-in and discovery** Users need to sign in to the gateway and list its tools before any tool is called. Permit the gateway endpoint itself, and the `MCPProtocol` action group on each upstream. The group contains the discovery actions (`mcp::tools/list`, `mcp::prompts/list`, `mcp::resources/list`, and `mcp::resources/templates/list`). Establishing an MCP session (`initialize`) is handled by the gateway itself and is not gated by Policies. To find the identifiers, open the gateway’s Application details page in Keycard Console (**Applications -> your gateway**): the gateway’s own identifier is the **MCP Access URL** on the **Application settings** page, and the upstream identifiers are the MCP URLs of the Resources listed under **Dependencies**. ``` @id("gateway-signin") @description("Allow users to sign in to and authorize the gateway") permit ( principal is Keycard::User, action, resource ) when { resource.identifier == "https://..mcp.gateway.context/mcp" }; @id("gateway-mcp-protocol") @description("Tool, prompt, and resource discovery on the upstreams") permit ( principal is Keycard::User, action in Keycard::ActionGroup::"MCPProtocol", resource ) when { ["https:///mcp", "https:///mcp"].contains(resource.identifier) }; ``` Caution Without the sign-in permission users cannot authorize the gateway at all. Without the `MCPProtocol` permission an upstream’s tools cannot be listed, so that upstream is excluded from the user’s aggregated tool list. Discovery never invokes a tool, so permitting `MCPProtocol` does not grant tool access by itself. Note The ability to reduce the number of tools presented to the client is coming soon: the aggregated tool list will only include the tools each user is permitted to call. 3. **Permit the baseline tools for all users** Enumerate the read-only tools every authenticated user may call. For example, on a calendar upstream: ``` @id("calendar-events-read") @description("Read-only event tools for all users") permit ( principal is Keycard::User, action in [Keycard::Action::"mcp::tools/call::list_events", Keycard::Action::"mcp::tools/call::get_event", Keycard::Action::"mcp::tools/call::search_events"], resource ) when { resource.identifier == "https:///mcp" }; ``` Tool calls that no Policy permits are denied: fine-grain authorization is default-deny, like every other Keycard enforcement point. 4. **Restrict sensitive tools to identity provider groups** Gate mutating and destructive tools on the `groups` claim your identity provider issues, using `context.subject_claims`: ``` @id("calendar-events-write") @description("Event mutations granted to Calendar Writers") permit ( principal is Keycard::User, action in [Keycard::Action::"mcp::tools/call::create_event", Keycard::Action::"mcp::tools/call::update_event"], resource ) when { resource.identifier == "https:///mcp" && context has subject_claims && context.subject_claims has groups && context.subject_claims.groups.contains("Calendar Writers") }; @id("calendar-events-delete") @description("Event deletion granted to Calendar Admins") permit ( principal is Keycard::User, action == Keycard::Action::"mcp::tools/call::delete_event", resource ) when { resource.identifier == "https:///mcp" && context has subject_claims && context.subject_claims has groups && context.subject_claims.groups.contains("Calendar Admins") }; ``` 5. **Cover prompts and resources (optional)** Upstream MCP prompts and resources are governed the same way, under the `mcp::prompts/get::` and `mcp::resources/read::` action prefixes: ``` @id("prompts-code-review") @description("The code_review prompt template for Engineering") permit ( principal is Keycard::User, action == Keycard::Action::"mcp::prompts/get::code_review", resource ) when { resource.identifier == "https:///mcp" && context has subject_claims && context.subject_claims has groups && context.subject_claims.groups.contains("Engineering") }; ``` 6. **Activate the Policies** Activate the Policies in your Zone through your usual workflow on the **Console -> Policies** page. Changes take effect on the next tool call. There is nothing to deploy or restart on the gateway. ## Verify Sign in to the gateway as a user in one of the permitted groups and call a permitted tool; it succeeds as before. Then call a tool your Policies do not permit. The call is denied before reaching the upstream, and the client receives a policy error instead of a tool result. Check **Console -> Audit Log** for both decisions. Every evaluation is logged with the user, the upstream, the tool name, and the Policy outcome, so denied calls carry the context of what was denied and why. ## Troubleshooting - **A tool call is denied that a Policy should allow.** Confirm the action uses the bare tool name (`mcp::tools/call::create_event`), not the prefixed name from the aggregated tool list (`calendar__create_event`), and that `resource.identifier` matches the upstream MCP server URL exactly. - **A group-gated Policy never matches.** Verify your identity provider issues the `groups` claim and that the user is a member. The Policy’s `context has subject_claims` guards only prevent evaluation errors; a missing claim means the Policy silently does not match. - **A user sees no tools from an upstream at all.** Tool listing is gated by the `MCPProtocol` action group. Check the user is permitted that group on the upstream, then have them reconnect.