Unified Access Gateway

A unified access gateway aggregates the tools from multiple upstream MCP servers behind a single MCP endpoint. Instead of advertising a separate connection for every MCP server, you hand your users one endpoint: they authenticate once through your identity provider, authorize the upstreams they need, and receive one tool list with every tool namespaced by its upstream (for example, github__create_issue). Two controls then shape what the gateway does: Tool Management decides which tools it serves at all, and Access Policies decide who may call them. When to use which is below.

Before starting:

• A Keycard Zone with a connected identity provider
• One or more upstream MCP servers configured in your Zone, for example installed from the Catalog
• Manager access to the Zone (see Roles & Permissions)

1. Create a gateway Application

   In Keycard Console, click Applications in the sidebar and click Add Application. In the form, enable the Proxy MCP Tools toggle to aggregate all tools from MCP servers through a single URL.

   Field	Value
   Name	<gateway-name>
   Proxy MCP Tools	Enabled
   Documentation URL	Optional
   Description	Optional

   Enabling Proxy MCP Tools removes the identifier, consent, and redirect URL fields from the form: the gateway’s MCP URL is generated for you when the Application is created.

2. Attach upstream MCP servers

   On the gateway’s page, open the MCP Servers tab, click Add MCP Server, and select each upstream MCP server to expose through the gateway, for example Linear and GitHub.

   Only Resources already configured in the Zone appear in the list. To add a new upstream, install a third-party MCP server from the Catalog, or add a custom resource with MCP Server turned on.

3. Choose which tools the gateway serves (optional)

   Every server you attach starts by serving all of its tools. To leave some out for everyone who connects, open the server from the MCP Servers tab and turn those tools off. Anything the vendor ships later then stays off until someone turns it on. See Tool Management for the steps.

4. Grant access (optional)

   By default, the Zone’s managed Policies permit all authenticated users to access the gateway and its upstreams. To restrict access, add a Policy that permits only specific users or groups.

   Click Policies in the sidebar and create a Policy scoped to the gateway’s Resource identifier. That identifier is the gateway’s MCP Access URL on its Application settings page, which has the form https://unified-<gateway-slug>-<zone-id>.mcp.gateway.context.cloud/mcp. Copy it from there rather than typing it: Keycard derives <gateway-slug> from the gateway name and shortens long names. For example, permit only members of the Law Study Group IdP group:

   @id("permit-law-study-group-gateway")
   permit (
     principal is Keycard::User,
     action,
     resource
   ) when {
     resource.identifier == "<gateway-mcp-access-url>" &&
     context has subject_claims &&
     context.subject_claims has groups &&
     context.subject_claims.groups.contains("Law Study Group")
   };

   See Access Policies for authoring and activating Policies.

5. Share the endpoint with your users

   Open the gateway’s Application settings page and copy the MCP Access URL using the copy button next to the field. Distribute this URL to your users: each user adds this single URL to their MCP client, signs in through the identity provider, and authorizes the upstreams they need.

   Optionally, users can use the Keycard CLI to automatically discover the endpoint and configure it in a supported coding agent for them.

The two controls answer different questions. Curation decides which tools the gateway has. A Policy decides who may call the tools it has.

You want to	Use	Page
Take a tool away from everyone who connects, or hold back tools the vendor ships later until someone reviews them	Curation: turn the tool off on the gateway. Nothing to write, and the tool leaves every user’s list.	Tool Management
Let some people call a tool and not others, by user, Group, or identity provider group	A Policy on the tool’s mcp::tools/call::<tool-name> action	Fine-Grained Authorization

Use both together: curate the set down to what this gateway should offer at all, then write Policies only for the tools whose answer differs by person. Curation applies to the gateway path only; a client holding a credential for the upstream itself still sees the upstream’s full tool set.

Add the gateway endpoint to an MCP client, sign in as a user with access (for example, annie.edison@greendale.edu), and authorize the upstreams when prompted. In Claude Code, run /mcp and confirm the gateway appears with an aggregated tool list where every tool carries an upstream prefix, such as github__create_issue and linear__list_issues.

To confirm tool calls flow through the gateway, invoke a tool and check Console -> Audit Log for the event showing who invoked which tool on which upstream.

• A user doesn’t see tools from an upstream. The user is either not permitted by Policy or has not authorized that upstream. Check your access Policies for the upstream Resource, then have the user reconnect and complete the authorization prompt.

• One tool is missing for every user. It is probably turned off on the gateway. Open the server from the MCP Servers tab and check whether it reads Selected actions with that tool off; see Tool Management.

• A newly attached upstream doesn’t appear for existing users. Users who signed in before the upstream was attached must sign in again to issue grants for it. Have them log out of the gateway connection and reconnect.

• A user lost access to an upstream mid-session. If the upstream does not support refreshable grants, the user must sign in again to restore access.

• Sign-in fails with unknown resource though the gateway URL answers. A 401 from a gateway host doesn’t show that the gateway exists, because the gateway builds that 401 and its protected resource metadata from the hostname alone.

  A gateway that was never created, or a URL with a typo in it, answers the same way. Its metadata names an authorization server too, taken from the Zone ID at the end of the first label. Keycard checks the URL against the Zone’s Resources only when the client requests authorization, and Requested authorization for unknown resource "<gateway-mcp-access-url>". means that Zone has no gateway at that URL. Copy the MCP Access URL from the gateway’s Application settings page again rather than building it by hand.

• Every call returns 401 after a successful sign-in. If you created the gateway’s Application with Terraform or the Management API, check that its host starts with unified-. Console always generates hosts of the form unified-<gateway-slug>-<zone-id>.

  The gateway service treats a host as a Unified Access Gateway only when its route slug, the part of the first label before the Zone ID, is unified or starts with unified-. On any other host it serves its generic client metadata instead of the gateway’s own, so sign-in and token issue succeed and then every call fails with 401 before it reaches an upstream.

  To check a host before anyone signs in, fetch https://<gateway-host>/oauth_client. The client_id in the response should be that same URL, and https://mcp.gateway.context.cloud/oauth_client means the host isn’t recognized as a gateway. Move the gateway to a host that starts with unified-, and use that host everywhere it appears, including the Application’s identifier and its /oauth_client URL credential.

• Choose which tools the gateway serves with Tool Management.
• Restrict who can reach each upstream with Access Policies.
• Gate individual tool calls with Fine-Grained Authorization.
• Let agents call API-key upstreams on their own behalf with Autonomous Agent Access.
• Add more upstream MCP servers from the Catalog.
• Review tool call events in the audit log, or export them with Audit Log Export.