---
title: Unified Access Gateway | Keycard
description: Expose multiple MCP servers through a single, policy-governed endpoint
---

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`). You control which upstreams the gateway exposes and who can access them via [Access Policies](/admin/access-policies/index.md).

## Prerequisites

Before starting:

- A Keycard Zone with a connected [identity provider](/admin/identity-providers/index.md)
- One or more upstream MCP servers configured in your Zone, for example installed from the [Catalog](/admin/catalog/index.md)
- **Manager** access to the Zone (see [Roles & Permissions](/admin/roles-and-permissions/index.md))

## Create the Gateway

1. **Create a gateway Application**

   In Keycard Console, click **Applications** in the sidebar and click **Create 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.

   Tip

   Name the gateway after the audience it serves, not the upstreams it contains, for example `study-group-tools` rather than `linear-github-gateway`. You can create multiple gateways, each exposing a different set of upstreams to a different group of users.

2. **Attach upstream MCP servers**

   On the gateway’s detail page, under **Dependencies**, click **Add dependency** 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](/admin/catalog/index.md), or configure an internal MCP server on the **Console -> Resources** page first.

   Note

   Tool names are prefixed with the upstream name in the aggregated tool list, so tools from different upstreams never collide. Keep upstream names short and recognizable; users select tools by these prefixes.

3. **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, which follows the format `https://<gateway-name>.<zone-id>.mcp.gateway.context/mcp`. 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 == "https://<gateway-name>.<zone-id>.mcp.gateway.context/mcp" &&
     context has subject_claims &&
     context.subject_claims has groups &&
     context.subject_claims.groups.contains("Law Study Group")
   };
   ```

   See [Access Policies](/admin/access-policies/index.md) for authoring and activating Policies.

   Note

   Access is enforced at upstream granularity. A user who is not authorized for an upstream still connects successfully; that upstream’s tools are simply excluded from their tool list. Tool-granularity enforcement is coming soon — see [Fine-Grain Authorization](/admin/unified-access-gateway/fine-grain-authorization/index.md).

4. **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](/cli/index.md) to automatically discover the endpoint and configure it in a supported coding agent for them.

## Verify

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.

## Troubleshooting

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

## Next Steps

- Restrict who can reach each upstream with [Access Policies](/admin/access-policies/index.md).
- Gate individual tool calls with [Fine-Grain Authorization](/admin/unified-access-gateway/fine-grain-authorization/index.md).
- Add more upstream MCP servers from the [Catalog](/admin/catalog/index.md).
- Review tool call events in the audit log, or export them with [Audit Log Export](/admin/audit-log-export/index.md).