> ## Documentation Index
> Fetch the complete documentation index at: https://tyk-tt17611-iam-auth.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Gateway Observability Overview

> An overview of the observability signals Tyk Gateway emits for MCP traffic: metrics dimensions, structured access log fields, distributed tracing, and the Dashboard analytics page.

Tyk Gateway emits three categories of observability signal for MCP traffic: custom metrics dimensions, structured access log fields, and distributed tracing spans. All three are enriched with the same set of MCP-specific fields, letting you monitor tool call volumes, track latency per primitive, classify errors, and correlate usage across sessions, through the same observability infrastructure you use for your REST APIs.

## Prerequisites

OpenTelemetry must be enabled on your Tyk Gateway. See [OpenTelemetry configuration](/api-management/traces) for setup instructions.

## MCP fields

The following fields are derived from the JSON-RPC payload on each MCP request. They appear across both signal types.

| Field                | Description                                                               | Example values                                              |
| -------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `mcp_method`         | JSON-RPC method invoked                                                   | `tools/call`, `initialize`, `resources/read`, `prompts/get` |
| `mcp_primitive_type` | MCP primitive category                                                    | `tool`, `resource`, `prompt`                                |
| `mcp_primitive_name` | Name of the specific tool, resource, or prompt                            | `get_current_weather`, `search_documents`                   |
| `mcp_error_code`     | Gateway-mapped JSON-RPC error code on failure; absent or empty on success | `-32001`, `-32002`, `-32003`                                |

All four fields are populated only for MCP requests. For non-MCP requests the fields are empty or absent, so existing metric instruments and log templates are unaffected.

## Observability Signals

| Signal                  | What it covers                                                                                             | Doc                                                           |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **Metrics**             | Custom OTel metric instruments with MCP dimensions for counters and histograms                             | [MCP metrics](/ai-management/mcp-gateway/mcp-metrics)         |
| **Access logs**         | Structured per-request log records with MCP fields included when non-empty                                 | [MCP access logs](/ai-management/mcp-gateway/mcp-access-logs) |
| **Distributed tracing** | Spans stamped with MCP attributes, with trace context carried in the JSON-RPC body as well as HTTP headers | [Distributed tracing](#distributed-tracing), below            |

## Distributed tracing

When [OpenTelemetry tracing](/api-management/traces) is enabled, Tyk stamps every MCP request's span with MCP-specific attributes and propagates trace context over both the standard HTTP `traceparent` header and the MCP JSON-RPC body, so a trace stays intact even through MCP clients or servers that don't preserve custom headers.

### Span attributes

| Attribute                                                  | Description                                                                                                                        |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `mcp.method.name`                                          | JSON-RPC method invoked                                                                                                            |
| `mcp.tool.name`, `mcp.resource.name`, or `mcp.prompt.name` | Name of the specific primitive, keyed by its type                                                                                  |
| `mcp.trace_source`                                         | Which channel(s) carried the inbound trace context: `none`, `header`, `meta` (the JSON-RPC body's `params._meta` field), or `both` |

### Trace context propagation

Not every MCP client library preserves custom HTTP headers, so the MCP specification allows a client to carry its W3C trace context inside the JSON-RPC request body instead, under `params._meta`. Tyk reads both channels, in a configurable, first-match-wins order set under `opentelemetry.traces.mcp.read_sources` in the gateway config. The default order, the HTTP header first and then the body, matches Tyk's existing header-based behavior, so tracing works unchanged if you don't set this.

Whichever channel Tyk resolves the inbound trace context from, it writes its own current trace context back into the outbound JSON-RPC body before forwarding the request, so a downstream MCP server that reads the body rather than the header joins the same trace. This is the body-channel equivalent of the `traceparent` header Tyk already injects on ordinary proxied requests.

<Note>
  This applies to every MCP proxy, whether it fronts a remote MCP server or is [generated directly from a Tyk-managed REST API](/ai-management/mcps/api-to-mcp). For the latter, the call into the paired REST API is dispatched through Tyk's standard internal request handling, so when tracing is enabled the trace continues into the source API's own request handling, and its own upstream call, without further configuration.
</Note>

## Dashboard Analytics

Alongside these OpenTelemetry signals, Tyk Dashboard has a dedicated **Activity by MCP** analytics page, covering proxy-level and primitive-level traffic and error charts. See [MCP Analytics](/ai-management/mcp-gateway/mcp-analytics).

<Note>
  For an MCP proxy [generated directly from a Tyk-managed REST API](/ai-management/mcps/api-to-mcp), these charts only ever reflect the proxy's own traffic. The internal call Tyk makes into the paired source REST API on every `tools/call` produces its own analytics record, but that record is never picked up as MCP traffic. It appears instead in the source API's own traffic view, indistinguishable from a direct hit on that API. See [MCP access logs](/ai-management/mcp-gateway/mcp-access-logs#access-logs-when-the-proxy-fronts-a-tyk-managed-rest-api) for the same pattern at the access log level.
</Note>