MCP Identity Gateway reference

Operational reference for MCP Identity Gateway operators and implementers.

For environment variables, see Environment variables reference. For installation, 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 if they were sent.
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.

systemd Commands

The MCP Identity Gateway runs as a systemd service (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

# View logs
journalctl --namespace aembit_mcp_gateway -f

Network requirements

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)

MCP clients authenticate using access tokens (JWTs) from your identity provider (such as Google, Okta, or Microsoft Entra ID). The MCP Identity Gateway validates tokens against the configured Trust Provider and uses streamable HTTP transport (HTTP with server-sent events) for server-to-client streaming.

Outbound

Port	Target	Destination	Purpose
443	Aembit Cloud	https://<tenantId>.aembit.io	Authorization, policy, 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)

Agent Controller dependency

The Agent Controller is a co-deployed Aembit Edge component that registers the MCP Identity Gateway with Aembit Cloud and provides credentials and configuration. The MCP Identity Gateway requires a running Agent Controller to start and operate. For details, see About the Agent Controller.

Logging and events

Log access

View MCP Identity Gateway logs 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"

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.

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, monitor the Gateway logs (journalctl --namespace aembit_mcp_gateway) for connection and authentication visibility.

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.

Available 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)

The component label value is aembit_mcp_gateway.

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.

Note

Aembit plans to add MCP-specific metrics (such as request counts and policy evaluation results) in future releases.

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 - The MCP Identity Gateway runs as a systemd service. See the systemd Commands section for service commands.
• Logging - The MCP Identity Gateway writes logs to journald. Use journalctl --namespace aembit_mcp_gateway to access logs.

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

Supported deployment patterns

In the current beta, the supported pattern is:

• Internet-facing VM Gateway - A Linux VM (for example, in AWS) running the MCP Identity Gateway as a systemd service, with a public DNS name for SaaS AI agents (such as Claude or Gemini).

You can deploy multiple Gateway VMs for different environments (development, staging, production) or for different MCP servers or trust boundaries.

Supported MCP servers

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

In the current beta, 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
• You retain control over deployment, network placement, and data flow

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
• The Gateway isn’t a fully managed multitenant service in the current public beta

See also

• MCP Identity Gateway concepts - Architecture and deployment patterns
• Environment variables - Complete configuration reference