Red Hat Connectivity Link

MCP gateway references for Observability

Understand the MCP gateway Observability options by using the references for descriptions of each field and the source and type of information that each provides.

MCP gateway router spans for observability

When enabled, the Model Context Protocol (MCP) router, ext_proc, emits trace spans for every request and can export structured logs through Red Hat build of OpenTelemetry.

With traces, you can see one continuous timeline of traffic events across different pods and services. This can help you identify bottlenecks and conduct root-cause analysis.

Spans show one part of the journey. The attributes attached to those spans give you the contextual metadata that you need to have searchable and meaningful traces. The attributes are simple key: value pairs attached to each span.

The MCP gateway uses the following router spans:

Table 25. MCP router spans
Span	When	Description
`mcp-router.process`	Every `ext_proc` stream	Root span. Starts when request headers arrive, ends after response headers are processed.
`mcp-router.route-decision`	The request body is parsed	Routing decision: `tool-call` versus pass-through to broker.
`mcp-router.broker-passthrough`	Non-`tool-call` requests	Pass-through to broker: `initialize`, `tools/list`, `notifications`. No child spans means the broker is not instrumented.
`mcp-router.tool-call`	`tools/call` requests	Full tool call handling including session and server resolution.
`mcp-router.broker.get-server-info`	Inside `tool-call`	Queries the broker to resolve which backend MCP server owns the tool.
`mcp-router.session-cache.get`	Inside `tool-call`	Queries the session cache to look up an existing backend session.
`mcp-router.session-init`	Cache miss during `tool-call`	Hairpin `initialize` request through the gateway to the backend MCP server.
`mcp-router.session-cache.store`	After `session-init`	Persists the new backend session in the session cache.

The attributes in the following tables use OpenTelemetry MCP Semantic Conventions.

Table 26. MCP router root span, `mcp-router.process`, attributes
Attribute	Source	Description
`http.method`	`:method` header	HTTP method, `POST`
`http.path`	`:path` header	Request path, `/mcp`
`http.request_id`	`x-request-id` header	Envoy request ID
`mcp.method.name`	JSON-RPC `method` field	MCP method, `initialize`, `tools/call`, `tools/list`, and so on
`gen_ai.tool.name`	JSON-RPC `params.name`	Tool name, only for `tools/call`
`jsonrpc.request.id`	JSON-RPC `id` field	JSON-RPC request ID
`jsonrpc.protocol.version`	JSON-RPC `jsonrpc` field	Always "2.0"
`gen_ai.operation.name`	JSON-RPC `method` field	Same as `mcp.method.name`
`mcp.session.id`	`mcp-session-id` header	Gateway session ID
`client.address`	`x-forwarded-for` header	Client IP address
`http.status_code`	`:status` response header	Response status code

Table 27. MCP route decision span, `mcp-router.route-decision`, attributes
Attribute	Description
`mcp.method.name`	MCP method
`mcp.route`	Routing decision: `tool-call`, `broker`, or `elicitation-response`

Table 28. MCP tool call span, `mcp-router.tool-call`, attributes
Attribute	Description
`gen_ai.tool.name`	Tool name from the request
`mcp.session.id`	Gateway session ID
`mcp.server`	Resolved backend server name
`mcp.server.hostname`	Resolved backend server hostname

Table 29. MCP error attributes
Attribute	Description
`error.type`	Error classification, such as `tool_not_found`, `missing_tool_name`, `invalid_session`, `session_cache_error`, `session_init_error`, `marshal_error`, `path_parse_error`
`error_source`	Component that generated the error, such as`ext-proc`
`http.status_code`	HTTP status code returned

When there is an error, spans include these attributes.

Custom audit log provider fields

Understand the MCP gateway audit log fields by using the reference table for descriptions of each field and the source and type of information that each provides.

Table 30. Audit log fields
Field	Source	Description
`timestamp`	`%START_TIME%`	The start time of the session
`method`	`%REQ(:METHOD)%`	The HTTP method of the request, for example, `GET`, `POST`
`path`	`%REQ(:PATH)%`	The HTTP request path, including any query parameters
`response_code`	`%RESPONSE_CODE%`	The HTTP response status code returned to the client
`request_id`	`%REQ(X-REQUEST-ID)%`	Unique string identifier for tracking the end-to-end request lifecycle
`traceparent`	`%REQ(TRACEPARENT)%`	W3C Trace Context for cross-system correlation
`mcp_method`	`%REQ(X-MCP-METHOD)%`	MCP method, such as `tools/call`, `tools/list`, `initialize`, and so on
`mcp_tool_name`	`%REQ(X-MCP-TOOLNAME)%`	Tool name after prefix stripping
`mcp_server_name`	`%REQ(X-MCP-SERVERNAME)%`	Backend MCP server name
`mcp_session_id`	`%REQ(MCP-SESSION-ID)%`	MCP session identifier
`mcp_user_id`	`%REQ(X-AUTH-IDENTITY)%`	Authenticated user identity, injected by an `AuthPolicy` custom resource
`duration_ms`	`%DURATION%`	Total duration of the request in milliseconds, from the start time to the last byte sent
`upstream_host`	`%UPSTREAM_HOST%`	The upstream host IP address and port that handled the request
`bytes_sent`	`%BYTES_SENT%`	Body bytes sent downstream to the client
`bytes_received`	`%BYTES_RECEIVED%`	Body bytes received upstream from the client