Skip to content
Control access

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.

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.

  • 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:list permission, 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. The MCPProtocol group 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, choose 2026-06-18 in 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.
  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 <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.

  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, the "any" check on each upstream, and tool discovery on each upstream. MCP clients that request the openid scope 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 MCPProtocol group covers the MCP protocol actions that target no specific item, including the discovery actions mcp::tools/list, mcp::prompts/list, mcp::resources/list, and mcp::resources/templates/list.

  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://<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-grants Policy 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 a forbid (see Block one tool, leave the rest).

  4. 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 groups claim keep working: match context.subject_claims.groups.contains("Calendar Writers") behind context has subject_claims && context.subject_claims has groups guards. 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.

  5. Build and activate a Policy Set

    In Console → Policies, create a Policy Set as in Build a custom Policy Set, choosing 2026-06-18 in 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.

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>".

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.

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")
};
  • 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. 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 groups claim, 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’s context has subject_claims guards 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 managed default-user-grants is still active.
  • A User sees no tools from an upstream at all. Tool listing is gated by "any" and then mcp::tools/list on that upstream. Check the User is permitted both (mcp::tools/list directly or via the MCPProtocol group, which only schema 2026-06-18 declares), 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.