MCP Identity Gateway reference

Operational reference for the Aembit-operated MCP Identity Gateway.

For Tenant-side configuration, see Set up the MCP Identity Gateway.

Token and credential details

The tokens and credentials used in each hop have different formats and purposes:

Token / Credential	Format	Source
Agent-to-Gateway	Aembit-issued access token (typically JWT)	Issued by the Aembit Authorization Server after the user authenticates via a configured IdP
Gateway-to-Server	Varies by MCP server	Determined by the Credential Provider configuration (for example, OAuth 2.0 access token via Authorization Code flow)

• Agent-to-Gateway tokens - The Aembit Authorization Server issues these tokens after it authenticates the user via an external identity provider (such as Google, Okta, or Microsoft Entra ID). The MCP Gateway validates these tokens using Aembit’s signing keys.
• Gateway-to-Server credentials - Aembit manages these via Credential Providers. For modern SaaS MCP servers, these are typically OAuth 2.0 access tokens obtained via the Authorization Code (3-legged OAuth) flow. Aembit may support other methods depending on how the MCP server authenticates.
• Credential caching - The MCP Gateway caches downstream MCP server credentials and configuration in memory to reduce latency. Cached credentials are short-lived and refreshed as needed; the Gateway doesn’t persist them to disk.

Proxied MCP methods

The MCP Identity Gateway proxies the following MCP protocol methods to downstream MCP servers. All methods go through the same token validation, policy evaluation, and credential injection flow.

Tool methods

Method	Description
tools/list	Discovers available tools across all assigned MCP servers. The Gateway adds prefixes to prevent tool name collisions across servers. The response includes tool annotations from upstream servers when those servers send them.
tools/call	Invokes a tool on the appropriate MCP server.

Resource methods

Method	Description
resources/list	Discovers available resources across all assigned MCP servers. The Gateway fans out the request to all servers and aggregates the results.
resources/read	Retrieves a specific resource by URI from the appropriate MCP server.

No resource prefixing

When the Gateway fans out resources/list across multiple MCP servers, it returns resource URIs as-is without adding server-specific prefixes. If two MCP servers expose resources with the same URI, both appear in the aggregated list. This differs from tool discovery, where the Gateway adds prefixes to tool names to prevent collisions.

Unsupported methods

The MCP Identity Gateway uses streamable HTTP transport, not Server-Sent Events (SSE). HTTP GET requests to the /mcp endpoint return 405 Method Not Allowed, per the MCP specification.

Session management

MCP clients can end their session with the Gateway by sending an HTTP DELETE request to the /mcp endpoint with the mcp-session-id header set to the session identifier. The Gateway returns 204 No Content on success. Subsequent requests that reuse the deleted session ID return 404 Not Found.

curl -X DELETE "https://<gateway-host>/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "mcp-session-id: <session-id>"
# Expected: 204 No Content

This behavior implements MCP specification section 2.5.5.

Connectivity requirements

Aembit operates the Gateway endpoint at https://<tenantId>.mcpgateway.aembit.io (replace <tenantId> with your Aembit Tenant ID). For MCP clients to reach the Gateway, the network paths from your AI agent hosts must allow outbound HTTPS on port 443 to this hostname.

Source	Destination	Port	Purpose
MCP clients / AI agents	https://<tenantId>.mcpgateway.aembit.io	443	MCP requests over TLS
MCP clients / AI agents	Your IdP (Okta, Google, Entra ID, etc.)	443	User authentication during the initial OAuth flow

MCP clients authenticate using access tokens (JWTs) issued by the Aembit Authorization Server after the user authenticates through your configured IdP. The Gateway validates tokens against the configured Trust Provider and uses streamable HTTP transport for server-to-client streaming.

Aembit manages the Gateway’s outbound paths to the Aembit Cloud control plane, MCP servers, and IdP discovery endpoints, so these don’t require customer configuration.

Logging and events

Log access

Because Aembit operates the Gateway, the Aembit operations team manages runtime logs—customers don’t access them directly. For customer-facing visibility into MCP activity, use workload events in Aembit Cloud (see the next section) and forward them via Log Streams to your SIEM or observability tooling.

Workload events

Workload events in Aembit CloudAembit Cloud: Aembit Cloud serves as both the central control plane and management plane, making authorization decisions, evaluating policies, coordinating credential issuance, and providing administrative interfaces for configuration.Learn more capture access patterns for audit and observability. See Audit and report on Workload activity for details.

The userId field

When an identity provider authenticates the MCP client, mcp.request and mcp.response workload events include a userId field containing the subject of the user’s OAuth or OIDC access token. This lets you attribute MCP activity to the specific authenticated user in audit reports.

The userId field is absent when Aembit can’t identify the MCP client, such as when client workload identification fails.

Event coverage

Workload events capture Gateway to MCP Server traffic only. This includes:

• Tool invocations forwarded to upstream MCP servers
• Resource requests forwarded to upstream MCP servers
• Credential injection events
• Policy evaluation results for server access

Agent to Gateway events (such as initial client connections and authentication) don’t appear in workload events. Aembit plans this capability for a future release.

Until Agent-to-Gateway events are available in workload events, if you need connection or authentication visibility, contact your Aembit representative.

Observability

The MCP Identity Gateway produces structured JSON logs that help you:

• Answer “who did what” questions—which user and AI agent accessed which MCP server and tools, and when
• Trace policy decisions—which policy allowed or denied a given request
• Monitor behavior—connection patterns and error rates between AI agents and MCP servers

Forward these logs to Log Streams to integrate with your existing observability and Security Information and Event Management (SIEM) tooling.

Operational considerations

• Policy management - Configure access policies through the Aembit Tenant, Terraform provider, or API.
• Service management - Aembit operates the Gateway as a managed service. The Aembit operations team handles provisioning, upgrades, TLS certificate management, and runtime health.
• Customer-facing observability - Use workload events in Aembit Cloud and forward via Log Streams for visibility into MCP activity.

To verify your Tenant configuration is working correctly, see Verify the connection in the setup guide.

Deployment model

Aembit operates the MCP Identity Gateway as a managed service. Each Aembit Tenant has a per-Tenant Gateway endpoint at https://<tenantId>.mcpgateway.aembit.io.

• Aembit provisions, operates, and upgrades the Gateway.
• Aembit handles TLS termination, certificate management, and runtime operations.
• Customers configure only Aembit Tenant resources (Identity Provider, Trust Provider, Access Policies, Credential Providers).

To request a Gateway endpoint for your Tenant, contact your Aembit representative.

Supported MCP servers

The Gateway supports both third-party SaaS MCP providers and customer-built MCP servers, subject to compatibility and configuration.

Aembit has validated the Gateway with a small set of MCP servers. Additional MCP servers may work but Aembit considers them best-effort until explicitly documented.

Security guarantees and non-goals

Guarantees:

• The Identity Gateway authenticates every request before any processing—unauthenticated requests receive 401 immediately and are never forwarded to MCP servers
• AI agents never receive downstream credentials for MCP servers
• Centrally managed Aembit policies govern all access
• Aembit enforces TLS end-to-end: the Gateway terminates TLS at its endpoint and initiates new TLS connections to MCP servers

Non-goals:

• The Gateway doesn’t replace the MCP server’s internal authorization logic
• The Gateway doesn’t inspect or filter prompt content beyond what policy evaluation requires

See also

• MCP Identity Gateway concepts - Architecture, identity model, and access policies
• Environment variables - Operator reference (the environment variables Aembit sets when provisioning a Gateway)