Set up the MCP Identity Gateway

This guide explains how to deploy and configure the Model Context Protocol (MCP)Model Context Protocol: A standard protocol for AI agent and server interactions that defines how AI assistants communicate with external tools and data sources.Learn more(opens in new tab) Identity Gateway.

Prerequisites

Before you begin, ensure you have:

• Aembit TenantAembit Tenant: Aembit Tenants serve as isolated, dedicated environments within Aembit that provide complete separation of administrative domains and security configurations.Learn more with admin access
• Compute host for the MCP Identity Gateway (Linux virtual machine)
• Network access from the MCP Identity Gateway to:
  • Your Aembit Tenant (https://<tenantId>.aembit.io, outbound HTTPS)
  • Target MCP serversMCP Server: A server that implements the Model Context Protocol to provide tools, resources, or data to AI agents and MCP clients.Learn more (outbound HTTPS)
  • MCP clientsMCP Client: An application (such as Claude Desktop, Claude Code, or Gemini CLI) that connects to MCP servers to access tools and resources on behalf of users.Learn more/AI agents (inbound on listener port)
• TLS certificate for the MCP Identity Gateway endpoint (public certificate authority or internal public key infrastructure)
• DNS hostname for the MCP Identity Gateway (for example, mcp-gateway.example.com)

Deploy MCP Identity Gateway

The following sections guide you through deploying and configuring the MCP Identity Gateway in your environment.

Customer-deployed infrastructure

The MCP Identity Gateway is always deployed and operated by the customer in their own infrastructure, not by Aembit.

Current deployment method

In the current limited beta, Aembit delivers the MCP Identity Gateway only as a Linux service on a virtual machine (such as an Ubuntu VM in AWS). Containerized and fully managed deployments aren’t available yet.

• Host - A customer-managed environment (Linux VM) where the MCP Identity Gateway runs as a service.
• Network placement - Internet-facing with a public DNS name for SaaS AI agents (such as Claude or Gemini).
• Configuration - Connection to Aembit control plane, MCP server information, and TLS settings.

You retain control over network boundaries, data locality, and integration with existing infrastructure.

Provision infrastructure

In the current limited beta, Aembit supports the MCP Identity Gateway only as a Linux service running on a virtual machine.

Create a Linux virtual machine for the MCP Identity Gateway with network access to:

• Incoming MCP client connections
• Outgoing connections to the Aembit control plane
• Outgoing connections to all configured MCP servers

See Linux virtual machine deployment for detailed instructions.

Set up the Agent Controller

The MCP Identity Gateway requires a colocated Agent Controller to register with Aembit Cloud and receive credentials and configuration. Install the Agent Controller on the same host before installing the MCP Identity Gateway.

See Install Agent Controller on Linux for full instructions. Use the following configuration:

Setting	Value	Reason
TLS	Off	The MCP Identity Gateway handles TLS termination and communicates with the Agent Controller over localhost.
Registration	Trust Provider-based	Recommended for automated registration
Port	5000 (default)	The MCP Identity Gateway connects to http://localhost:5000

Network placement

Position the MCP Identity Gateway where it can accept connections from MCP clients and reach your MCP servers.

• The MCP Identity Gateway runs in your cloud or data center.
• It has a public DNS name (for example, mcp-gateway.example.com).
• It listens on a TLS-protected port (typically 443) with a certificate trusted by the clients.

Deploy multiple MCP Identity Gateway instances for different environments (development, testing, production) or for different regions or business units.

Install and register MCP Identity Gateway

Download, install, and start the MCP Identity Gateway on your provisioned host. The Gateway registers with Aembit Cloud through the colocated Agent Controller.

1. Download the MCP Identity Gateway binary from the Aembit releases portal.

2. Install the MCP Identity Gateway software on the host using the appropriate package for your platform.

   # Example install command with required environment variables
   sudo AEMBIT_TENANT_URL="https://<tenantId>.aembit.io" \
   AEMBIT_MCP_GATEWAY_URL="https://mcp-gateway.example.com" \
   AEMBIT_TLS_CERT_CHAIN_PATH="/etc/aembit/certs/fullchain.pem" \
   AEMBIT_TLS_PRIVATE_KEY_PATH="/etc/aembit/certs/privkey.pem" \
   AEMBIT_AGENT_CONTROLLER_URL="http://localhost:5000" \
   AEMBIT_LOG_LEVEL="info" \
   ./install

   Finding placeholder values

   <tenantId> is your Aembit tenant ID, visible in the console URL (for example, abc123 in https://abc123.aembit.io).

3. Start the MCP Identity Gateway service and verify it is running:

   sudo systemctl status aembit_mcp_gateway

Configure an Identity Provider

Connect Aembit to your enterprise Identity Provider (IdP) to authenticate the humans behind MCP clients.

Unlike typical Aembit workload-to-workload scenarios, MCP requests involve two identities:

• MCP client identity (workload) - The AI agent or application making the request, identified by its redirect URL.
• User identity (human) - The person using the AI agent, identified by claims from your IdP (such as email address).

The MCP Identity Gateway needs both: it validates which MCP client is connecting and who is using it. The Credential Provider then stores tokens per-user, tying each user’s MCP server access to their own authorization.

In this model, you configure identity once at the tenant level. Many users can share the same set of policies, while the per-user credentials the Credential Provider manages isolate their individual access.

In your Aembit Tenant, go to Administration -> Identity Providers and configure your IdP using OIDC or SAML.

Automating configuration

Automate Workload, Trust Provider, Credential Provider, and Access Policy creation using the Aembit Terraform provider or the Aembit API.

Create the client-to-gateway Access Policy

The MCP Identity Gateway requires two Access Policies to function: one for the client-to-Gateway connection and one for the Gateway-to-server connection. You must create both policies for the Gateway to work.

This section covers creating the first policy, which governs which MCP clients and users can connect to the MCP Identity Gateway. For step-by-step instructions on using the Access Policy Builder interface, see Create an Access Policy.

Name the Access Policy

1. While still in your Aembit Tenant, go to Access Policies and click + New.
2. Click the Access Policy card in the left panel.
3. In the Access Policy Name field, enter a name (for example, MCP Client to Gateway).

Client Workload

Create a Client WorkloadClient Workload: Client Workloads represent software applications, scripts, or automated processes that initiate access requests to Server Workloads, operating autonomously without direct user interaction.Learn more that represents the MCP client connecting to the Gateway.

1. Click the Client Workload card in the left panel.

2. Select the Add New tab.

3. Configure the Client Workload with the following settings:

   Field	Value
   Name	A descriptive name (for example, Claude MCP Client)
   Client Identification	Select Redirect URL
   Value	The MCP client’s OAuth callback URL (for example, https://claude.ai/api/mcp/auth_callback)

4. Click Save.

The Redirect URL identifies which MCP client application is requesting access. Each MCP client (Claude, Gemini, etc.) has its own callback URL. See Client Workloads for additional configuration options.

Server Workload

Create a Server WorkloadServer Workload: Server Workloads represent target services, APIs, databases, or applications that receive and respond to access requests from Client Workloads.Learn more that represents the MCP Identity Gateway endpoint.

1. Click the Server Workload card in the left panel.

2. Select the Add New tab.

3. Configure the Server Workload with the following settings:

   Field	Value
   Name	A descriptive name (for example, MCP Identity Gateway)
   Host	The Gateway’s public hostname (for example, mcp-gateway.example.com)
   Application Protocol	Select MCP
   Port	443
   TLS	Enabled
   Path	Leave empty

4. Click Save.

Path must be empty

MCP clients connect to the Gateway’s root endpoint, not a subpath like /mcp.

See Server Workloads for additional configuration options.

Trust Provider

Create a Trust ProviderTrust Provider: Trust Providers validate Client Workload identities through workload attestation, verifying identity claims from the workload's runtime environment rather than relying on pre-shared secrets.Learn more that validates user tokens from your enterprise IdP.

1. Click the Trust Providers card in the left panel.

2. Select the Add New tab.

3. Configure the Trust Provider with the following settings:

   Field	Value
   Name	A descriptive name (for example, Okta User Tokens)
   Trust Provider	Select OIDC ID Token
   OIDC Discovery URL	Your IdP’s discovery endpoint (for example, https://your-org.okta.com)
   Match Rules	Configure issuer validation

4. Configure Match Rules to validate identity token claims:

   • Issuer (iss) - Your IdP’s URL (for example, https://your-org.okta.com). This must match the OIDC Discovery URL.
   • Audience (aud) - (Optional) The intended recipient identifier.
   • Subject (sub) - (Optional) User identifier pattern to match.

5. Click Save.

Find your IdP’s OIDC discovery URL in your identity provider’s administrator console. Enter only the base URL (for example, https://your-org.okta.com)—Aembit automatically appends /.well-known/openid-configuration to discover the provider’s configuration. See Trust Providers for additional configuration options.

Credential Provider

Create a Credential ProviderCredential Provider: Credential Providers obtain the specific access credentials—such as API keys, OAuth tokens, or temporary cloud credentials—that Client Workloads need to authenticate to Server Workloads.Learn more that issues tokens for MCP clients to authenticate to the Gateway.

1. Click the Credential Provider card in the left panel.

2. Select the Add New tab.

3. Configure the Credential Provider with the following settings:

   Field	Value
   Name	A descriptive name (for example, Gateway Access Token)
   Credential Type	Select OIDC ID Token
   Subject	Select Dynamic from the dropdown, then enter ${oidc.identityToken.decode.payload.<user_claim>} (see the following tip)
   Audience	The Gateway URL (for example, https://mcp-gateway.example.com)
   Signing Algorithm Type	RS256 (recommended) or ES256

4. Click Save.

UI Terminology

The Aembit Cloud UI labels this credential type as ‘OIDC ID Token’, but what’s generated is an OAuth 2.0 access token in JWT format. This documentation uses ‘access token’ in conceptual explanations while preserving the exact UI field values in step-by-step instructions.

Choosing a user identifier claim

Replace <user_claim> with a claim from your IdP that uniquely identifies users (for example, email, sub, or preferred_username). The exact claim name depends on your Identity Provider—check your IdP’s token documentation to find available claims.

Unlike typical workload-to-workload scenarios, MCP traffic involves a human user. This dynamic claim identifies who is using the AI agent, enabling per-user access control. See User identity in MCP traffic for details, or OIDC Dynamic Claims for the full syntax reference.

The token contains the authenticated user’s identity (for example, an email claim) and targets only the MCP Identity Gateway. See Credential Providers for additional configuration options.

Save the Access Policy

1. Verify all components show green checkmarks in the left panel.
2. Click Save Policy in the header bar.
3. Enable the Active toggle to activate the policy.

Create the gateway-to-server Access Policy

The second policy governs the MCP Identity Gateway’s access to each MCP server. The Credential Provider enforces per-user access by storing OAuth tokens for each user.

Per-user access control

In this policy, the Client Workload is the MCP Identity Gateway itself, not individual users. The Credential Provider enforces per-user access: each user completes an OAuth authorization flow once per MCP server, and Aembit stores their tokens individually. Optional Access Conditions can add Time or GeoIP restrictions.

Name the Access Policy

1. While still in your Aembit Tenant, go to Access Policies and click + New.
2. Click the Access Policy card in the left panel.
3. In the Access Policy Name field, enter a name (for example, Gateway to Finance MCP Server).

Client Workload

Create a Client Workload that represents the MCP Identity Gateway as a client.

1. Click the Client Workload card in the left panel.

2. Select the Add New tab.

3. Configure the Client Workload with the following settings:

   Field	Value
   Name	A descriptive name (for example, MCP Identity Gateway)
   Client Identification	Select the identifier that matches how the Gateway authenticates to Aembit (consult your Agent Controller configuration)

4. Click Save.

The Gateway acts as the client when accessing MCP servers. See Client Workloads for additional configuration options.

Server Workload

Create a Server Workload for each downstream MCP server.

1. Click the Server Workload card in the left panel.

2. Select the Add New tab.

3. Configure the Server Workload with the following settings:

   Field	Value
   Name	A descriptive name (for example, Finance MCP Server)
   Host	The MCP server’s hostname (for example, mcp.example.com)
   Application Protocol	Select MCP
   Port	Typically 443 with TLS enabled
   Path	The MCP endpoint path (for example, /integrations/mcp)

4. Click Save.

Find the hostname, path, and port in your MCP server vendor’s documentation. See Server Workloads for additional configuration options.

Trust Provider

Create a Trust Provider that validates Aembit-issued tokens.

1. Click the Trust Providers card in the left panel.

2. Select the Add New tab.

3. Configure the Trust Provider with the following settings:

   Field	Value
   Name	A descriptive name (for example, Aembit MCP Tokens)
   Trust Provider	Select OIDC ID Token
   OIDC Discovery URL	Your Aembit tenant’s base URL (for example, https://<tenantId>.aembit.io)

4. Configure Match Rules to validate Aembit-issued tokens:

   • Audience (aud) - The Gateway identifier (for example, gateway).
   • Issuer (iss) - (Optional) Your Aembit Tenant URL (for example, https://<tenantId>.aembit.io). If you configure this, this must match the OIDC Discovery URL.

5. Click Save.

See Trust Providers for additional configuration options, including how to locate your tenant’s OIDC discovery URL.

Credential Provider

Create a Credential Provider that retrieves credentials for the MCP server. The MCP Identity Gateway supports two credential provider types for this policy, depending on how the MCP server issues credentials.

Choosing a credential type

	MCP User-Based Access Token	OAuth 2.0 Authorization Code
Token storage	Per user. Aembit stores and refreshes each user’s tokens individually.	Per credential provider. One set of tokens, shared across all users.
Authorization flow	Each user completes their own OAuth consent flow on first access through the Gateway.	An administrator clicks Authorize in the Aembit UI during setup.
Best for	SaaS MCP servers that issue credentials scoped to individual users (most common).	MCP servers that accept a shared service account or administrator-authorized token.
Discovery	MCP Server URL field with Discover auto-populates OAuth endpoints from server metadata.	OAuth URL field with URL Discovery auto-populates endpoints.

Most SaaS MCP servers require per-user credentials. Use MCP User-Based Access Token unless the MCP server explicitly accepts shared credentials.

Where to find OAuth client settings

The Client ID, Client Secret, Scopes, and OAuth endpoint URLs come from your MCP server vendor. To find these values:

• Check the vendor’s developer documentation for OAuth or API integration guides.
• Look in the vendor’s administrator console for an app registration or API credentials section.
• Use dynamic client registration if the vendor supports it. Some MCP servers let you register a client by sending a POST request to their registration endpoint, which returns a Client ID automatically.
• Use Discover/URL Discovery after entering the MCP Server URL or OAuth URL. Aembit can auto-populate endpoint URLs and scopes from the server’s published OAuth metadata.

MCP User-Based Access Token

1. Click the Credential Provider card in the left panel.

2. Select the Add New tab.

3. Configure the Credential Provider with the following settings:

   Field	Value
   Name	A descriptive name (for example, Finance MCP User Token)
   Credential Type	Select MCP User-Based Access Token
   MCP Server URL	The MCP server’s base URL (for example, https://mcp.example.com/mcp)

4. Click Discover to auto-populate the Authorization URL, Token URL, and Scopes from the MCP server’s metadata.

   If the MCP server does not support discovery, enter the Authorization URL and Token URL manually using values from the MCP server vendor’s documentation.

5. Enter the remaining OAuth client settings:

   Field	Value
   Client ID	Your OAuth client ID for the MCP server
   Client Secret	The OAuth client secret, if required
   Scopes	Required scopes (may be auto-populated by Discover)
   PKCE Required	Enable if the MCP server requires Proof Key for Code Exchange (PKCE)

6. Click Save.

Per-user authorization

Unlike the OAuth 2.0 Authorization Code Credential Provider, this type doesn’t require an administrator to click Authorize during setup. Instead, each user completes their own OAuth consent flow the first time they access the MCP server through the Gateway. Aembit stores and refreshes each user’s tokens individually.

OAuth 2.0 Authorization Code

1. Click the Credential Provider card in the left panel.

2. Select the Add New tab.

3. Configure the Credential Provider with the following settings:

   Field	Value
   Name	A descriptive name (for example, Finance Shared OAuth Token)
   Credential Type	Select OAuth 2.0 Authorization Code

4. Enter the OAuth client settings:

   Field	Value
   Client ID	Your OAuth client ID for the MCP server
   Client Secret	The OAuth client secret, if required
   Scopes	Required scopes (for example, read:all offline_access)
   OAuth URL	The base URL of the OAuth endpoints (for example, https://mcp.example.com/oauth). Click URL Discovery to auto-populate the Authorization URL and Token URL.
   Authorization URL	The endpoint where the user authenticates and grants consent (auto-populated by URL Discovery if available)
   Token URL	The endpoint that exchanges authorization codes for access tokens (auto-populated by URL Discovery if available)
   PKCE Required	Enable if the MCP server requires Proof Key for Code Exchange (PKCE)
   Lifetime	The expected lifetime of the authorization (for example, 1 year)

5. Click Save.

6. After saving, click Authorize to complete the OAuth flow. An administrator must authenticate with the MCP server and grant access. All users who access this MCP server through the Gateway share the resulting tokens.

Shared authorization

With this credential type, an administrator completes the OAuth flow once during setup. All users who access this MCP server through the Gateway share the same credentials. If the authorization expires, an administrator must re-authorize in the Aembit UI.

OAuth endpoint sources

OAuth endpoint URLs vary by MCP server vendor. Consult your MCP server’s documentation for these values, or use the discovery button to auto-populate them from the server’s metadata.

For more information, see:

• About MCP User-Based Access Tokens for guidance on when each type is appropriate
• Configure MCP User-Based Access Token for the full MCP User-Based configuration reference
• OAuth 2.0 Authorization Code for the full OAuth 2.0 configuration reference
• Credential Providers for all available Credential Provider types

Access Conditions (optional)

Access ConditionsAccess Condition: Access Conditions add dynamic, context-aware constraints to authorization by evaluating circumstances like time, location, or security posture to determine whether to grant access.Learn more add contextual restrictions to the policy. In the current limited beta, the MCP Identity Gateway supports time-based and GeoIP-based conditions for MCP traffic.

To add Access Conditions, click the Access Conditions card in the Access Policy Builder and configure as needed. See Access Conditions for available condition types and configuration options.

Per-user access

Access Conditions are optional. Without them, any authenticated user routed through the Gateway can access the MCP server.

Each user has their own OAuth tokens managed by the Credential Provider—when the Gateway acts on behalf of a user, it retrieves that user’s specific credentials.

Save the Access Policy

1. Verify all components show green checkmarks in the left panel.
2. Click Save Policy in the header bar.
3. Enable the Active toggle to activate the policy.

When the MCP Identity Gateway connects to the Aembit control plane, it automatically discovers which MCP servers are available based on the Access Policies that apply to it. This policy-driven discovery means you can add or remove MCP servers by updating your Aembit configuration without modifying the Gateway itself.

User authorization flow

For MCP servers that require user authorization (for example, via OAuth 2.0 flows), the first access triggers a consent flow:

1. When a user first attempts to access a given MCP server via the MCP Identity Gateway, Aembit detects that no credentials exist for that user and MCP server.
2. Aembit starts an OAuth 2.0 authorization flow and directs the user to authenticate with your IdP and approve the MCP integration (for example, by opening a browser flow).
3. After the user completes the flow, Aembit obtains credentials from the MCP server’s authorization infrastructure and associates those credentials with that user and MCP server.

Subsequent access for that user and server proceeds without repeated consent, subject to token expiration and revocation policies.

Verify the connection

Activate both policies

Both the client-to-Gateway and Gateway-to-server Access Policies must be active before testing. If you didn’t activate them during creation, go to Access Policies and enable the Active toggle for each policy.

Once configuration is complete, verify the end-to-end flow:

1. Verify the MCP Identity Gateway service is active by running the following command:

   sudo systemctl status aembit_mcp_gateway

   Expected: active (running) status. If this fails, check the environment variables and TLS certificate paths.

2. Configure an MCP client to use the MCP Identity Gateway’s endpoint and verify it can establish a TLS connection:

   curl -I "https://<your-gateway-url>/"

   Expected: TLS handshake succeeds (you’ll get an HTTP response, possibly an error since this isn’t a valid MCP request). If this fails, check that DNS resolves correctly and the TLS certificate is valid for the hostname.

3. Confirm the user can authenticate via the IdP and that the MCP Identity Gateway receives a valid token. Use your MCP client to initiate a connection—the IdP / consent flow should appear in the user’s browser.

   If this fails, check the Trust Provider configuration in Aembit and verify the IdP endpoints are correct.

4. Verify the MCP Identity Gateway can evaluate Access Policies and that permitted requests succeed. After authentication, the MCP client should be able to list tools or resources.

   If this fails, check the Access Policy configuration in Aembit—ensure both Client-to-Gateway and Gateway-to-Server policies are active.

5. Check MCP Identity Gateway logs for the connection events:

   sudo journalctl --namespace aembit_mcp_gateway -n 50

   Expected: Log entries showing authentication, policy evaluation, and MCP request handling. See Log Streams to forward logs to external systems.

Relationship to the MCP Authorization Server

The MCP Identity Gateway uses Aembit’s existing authorization capabilities behind the scenes to:

• Authenticate users via your configured Identity Provider (IdP),
• Evaluate Aembit Access Policies, and
• Orchestrate OAuth 2.0 Authorization Code (3LO) flows to MCP servers.

You don’t need to deploy or configure the standalone Aembit MCP Authorization Server product to use the MCP Identity Gateway.

• The public MCP Authorization Server docs (Set up the MCP Authorization Server) describe a separate control-plane deployment where Aembit acts as the official Authorization Server for your MCP servers.
• In the MCP Identity Gateway flow, Aembit Cloud provides those authorization capabilities and wires them into the Gateway for you.

To use the MCP Identity Gateway, you only configure:

• An Identity Provider in your Aembit tenant (OIDC or SAML),
• Two Access Policies:
  • Client-to-Gateway (AI agent → MCP Gateway)
  • Gateway-to-Server (MCP Gateway → MCP server),
• One Credential Provider for each MCP server. Use MCP User-Based Access Token when the server requires per-user OAuth credentials, or OAuth 2.0 Authorization Code for shared credentials.

You shouldn’t follow the “Set up the MCP Authorization Server” steps unless you’re explicitly using Aembit as a standalone MCP Authorization Server for your own MCP servers.

Example end-to-end scenario

1. An administrator configures the Gateway and access policies in Aembit
2. A user opens an AI agent (such as Claude), which connects through the Gateway
3. The user queries an MCP server through the agent
4. An auditor reviews logs to see which user and agent accessed which MCP server and when

Next steps

• Environment variables reference
• MCP Identity Gateway reference