Troubleshoot MCP and AI IAM access

When an AI agent or MCP client can’t reach an MCP server, the failure can originate in the or in .

Use this guide to:

Investigate failures across the three Aembit reporting surfaces
Look up specific failure modes and resolutions
Monitor proactively for new failures

Step-by-step investigation

Three reporting surfaces in the Aembit Tenant cover MCP and AI IAM activity. Consult them in this order:

Access Authorization Events

Use to confirm whether the request reached Aembit Cloud and how Access Policy evaluation resolved.

In the Aembit Tenant, click Reporting. The Access Authorization Events tab is selected by default.
Set Timespan to a range that covers the failure.
Set Severity to Error.
View the event type. It tells you which stage of authorization failed and what to check first. See the Error condition matrix for specific resolutions.
- access.request - The request reached Aembit Cloud and a Client Workload match was attempted. An error means no Client Workload matched. Check that the Client Workload’s redirect URI matches the MCP client’s callback URL, and that the resource URL matches a registered Server Workload.
- access.authorization - A Client Workload and Access Policy matched, and Aembit Cloud evaluated Trust Providers, Access Conditions, and the Server Workload selection. An error means one of those checks failed. Inspect the result field on each Trust Provider, Access Condition, and Server Workload entry in the event to see which rejected the request.
- access.discovery - Aembit Cloud searched for matching workloads or policies and either found none or found multiple.
- access.credential - Aembit attempted to retrieve a credential from a Credential Provider for the matched Server Workload. An error means the Credential Provider didn’t return a usable credential. Check the reason field—Token expired means the user needs to reauthenticate; other reasons describe upstream identity-provider errors.

Workload Events

Use when Access Authorization Events show a successful authorization but the MCP client still received an error. See what the MCP Identity Gateway forwarded, modified, or rejected.

Open Workload Events and filter by the same timespan and Application Protocol = MCP.
If you know which user reported the failure, apply the User (MCP App Protocol only) filter. MCP Workload Events record user identity as application.mcp.userId for flows that involve a human identity.
Narrow by matched Client Workload, Server Workload, or mcpSessionId to isolate a specific session.
Look for mcp.response events where outcome.result is Error. The outcome.reason field describes the failure source.

MCP Authorization Tracing

Use when the static event record is ambiguous and you can reproduce the failure on demand.

Ask the user to retry the failing operation.
Watch MCP Authorization Tracing for the resource URL, redirect URI, and Access Policy match outcome.

Error condition matrix

The following matrix maps MCP failure modes to the event that surfaces them and how to remediate.

Failure	Where it surfaces	What you’ll see	Resolution
Client Workload redirect URI mismatch	`access.request` event, severity Error	No matching Client Workload, or the redirect URI in the request does not match any registered Client Workload.	Verify the redirect URI on the Client Workload matches the MCP client’s callback URL exactly. See Redirect URI mismatch.
Server Workload mismatch	`access.request` event, severity Error	Resource URL in the request does not match any registered Server Workload.	Verify the resource URL on the Server Workload matches the MCP server URL the client is trying to reach.
Trust Provider attestation failure	`access.authorization` event, severity Error	Trust Provider `result` is `Unauthorized` with a `reason` such as `MatchRuleFailed` or `InvalidSignature`.	Confirm the identity token’s claims match the Trust Provider match rules. See Authorization failure.
Credential Provider failure	`access.credential` event, severity Error	Credential Provider `result` is not `Retrieved`. Common reasons include `Token expired` and upstream identity-provider errors.	The expired-credential explanation in the event now describes which token expired and at which step. Re-authenticate the user or refresh the credential.
No matching Client Workload	`access.discovery` event, severity Error	Discovery enumerates the Client Workloads considered for the Gateway-to-Server Access Policy and indicates that none matched.	Verify the Client Workload identifying the Gateway is present in the Gateway-to-Server Access Policy.
No matching Server Workload	`access.discovery` event, severity Error	Discovery enumerates the Server Workloads considered and indicates that none matched the target MCP server.	Verify the Server Workload for the target MCP server exists and is included in the Gateway-to-Server Access Policy.
Trust Provider attestation failure	`access.authorization` event, severity Error	Same shape as the Client-to-Gateway Access Policy Trust Provider failure, but with the Gateway-to-Server Access Policy context.	Confirm the Aembit-issued JWT presented by the Gateway is valid for the target MCP server.
Wrong-audience JWT presented to the Gateway	`mcp.response` Workload Event, severity Error	Gateway rejects the request because the access token’s `aud` claim does not match the Gateway URL.	Reissue the access token with the correct audience. Check the Client Workload’s resource configuration.
No assigned MCP servers	`mcp.response` Workload Event, severity Error	The Gateway received a request but has no Server Workloads assigned in the matched Gateway-to-Server Access Policy.	Add the target Server Workload to the Gateway-to-Server Access Policy.
MCP server unreachable	`mcp.response` Workload Event, severity Error	The Gateway could not connect to the upstream MCP server. The reason describes the network or TLS failure.	Verify network reachability from the Gateway to the MCP server and confirm any required TLS configuration.
Non-2xx response from the MCP server	`mcp.response` Workload Event, severity Error	The MCP server returned a non-2xx HTTP status code. The reason includes the status code and any upstream error detail.	Investigate the MCP server logs for the cause of the upstream error.
`tools/call` failure	`mcp.response` Workload Event, severity Error	The Gateway forwarded the tool invocation, and the MCP server returned a tool-call error.	Inspect the upstream MCP server response. The Gateway records the failure with Error severity so SIEM alerting can trigger on it.

Match events across surfaces

To match Access Authorization Events with Workload Events for the same activity, use these shared IDs:

Context ID to match Access Authorization Events from the same evaluation.
Connection ID to match Workload Events on the same connection.
MCP Session ID to match Workload Events across multiple connections in the same MCP session.

Identifier	Where it appears	What it identifies
Event ID	All events (`meta.eventId`)	A single event record. Unique per event. Useful when sharing a specific event with Aembit support.
Context ID	Access Authorization Events (`meta.contextId`)	An authorization evaluation context. The `access.request` and `access.authorization` events for the same evaluation share a Context ID.
Connection ID	Workload Events (`meta.connectionId`)	A single TCP or HTTP connection through Agent Proxy or the MCP Identity Gateway. All request and response events for the same connection share a Connection ID.
MCP Session ID	Workload Events (`application.mcp.mcpSessionId`)	The MCP protocol session between an MCP client and the Gateway. Shared across requests and responses in the same session. Useful when an MCP client reconnects mid-session.
User identity	MCP Workload Events (`application.mcp.userId`)	The user identity associated with the event for MCP flows that involve a human identity, such as MCP Authorization Server flows. Use this with the User (MCP App Protocol only) filter to scope investigation to a single user.

Monitor for failures

Once you know what MCP and AI IAM failures look like, you can monitor for them proactively instead of waiting for a user to report a problem. Forward Aembit events to any destination you already operate—a SIEM, an S3 bucket, or another log store—using Log Streams.

What to alert on

Any Access Authorization Event with severity Error. This includes Trust Provider failures, Credential Provider failures, and access.discovery events that found no match.
Any Workload Event with severity Error and event type mcp.response. This catches Gateway-side rejections, upstream MCP server failures, and tool-call failures.

Severity levels

Info - Normal authorization or traffic event. No action required.
Warning - Reserved for non-failure conditions that still merit review.
Error - A real failure. Trust Provider attestation failures and tool-call failures now emit at Error severity in MCP flows, so you can use Error as a reliable alerting threshold.

Event volume

The MCP Identity Gateway emits two events per request on the simple path and 2 + (2 × N) events on fanout requests such as tools/list and initialize, where N is the number of assigned MCP servers. Plan retention and alerting thresholds accordingly.