Fine-Grained Authorization
Write Policies that permit or deny individual MCP tool calls through a Unified Access Gateway
Fine-grained authorization lets you govern a Unified Access Gateway at the level of individual MCP tool calls. On every tool call the gateway forwards, Keycard evaluates your Zone’s active Access Policies 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. For the case this solves, and what a reviewer asks about it, see Allow one tool, deny the next.
How it works
Section titled “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 under Policies → Activity.
Gateway activity maps onto Cedar actions as follows:
| MCP activity | Cedar action |
|---|---|
Tool call (tools/call) |
Keycard::Action::"mcp::tools/call::<tool-name>" |
Tool discovery (tools/list) |
Keycard::Action::"mcp::tools/list", a member of Keycard::Action::"MCPProtocol" |
Neither action is checked alone. The gateway reaches an upstream through a token exchange, and Keycard checks every exchange with Keycard::Action::"any" before the action in the table, so a call needs a permit for both. Signing in to the gateway also checks "any" on each upstream, and an upstream that fails that check is left out of the User’s access. Every check is made for the User and again for the Application acting on the User’s behalf: the gateway on each upstream, and the User’s MCP client on the gateway’s own identifier at sign-in. The resource in each evaluation is the upstream MCP server the gateway is talking to, so resource.identifier is that upstream’s MCP URL, not the gateway’s own URL.
Prerequisites
Section titled “Prerequisites”- A Unified Access Gateway with upstream MCP servers attached (see Unified Access Gateway)
- Manager access to the Zone (see Roles & Permissions). The checks under Verify read Policies → Activity, the session Timeline and the Audit Log, which take the organization Admin Role: they need the
events:listpermission, which custom Zone Roles don’t have - Familiarity with authoring and activating Policies (see Access Policies)
- A Policy Set on schema version
2026-06-18. TheMCPProtocolgroup is declared only in that version, so on an earlier schema a rule that uses the group never matches and the upstream’s tools are not listed. When you create the set, choose2026-06-18in the Schema picker. The picker starts on the default version, which may be an earlier one. The Policies in the set must be on the same version, so create them inside the set in step 5 rather than on their own.
Create fine-grained Policies
Section titled “Create fine-grained Policies”-
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 namedcreate_eventbecomes:Keycard::Action::"mcp::tools/call::create_event"Use the bare tool name from the upstream, not the
<upstream>__prefixed name shown in the gateway’s aggregated tool list. The prefix is presentation only: the gateway strips it before evaluating Policy, so the action always carries the name the upstream will actually execute. -
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, the
"any"check on each upstream, and tool discovery on each upstream. MCP clients that request theopenidscope at sign-in also reach the Zone’s OpenID Connect UserInfo Resource, and a denial there fails the whole sign-in, so the sign-in rule covers that Resource too.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 MCP Servers.
@id("gateway-signin")@description("Allow users to sign in to and authorize the gateway, including the Zone's UserInfo Resource")permit (principal is Keycard::User,action,resource) when {["<gateway-mcp-access-url>","<keycard-issuer-url>/openid/connect/userinfo"].contains(resource.identifier)};@id("gateway-upstream-issuance")@description("The any check at sign-in and on every token exchange to the upstreams")permit (principal is Keycard::User,action == Keycard::Action::"any",resource) when {["https://<first-upstream-mcp-url>/mcp","https://<second-upstream-mcp-url>/mcp"].contains(resource.identifier)};@id("gateway-mcp-protocol")@description("Tool discovery on the upstreams")permit (principal is Keycard::User,action in Keycard::Action::"MCPProtocol",resource) when {["https://<first-upstream-mcp-url>/mcp","https://<second-upstream-mcp-url>/mcp"].contains(resource.identifier)};The
MCPProtocolgroup covers the MCP protocol actions that target no specific item, including the discovery actionsmcp::tools/list,mcp::prompts/list,mcp::resources/list, andmcp::resources/templates/list. -
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://<upstream-mcp-url>/mcp"};Under a Policy Set of your own, a tool call that no rule permits is denied. That is not true of the managed default-zone-policies set: its
default-user-grantsPolicy permits every User every action on every Resource, tool calls included. Step 5 builds a set without it; or keep the managed set and add aforbid(see Block one tool, leave the rest). -
Restrict sensitive tools to a Group
Gate mutating and destructive tools on membership of a Keycard Group, which policy reads on every request. The entity ID is the Group’s identifier; see Group-based Policies.
@id("calendar-events-write")@description("Event mutations granted to the calendar-writers Group")permit (principal in Keycard::Group::"calendar-writers",action in[Keycard::Action::"mcp::tools/call::create_event",Keycard::Action::"mcp::tools/call::update_event"],resource) when {resource.identifier == "https://<upstream-mcp-url>/mcp"};@id("calendar-events-delete")@description("Event deletion granted to the calendar-admins Group")permit (principal in Keycard::Group::"calendar-admins",action == Keycard::Action::"mcp::tools/call::delete_event",resource) when {resource.identifier == "https://<upstream-mcp-url>/mcp"};Rules that already read the identity provider’s
groupsclaim keep working: matchcontext.subject_claims.groups.contains("Calendar Writers")behindcontext has subject_claims && context.subject_claims has groupsguards. That claim is a sign-in snapshot, and the policy owner treats it as legacy; which kind of group to use compares the two, and Send group claims covers the provider setup. -
Build and activate a Policy Set
In Console → Policies, create a Policy Set as in Build a custom Policy Set, choosing
2026-06-18in the Schema picker in place of the default. Add each Policy above with Add policy… → Create new policy, so it is saved on the set’s schema: Console won’t publish a set that holds a Policy on a different schema, and a Policy saved on its own starts on the Zone’s default. Create only the first one and click Publish as Candidate while it is the only Policy in the set, then add every other Policy, managed ones included, on the saved set’s page, clicking Save after each. A new set starts empty, so also add the managed default-app-delegation Policy to it (Add policy…): every check also runs for the Application acting on the User’s behalf (the gateway on each upstream, and the User’s MCP client on the gateway’s own identifier at sign-in), and the Policies above permit only the User. Also add default-app-direct-access if agents call upstreams as themselves. Leave default-user-grants out: it permits every User every action on every Resource, so while it is in the active set the rules above restrict nothing.Activate the set. Changes to tool rules take effect on the next tool call; there is nothing to deploy or restart on the gateway.
Block one tool, leave the rest
Section titled “Block one tool, leave the rest”You don’t need an allow-list to take one tool away. A forbid rule wins over every permit, including the managed default-user-grants, so one rule does it:
@id("block-delete-event")@description("Nobody deletes calendar events through the gateway")forbid ( principal, action == Keycard::Action::"mcp::tools/call::delete_event", resource) when { resource.identifier == "https://<upstream-mcp-url>/mcp"};Every other tool on that upstream keeps whatever the rest of the active set permits. If the Zone is still on default-zone-policies, create a Policy Set on schema 2026-06-18 that holds the three managed Policies plus this one and activate it (on the default schema, Console won’t add the managed Policies); the managed set itself can’t be edited. Build a custom Policy Set has the Console steps. Or, shorter, open the default-zone-policies card’s menu and click Duplicate: the copy takes the set’s latest version, on 2026-06-18, with copies of the three managed Policies, so you add only this one. To remove a tool for everyone without writing a rule, switch it off in Tool Management instead.
To take a tool away everywhere in the Zone, leave out the when condition. A forbid that names only the action applies to every Resource in the Zone that has a tool by that name, whichever upstream serves it, and to Users and Applications alike:
@id("no-event-deletes")@description("Nobody deletes a calendar event through any upstream")forbid ( principal, action == Keycard::Action::"mcp::tools/call::delete_event", resource);Keep a rule like this in a Policy of its own, not inside an upstream’s Policy. You can then take it out of the Policy Set and put it back without editing any other rule, and every refusal names it: Action "mcp::tools/call::delete_event" on "<resource-name>" is denied by Policy "<policy-name>" in version <version> of Policy Set "<policy-set-name>".
Verify
Section titled “Verify”Sign in to the gateway as a user in one of the permitted groups and call a permitted tool: it succeeds. Then call a tool that your Policies do not permit. The call is denied before reaching the upstream, and the client receives a JSON-RPC error (-32603, access denied by policy for <upstream-mcp-url>) over HTTP 403 rather than a tool result. Because it is a protocol-level error and not a failed tool result, MCP clients typically surface it as a connection or request error rather than as tool output.
If discovery is denied on every upstream at once, the gateway answers the client’s tools/list with HTTP 403 and no unified upstreams are accessible with the presented grant. When only some upstreams are denied, the response is a successful, partial tool list.
Check Policies → Activity for both decisions: each is a Policy Evaluated entry with its outcome, so a denied call carries the context of what was denied and why. The gateway records each tool call as its token exchange with the upstream. In the session’s Timeline under Sessions, each call is a credentials:issue from the gateway to the upstream (tools/list makes one too), with the Policy’s message on a denied one; in the Audit Log, a permitted call’s credentials:issue names the tool in its Raw Data, under authorization_details, and a denied one names it in its error_message.
Prompts and resources
Section titled “Prompts and resources”MCP prompts and resources are not yet available through a Unified Access Gateway. When these surfaces arrive, they are expected to follow the same action-naming pattern as tools, with the item identifier appended to the method:
| Planned MCP activity | Planned Cedar action |
|---|---|
Prompt (prompts/get) |
Keycard::Action::"mcp::prompts/get::<prompt-name>" |
Resource read (resources/read) |
Keycard::Action::"mcp::resources/read::<resource-uri>" |
A Policy written against those actions would look like any other:
@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://<upstream-mcp-url>/mcp" && context has subject_claims && context.subject_claims has groups && context.subject_claims.groups.contains("Engineering")};Troubleshooting
Section titled “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 thatresource.identifiermatches the upstream MCP server URL exactly. The gateway evaluates against the upstream’s identifier, never the gateway’s own. - A group-gated Policy never matches. For a Keycard Group rule, check the User is a member in Manage groups. For a rule on the identity provider’s
groupsclaim, verify the provider issues it, that Keycard requests it, and that the user signed in after joining the group; Send group claims has the setup. The Policy’scontext has subject_claimsguards only prevent evaluation errors; a missing claim means the Policy silently does not match, which is a denial under your own set and an allow while the manageddefault-user-grantsis still active. - A User sees no tools from an upstream at all. Tool listing is gated by
"any"and thenmcp::tools/liston that upstream. Check the User is permitted both (mcp::tools/listdirectly or via theMCPProtocolgroup, which only schema2026-06-18declares), then have them reconnect. - A client reports “method not found” for a prompt or resource. Expected: a gateway serves the tools surface only. Reach that upstream directly instead of through the gateway if you need its prompts or resources.