MCP Identity Gateway reference

Operational reference for the MCP Identity Gateway, covering the Aembit-managed service and self-hosted deployments.

For configuration in your , see Set up the MCP Identity Gateway. To deploy and operate the MCP Identity Gateway yourself, see Self-host 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 Identity Gateway validates these tokens using Aembit’s signing keys, whether the keys sign with RS256 or ES256. A token’s audience must be the MCP Identity Gateway’s /mcp endpoint URL or the MCP Identity Gateway URL itself, either with or without a trailing slash. The MCP Identity Gateway accepts a token for up to 3 seconds after it expires.
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 Identity Gateway caches downstream MCP server credentials and configuration in memory to reduce latency. Cached credentials are short-lived and refreshed as needed; the MCP Identity Gateway doesn’t persist them to disk.

Authentication sent to the MCP server

The Gateway-to-Server Server Workload’s Authentication Method and Authentication Scheme decide how the MCP Identity Gateway presents the credential to the MCP server. The following table lists each combination and whether its credential reaches the MCP server:

Authentication method	Authentication scheme	Sent to the MCP server	Notes
HTTP Authentication	Basic	Yes	`Authorization: Basic` header
HTTP Authentication	Bearer	Yes	`Authorization: Bearer` header
HTTP Authentication	Header	Yes	The header you name in Header
HTTP Authentication	AWS Signature v4	No	None
API Key	Header	Yes	The header you name in Header
API Key	Query Parameter	No	None
mTLS Authentication	x509 Certificate	Yes	Needs an Credential Provider and an `https` URL
Password Authentication	Password	No	Applies to database protocols, not MCP

The MCP Identity Gateway rejects a mutual Transport Layer Security (mTLS) connection to an MCP server whose URL uses http://. The MCP Identity Gateway sends the Server Workload’s Static HTTP Headers to the MCP server with every authentication method, including No Authentication.

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, Access Policy evaluation, and credential injection flow.

The MCP Identity Gateway serves clients using either the 2026-07-28 revision of the MCP specification or an earlier revision. The proxied methods apply to both, with revision-specific compatibility behavior where the two revisions differ. The MCP Identity Gateway negotiates each downstream connection, so a client’s revision and a server’s revision don’t have to match.

Capability advertisement

When an MCP client connects, the MCP Identity Gateway advertises the union of the capabilities that its assigned MCP servers support. These capabilities include tools, resources, prompts, and tasks, and whether tools, resources, and prompts send change notifications. This set comes from the assigned MCP servers, not from a fixed list and not from what the client declared.

Advertising a capability is separate from letting a client use it. Tools, resources, and prompts are server capabilities: the MCP Identity Gateway advertises them on behalf of its assigned MCP servers, and a client doesn’t declare them. Task handling and elicitation come from the client. A client using the 2026-07-28 revision declares them on each request, and a client using an earlier revision declares them when it connects:

A task request from a client that didn’t declare tasks fails with error -32021.
The MCP Identity Gateway can relay a request for input to a client using a revision earlier than 2026-07-28. If that client didn’t declare elicitation, the request fails with error -32600. See Elicitation.

Tool methods

Method	Description
`tools/list`	Discovers available tools across all assigned MCP servers and returns each under a prefixed name. See Tool and prompt names. The response includes tool annotations from upstream servers when those servers send them.
`tools/call`	Invokes a tool on the appropriate MCP server, and checks the result against the tool’s output schema. See Tool output validation.

Tool and prompt names

The MCP Identity Gateway names each tool and prompt <server-workload>_<name>, so names from different MCP servers stay apart. <server-workload> is the name of the the tool or prompt came from, with every character other than A-Z, a-z, 0-9, or a hyphen replaced by a hyphen. For example, the create_issue tool from a Server Workload named github.prod reaches the MCP client as github-prod_create_issue.

MCP Tool Access Control matches the name the MCP server publishes, not the prefixed name the MCP client receives. See MCP tool name reference.

Tool output validation

When a tool publishes an output schema in tools/list, the MCP Identity Gateway checks each completed result of that tool against the schema before returning it. This includes a result that a task returns later through tasks/get. When a successful result doesn’t match the schema, or carries no structured content, the MCP client gets error -32004 in place of the result. The error message names the tool and where the result breaks the schema, and the workload event for the call records an error. The MCP Identity Gateway checks a tool error that carries structured content the same way as a successful result. A tool error that carries no structured content passes, because the schema describes successful results.

The MCP Identity Gateway returns the result without checking it in these cases:

The tool published no output schema, or the MCP Identity Gateway hasn’t received the tool in a tools/list response in the last hour.
The MCP Identity Gateway can’t compile the schema, such as when the schema references an external document.
The schema has more than 64 levels of nesting or more than 10,000 nodes.
The result comes from a task, and the MCP Identity Gateway can’t tell which tool started the task or can’t read the task’s result.

A self-hosted MCP Identity Gateway counts each checked or unchecked result in the aembit_mcp_gateway_tool_output_schema_validations_total metric. See Prometheus metrics.

Resource methods

Method	Description
`resources/list`	Discovers available resources across all assigned MCP servers. The MCP Identity 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.

The MCP Identity Gateway returns each resource URI exactly as the MCP server reported it. It prefixes each resource’s name the same way as a tool name. It also puts the name of the that returned it in brackets ahead of the resource’s title and description. An MCP client can then tell resources apart in resources/list. The MCP client sends the URI unchanged in resources/read. Two MCP servers can expose the same URI. The MCP Identity Gateway then sends every read for that URI to the first of them in the MCP client’s assignments that listed or read the URI. If a later read from that MCP server fails, the MCP Identity Gateway doesn’t try the other one. The MCP client can’t choose which of the two resources it reads.

Prompt methods

Method	Description
`prompts/list`	Discovers available prompts across all assigned MCP servers and returns each under a prefixed name. See Tool and prompt names.
`prompts/get`	Retrieves a specific prompt from the MCP server that exposes it.

Task methods

Tasks let an MCP server accept work that outlives a single call and report on it later.

Method	Description
`tasks/get`	Returns the current state of a task from the MCP server that created it.
`tasks/update`	Sends input a task is waiting on to the MCP server that created it.
`tasks/cancel`	Cancels a task on the MCP server that created it.

Elicitation

An upstream MCP server can ask for more input before it finishes a call. How the MCP Identity Gateway handles the request depends on the revision the MCP server and the client use:

When both use the 2026-07-28 revision, the client receives the server’s request for input, answers it, and retries the call.
When the MCP server uses the 2026-07-28 revision and the client uses an earlier one, the MCP Identity Gateway relays the request as elicitation/create. It sends the client’s answer to the MCP server. The client must declare elicitation. The MCP Identity Gateway doesn’t relay sampling or roots requests to these clients.
When the MCP server uses an earlier revision and sends elicitation/create, the MCP Identity Gateway declines it, and the client never receives it.

Change notifications

A client using the 2026-07-28 revision can subscribe to change notifications by sending subscriptions/listen. A client using an earlier revision that sends subscriptions/listen gets error -32601.

When an assigned MCP server reports that its tools, resources, or prompts have changed, the MCP Identity Gateway relays the matching notification to the subscribed client: notifications/tools/list_changed, notifications/resources/list_changed, or notifications/prompts/list_changed. A client that subscribes to specific resources also receives notifications/resources/updated when one of them changes. The MCP Identity Gateway doesn’t support resources/subscribe or resources/unsubscribe. Subscribe to resources through subscriptions/listen instead.

The MCP Identity Gateway also sends a list_changed notification itself in these cases:

The client’s assigned Server Workloads change, including a change to an assigned Server Workload’s settings, such as its name or URL.
The MCP Tool Access Control rules that apply to the client change.
The MCP Identity Gateway reconnects to an MCP server after the connection drops.

The MCP Identity Gateway checks for assignment and rule changes every 30 seconds by default. The subscriptions_workload_refresh_interval name in AEMBIT_MCP_GATEWAY_TIMEOUT sets the interval.

The MCP Identity Gateway relays notifications only from MCP servers that use the 2026-07-28 revision. When its connection to an MCP server for notifications drops, it reconnects after a delay that starts at 200 milliseconds and doubles up to 5 minutes. The MCP Identity Gateway stops reconnecting when a retry would get the same answer, such as HTTP status 401, 403, 404, 405, 501, or 505. It keeps reconnecting after a timeout, a rate limit, or another server error such as 503. After it stops, it reconnects to that MCP server only after that Server Workload changes, or after the client reconnects and subscribes again.

A subscription ends when the client’s access token expires. The client gets error -32005 and must reconnect with a fresh token. A subscription also ends when the MCP Identity Gateway can’t refresh the client’s assignments from Aembit Cloud. A second subscriptions/listen request fails when the client already has a subscription open on the same connection. The client can reconnect and subscribe again.

Methods the MCP Identity Gateway answers itself

resources/templates/list and completion/complete return an empty result.
ping returns a result for clients using revisions earlier than 2026-07-28, and error -32601 for clients using the 2026-07-28 revision.
logging/setLevel, resources/subscribe, resources/unsubscribe, tasks/list, and tasks/result return error -32601.
subscriptions/listen returns error -32601 for clients using revisions earlier than 2026-07-28. See Change notifications.

Errors from MCP servers

When an MCP server answers a request with an HTTP error status, the MCP client receives error -32603. The error’s data object carries the MCP server’s HTTP status code in upstreamHttpStatus:

{
  "code": -32603,
  "message": "upstream MCP server rejected the request with HTTP 502 Bad Gateway",
  "data": { "upstreamHttpStatus": 502 }
}

The message text varies by request, so read the status code from upstreamHttpStatus. A list request that spans more than one MCP server, such as tools/list, leaves out the MCP server that failed and returns results from the rest.

Transport

The MCP Identity Gateway uses the streamable HTTP transport. A client using a revision earlier than 2026-07-28 can send an HTTP GET request with its session identifier to the /mcp endpoint. The MCP Identity Gateway answers it with a stream of messages. For a client using the 2026-07-28 revision, an HTTP GET request returns 405 Method Not Allowed.

Session management

Sessions belong to the 2025-11-25 revision of the MCP specification and earlier revisions. The 2026-07-28 revision removes sessions, so the MCP Identity Gateway doesn’t create a session for clients using that revision. When such a client reaches an MCP server running an earlier revision, the MCP Identity Gateway performs that server’s handshake and manages the upstream session itself.

MCP clients can end their session with the MCP Identity Gateway by sending an HTTP DELETE request to the /mcp endpoint with the mcp-session-id header set to the session identifier. The MCP Identity Gateway returns 202 Accepted 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: 202 Accepted

This behavior implements session management in the MCP specification.

The MCP Identity Gateway also ends a session that stays idle, and a self-hosted MCP Identity Gateway keeps sessions in memory unless you configure a session store. For both, see Session persistence.

Connectivity requirements

Aembit operates the MCP Identity Gateway endpoint at https://<tenantId>.mcpgateway.aembit.io (replace <tenantId> with your Aembit Tenant ID). For MCP clients to reach the MCP Identity 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 MCP Identity Gateway validates tokens against the configured Trust Provider and uses streamable HTTP transport for server-to-client streaming.

Aembit manages the MCP Identity Gateway’s outbound paths to the Aembit Cloud control plane, MCP servers, and IdP discovery endpoints, so these don’t require customer configuration. The Aembit-managed MCP Identity Gateway connects only to MCP servers at publicly reachable addresses.

Neither the managed nor the self-hosted MCP Identity Gateway follows HTTP redirects from an MCP server. Set each Server Workload to the MCP server’s final URL. A request that the MCP server redirects fails, and the MCP Identity Gateway records the failure in a workload event.

Logging and events

Log access

Because Aembit operates the MCP Identity 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.

If you self-host the MCP Identity Gateway, you access its runtime logs directly on the host. See Logs under Self-hosted operations.

Workload events

Workload events in capture access patterns for audit and observability. See Audit and report on Workload activity for details.

The MCP Identity Gateway emits Client-to-Gateway mcp.request and mcp.response events for every request that passes access token validation. It also emits them when it rejects a correctly signed access token because of its claims, such as an audience that doesn’t match.

Gateway-to-Server workload events cover:

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

A request the Gateway rejects before it can trust the access token produces no workload event. That includes an access token whose signature doesn’t verify, and one that has expired or isn’t valid yet. The Gateway logs each access token it rejects. If you self-host the MCP Identity Gateway, check its logs for those requests.

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.

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 Access Policy decisions—which Access 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 MCP Identity 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.
Specification revisions - The MCP Identity Gateway supports the 2026-07-28 revision of the MCP specification and earlier revisions. It serves each client using the revision the client asks for, when the MCP Identity Gateway supports that revision.

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

Check the MCP Identity Gateway version

The document that MCP Identity Gateway serves reports its version in the aembit_gateway_version field. The document needs no access token, so you can read it for the Aembit-managed service and for a self-hosted MCP Identity Gateway:

curl "https://<tenant-id>.mcpgateway.aembit.io/.well-known/oauth-protected-resource/mcp"

MCP Identity Gateway serves the same document at /.well-known/oauth-protected-resource. For a self-hosted MCP Identity Gateway, replace the host with your MCP Identity Gateway’s URL.

{
  "resource": "https://<tenant-id>.mcpgateway.aembit.io/mcp",
  "authorization_servers": ["<authorization-server-url>"],
  "scopes_supported": ["https://<tenant-id>.mcpgateway.aembit.io/mcp"],
  "aembit_gateway_version": "1.35.6263"
}

MCP Identity Gateway versions earlier than 1.35.6263 do not include the aembit_gateway_version field.

Deployment model

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

Aembit provisions, operates, and upgrades the MCP Identity 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 an MCP Identity Gateway endpoint for your Aembit Tenant, contact your Aembit representative.

As a secondary option, you can self-host the MCP Identity Gateway in your own infrastructure. See Self-host the MCP Identity Gateway and Self-hosted operations.

Self-hosted operations

The following sections apply only when you self-host the MCP Identity Gateway. For the Aembit-managed service, Aembit handles service management, networking, logging, and metrics for you.

Service management

A self-hosted MCP Identity Gateway runs as a systemd service named aembit_mcp_gateway.

# Check service status
sudo systemctl status aembit_mcp_gateway

# Restart the service
sudo systemctl restart aembit_mcp_gateway

# Stop the service
sudo systemctl stop aembit_mcp_gateway

# Start the service
sudo systemctl start aembit_mcp_gateway

# Follow logs
journalctl --namespace aembit_mcp_gateway -f

Network requirements

Open the following network paths for the host running a self-hosted MCP Identity Gateway.

Inbound

Port	Protocol	Purpose
443	TCP/TLS	MCP client connections
80	TCP	TLS certificate provisioning (Let’s Encrypt)
9091	TCP/HTTP	Prometheus metrics (configurable via `AEMBIT_METRICS_PORT`)

Outbound

Port	Target	Destination	Purpose
443	Aembit Cloud	`https://<tenantId>.aembit.io`	Authorization, Access Policy, and credentials
443	MCP servers	`https://<mcp-server-host>`	Proxied MCP traffic
443	IdP endpoints	`https://<idp-host>/...`	OAuth/OIDC user authentication
5000	Agent Controller	`http://localhost:5000`	Registration (localhost only)

To limit a self-hosted MCP Identity Gateway to MCP servers at publicly reachable addresses, set AEMBIT_NETWORK_ACCESS_POLICY to public.

Logs

A self-hosted MCP Identity Gateway writes logs to journald. View them using journalctl:

# Follow logs in real-time
journalctl --namespace aembit_mcp_gateway -f

# View recent logs
journalctl --namespace aembit_mcp_gateway -n 100

# View logs since a specific time
journalctl --namespace aembit_mcp_gateway --since "1 hour ago"

Prometheus metrics

The MCP Identity Gateway exposes a Prometheus-compatible metrics endpoint for integration with observability tools.

Endpoint

The metrics endpoint is available at /metrics on a configurable port (default 9091). To override the port, set AEMBIT_METRICS_PORT during installation. See MCP Identity Gateway environment variables for details.

The default port is 9091 to avoid a collision with the Agent Controller, which exposes its metrics on port 9090 on the same host.

Process and runtime metrics

Metric	Type	Labels	Description
`machine_cpu_cores`	`gauge`	`component`, `hostname`	Number of CPU cores available to the MCP Identity Gateway
`version`	`gauge`	`component`, `version`	MCP Identity Gateway version
`process_cpu_seconds_total`	`counter`	`component`, `hostname`	CPU seconds consumed by the MCP Identity Gateway process
`process_memory_usage_bytes`	`gauge`	`component`, `hostname`	Memory consumed by the MCP Identity Gateway process (bytes)

Session metrics

Metric	Type	Labels	Description
`aembit_mcp_gateway_sessions_created_total`	`counter`	`tenant_id`	MCP sessions the Gateway created since it started
`aembit_mcp_gateway_sessions_active`	`gauge`	`tenant_id`	MCP sessions that are open. The Gateway recomputes this value from the session store on an interval, so it can lag the true count
`aembit_mcp_gateway_session_cleanup_last_run_timestamp_seconds`	`gauge`	none	Unix timestamp of the last completed session cleanup run, for the whole process. A value that stops advancing means the cleanup task stopped

Request processing metrics

Metric	Type	Labels	Description
`aembit_mcp_gateway_mcp_requests_processed_total`	`counter`	`tenant_id`, `method`, `outcome`	MCP requests the Gateway processed
`aembit_mcp_gateway_mcp_request_duration_seconds`	`histogram`	`tenant_id`, `method`	Time the Gateway spent processing an MCP request, excluding time spent waiting on MCP servers
`aembit_mcp_gateway_tool_output_schema_validations_total`	`counter`	`tenant_id`, `outcome`	Completed tool results, by the result of the output schema check. `blocked` means the result didn’t match its tool’s output schema and the client received error `-32004` instead

Fanout requests always report success here

For a request the Gateway fans out to your MCP servers, it builds the client response itself, whatever the upstream servers return. Those requests count as outcome="success" in aembit_mcp_gateway_mcp_requests_processed_total. To see upstream health, use aembit_mcp_gateway_upstream_mcp_server_fanout_workloads_failed_total against aembit_mcp_gateway_upstream_mcp_server_fanout_workloads_total.

Upstream MCP server metrics

Metric	Type	Labels	Description
`aembit_mcp_gateway_upstream_mcp_server_http_requests_total`	`counter`	`tenant_id`, `method`, `outcome`	HTTP requests the Gateway sent to upstream MCP servers
`aembit_mcp_gateway_upstream_mcp_server_mcp_responses_total`	`counter`	`tenant_id`, `method`, `outcome`	MCP protocol responses received from upstream servers. Counts HTTP 2xx responses only
`aembit_mcp_gateway_upstream_mcp_server_response_bytes`	`histogram`	`tenant_id`, `method`	Size in bytes of each HTTP response body received from an upstream server. Recorded whatever the status code, so an oversized error page is as visible as an oversized success body
`aembit_mcp_gateway_upstream_mcp_server_fanout_timeouts_total`	`counter`	`tenant_id`, `method`, `outcome`	Upstream workloads that timed out during a fanout request
`aembit_mcp_gateway_upstream_mcp_server_fanout_duration_seconds`	`histogram`	`tenant_id`, `method`	Time a fanout request took across all its upstream workloads
`aembit_mcp_gateway_upstream_mcp_server_fanout_workloads_total`	`counter`	`tenant_id`, `method`	Upstream workloads that fanout requests attempted
`aembit_mcp_gateway_upstream_mcp_server_fanout_workloads_failed_total`	`counter`	`tenant_id`, `method`	Upstream workloads that failed within a fanout request, through a transport error, a timeout, a non-2xx status, or an MCP-level error. A failed count equal to the attempted count means the upstream fleet was down for that method
`aembit_mcp_gateway_upstream_mcp_server_sessions_restored_count_total`	`counter`	`tenant_id`, `outcome`	Upstream sessions restored from the Gateway session cache
`aembit_mcp_gateway_upstream_mcp_server_sessions_reinitialized_count_total`	`counter`	`tenant_id`, `outcome`	Upstream sessions re-established after the upstream session expired

Authentication and Content Security metrics

Metric	Type	Labels	Description
`aembit_mcp_gateway_auth_failures_total`	`counter`	`tenant_id`, `reason`	Inbound requests the Gateway rejected at the authentication layer. Expired and invalid tokens are normal background traffic; a sustained rate, or a spike in `audience_mismatch`, is worth investigating
`aembit_mcp_gateway_jwks_refresh_attempts_total`	`counter`	`tenant_id`, `outcome`	JWKS load and refresh attempts
`aembit_mcp_gateway_aidr_guard_decisions_total`	`counter`	`tenant_id`, `outcome`	CrowdStrike AIDR scan decisions

Session store and health metrics

Metric	Type	Labels	Description
`aembit_mcp_gateway_session_store_operations_total`	`counter`	`operation`, `outcome`, `reason`	Session store operations
`aembit_mcp_gateway_session_store_operation_duration_seconds`	`histogram`	`operation`, `outcome`, `reason`	Time a session store operation took
`aembit_mcp_gateway_readiness_probe_flaps_total`	`counter`	`probe`	Times a readiness probe went from healthy to unhealthy, for the whole process. The Gateway counts a flap after the probe crosses its consecutive-failure threshold, which is the point where the instance leaves the load balancer rotation

Label values

Label	Applies to	Values
`component`	Process and runtime metrics	`aembit_mcp_gateway`
`hostname`	Process and runtime metrics	The hostname of the machine running the Gateway
`version`	The `version` metric	The MCP Identity Gateway build version, such as `1.34.5733`
`tenant_id`	Every metric with a `tenant_id` label	Your Aembit Tenant ID
`method`	Every metric with a `method` label	The MCP method name, such as `initialize`, `tools/list`, or `tools/call`
`outcome`	Every metric with an `outcome` label, except where noted	`success` or `error`
`outcome`	`aembit_mcp_gateway_aidr_guard_decisions_total`	`scanned`, `fail_open`, or `fail_closed`
`outcome`	`aembit_mcp_gateway_upstream_mcp_server_fanout_timeouts_total`	`timeout`
`outcome`	`aembit_mcp_gateway_tool_output_schema_validations_total`	`valid`, `blocked`, or `unchecked`
`reason`	`aembit_mcp_gateway_auth_failures_total`	`missing_header`, `audience_mismatch`, `invalid_token`, or `token_expired_during_listen`
`reason`	Session store metrics	`none`, `not_found`, or `store_error`
`operation`	Session store metrics	`save`, `get`, `delete`, or `count`
`probe`	`aembit_mcp_gateway_readiness_probe_flaps_total`	`cloud` or `session_store`

Histogram metrics expose _bucket, _count, and _sum series under the metric names in these tables.

Scraping configuration

Configure Prometheus to scrape the metrics endpoint:

scrape_configs:
  - job_name: 'aembit-mcp-gateway'
    static_configs:
      - targets: ['<gateway-host>:9091']

Replace <gateway-host> with your MCP Identity Gateway hostname or IP address.

Supported MCP servers

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

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

The MCP Identity Gateway connects to an MCP server on either the 2026-07-28 revision or an earlier one. It tries the newer revision first and falls back to the earlier handshake when the server doesn’t accept it, so a server using either revision works with no configuration.

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 Access Policies govern all access
Aembit enforces TLS end-to-end: the MCP Identity Gateway terminates TLS at its endpoint and initiates new TLS connections to MCP servers

Non-goals:

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