MCP Gateway Metrics

When Tyk Gateway proxies MCP traffic, it makes four MCP-specific fields available as metadata dimension sources in custom OTel metric instruments. Use these dimensions to monitor tool call volumes, track latency per primitive, classify gateway errors, and correlate usage to individual sessions, all through the same observability infrastructure you use for your REST APIs. For an overview of all MCP observability signals, see MCP observability.

MCP Fields Reference

The following fields are derived from the JSON-RPC payload and available as metadata dimension sources in custom metrics.

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`	JSON-RPC error code of a failed request, from Tyk or from the upstream’s response; absent or empty on success	`-32003` / `-33004` (rate limit exceeded), `-32601` (method not found)

All four fields are populated only for MCP APIs. For non-MCP requests they are empty strings, so existing metric instruments are unaffected.

mcp_error_code holds the code of Tyk’s own error, or the code from the upstream MCP server’s JSON-RPC error response. Tyk’s codes depend on the protocol version the request uses. See MCP Error Codes.

Use Cases

The examples below use Tyk’s custom metrics system. Each instrument is a JSON object in the opentelemetry.metrics.api_metrics array in tyk.conf.

MCP Traffic Volume by Method

Track how many requests each JSON-RPC method receives across all MCP APIs. This shows the distribution of tools/call, initialize, resources/read, and other operations.

{
  "name": "tyk.mcp.requests.by_method",
  "type": "counter",
  "description": "Request count broken down by MCP JSON-RPC method",
  "dimensions": [
    { "source": "metadata", "key": "mcp_method",  "label": "mcp_method",  "default": "" },
    { "source": "metadata", "key": "api_id",       "label": "api_id" }
  ]
}

Top Tools by Call Volume

Identify the most frequently invoked tools, useful for cost attribution and optimization. Add api_id to compare usage across multiple MCP backends.

{
  "name": "tyk.mcp.tool_calls.total",
  "type": "counter",
  "description": "MCP tool invocations by tool name and primitive type",
  "dimensions": [
    { "source": "metadata", "key": "mcp_primitive_name", "label": "tool_name",      "default": "" },
    { "source": "metadata", "key": "mcp_primitive_type", "label": "primitive_type", "default": "" },
    { "source": "metadata", "key": "api_id",             "label": "api_id" }
  ],
  "filters": { "methods": ["POST"] }
}

Tool Execution Latency: Upstream

Measure how long the upstream MCP server takes to respond per tool. Use this to identify slow tools and performance regressions; this measurement excludes gateway overhead.

{
  "name": "tyk.mcp.upstream.duration",
  "type": "histogram",
  "description": "Upstream latency per MCP tool",
  "histogram_source": "upstream",
  "histogram_buckets": [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
  "dimensions": [
    { "source": "metadata", "key": "mcp_primitive_name", "label": "tool_name", "default": "" },
    { "source": "metadata", "key": "api_id",             "label": "api_id" }
  ],
  "filters": { "methods": ["POST"] }
}

Total Request Duration with MCP Labels

Measure end-to-end latency (client → gateway → upstream → client) with MCP labels attached. Compare this with upstream latency to quantify gateway overhead.

{
  "name": "tyk.mcp.request.duration",
  "type": "histogram",
  "description": "End-to-end latency per MCP tool",
  "histogram_source": "total",
  "histogram_buckets": [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
  "dimensions": [
    { "source": "metadata", "key": "mcp_primitive_name", "label": "tool_name",   "default": "" },
    { "source": "metadata", "key": "mcp_method",         "label": "mcp_method",  "default": "" },
    { "source": "metadata", "key": "api_id",             "label": "api_id" }
  ]
}

The histogram_source field accepts three values: "upstream" (upstream server latency only), "total" (end-to-end including gateway), and "gateway" (gateway processing time only, excluding upstream). Use "gateway" to isolate gateway overhead.

JSON-RPC Error Classification

Count MCP errors by their JSON-RPC error code. Errors that Tyk raises itself, such as access denied or rate limit exceeded, return an HTTP 4xx or 5xx status. Errors from the upstream MCP server usually return HTTP 200. mcp_error_code records the code in both cases, so it is the reliable way to detect JSON-RPC failures. If you serve clients on more than one protocol version, match both ranges of Tyk’s codes, such as -32003 and -33004.

{
  "name": "tyk.mcp.errors.by_code",
  "type": "counter",
  "description": "MCP JSON-RPC errors by error code and tool",
  "dimensions": [
    { "source": "metadata", "key": "mcp_error_code",     "label": "error_code", "default": "" },
    { "source": "metadata", "key": "mcp_primitive_name", "label": "tool_name",  "default": "" },
    { "source": "metadata", "key": "api_id",             "label": "api_id" }
  ],
  "filters": { "methods": ["POST"] }
}

Filter this instrument in your metrics backend to exclude the empty error_code value (successful requests), or add a status_codes filter if your upstream signals errors via HTTP status.

Per-Consumer Tool Usage

Correlate tool call volume to individual consumers using the alias of the authenticated key. Use this to identify heavy users, debug a specific consumer’s traffic, or allocate costs to teams.

{
  "name": "tyk.mcp.tool_calls.by_consumer",
  "type": "counter",
  "description": "Tool calls per consumer and tool",
  "dimensions": [
    { "source": "session",  "key": "alias",              "label": "consumer",   "default": "unknown" },
    { "source": "metadata", "key": "mcp_primitive_name", "label": "tool_name",  "default": "" },
    { "source": "metadata", "key": "api_id",             "label": "api_id" }
  ],
  "filters": { "methods": ["POST"] }
}

alias is the human-readable key alias set on the API key or OAuth token. If you identify consumers differently (for example, via a JWT claim), use the context source with the appropriate jwt_claims_<name> key instead.

Multi-API MCP Backend Comparison

Compare performance across multiple MCP backends by including api_id alongside tool dimensions. Use this to determine whether the same tool performs differently on different upstream MCP servers.

{
  "name": "tyk.mcp.backend.upstream.duration",
  "type": "histogram",
  "description": "Upstream latency per tool broken down by MCP backend",
  "histogram_source": "upstream",
  "histogram_buckets": [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
  "dimensions": [
    { "source": "metadata", "key": "mcp_primitive_name", "label": "tool_name", "default": "" },
    { "source": "metadata", "key": "api_id",             "label": "api_id" }
  ]
}

Session Efficiency

Measure the ratio of productive tools/call operations to session lifecycle calls (initialize). A low ratio may indicate clients that open sessions but make few tool calls, useful for detecting misconfigured AI clients or idle connections.

{
  "name": "tyk.mcp.method.distribution",
  "type": "counter",
  "description": "Distribution of MCP method types for session efficiency analysis",
  "dimensions": [
    { "source": "metadata", "key": "mcp_method", "label": "mcp_method", "default": "" },
    { "source": "metadata", "key": "api_id",     "label": "api_id" }
  ]
}

To compute efficiency, query your metrics backend for the ratio of tools/call to initialize counts:

# PromQL: ratio of tool calls to session initializations per API
sum by (api_id) (rate(tyk_mcp_method_distribution_total{mcp_method="tools/call"}[5m]))
/
sum by (api_id) (rate(tyk_mcp_method_distribution_total{mcp_method="initialize"}[5m]))

This ratio applies only to 2025-11-25 traffic. Clients using 2026-07-28 have no sessions and never send initialize, so their tool calls raise the ratio without a matching lifecycle call.

Complete Configuration Example

Add the following to tyk.conf. This covers all the instruments needed for the Grafana dashboard panels:

{
  "opentelemetry": {
    "metrics": {
      "enabled": true,
      "api_metrics": [
        {
          "name": "tyk.mcp.requests.total",
          "type": "counter",
          "description": "MCP request count by method, tool, API, and session",
          "dimensions": [
            { "source": "metadata", "key": "mcp_method",         "label": "mcp_method",      "default": "" },
            { "source": "metadata", "key": "mcp_primitive_type", "label": "primitive_type",  "default": "" },
            { "source": "metadata", "key": "mcp_primitive_name", "label": "tool_name",       "default": "" },
            { "source": "metadata", "key": "mcp_error_code",     "label": "error_code",      "default": "" },
            { "source": "metadata", "key": "api_id",             "label": "api_id" },
            { "source": "session",  "key": "alias",              "label": "session",         "default": "unknown" }
          ]
        },
        {
          "name": "tyk.mcp.upstream.duration",
          "type": "histogram",
          "description": "Upstream MCP server latency per tool and API",
          "histogram_source": "upstream",
          "histogram_buckets": [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
          "dimensions": [
            { "source": "metadata", "key": "mcp_primitive_name", "label": "tool_name", "default": "" },
            { "source": "metadata", "key": "api_id",             "label": "api_id" }
          ]
        },
        {
          "name": "tyk.mcp.request.duration",
          "type": "histogram",
          "description": "End-to-end MCP request latency per tool and API",
          "histogram_source": "total",
          "histogram_buckets": [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
          "dimensions": [
            { "source": "metadata", "key": "mcp_primitive_name", "label": "tool_name",  "default": "" },
            { "source": "metadata", "key": "mcp_method",         "label": "mcp_method", "default": "" },
            { "source": "metadata", "key": "api_id",             "label": "api_id" }
          ]
        }
      ]
    }
  }
}

The tyk.mcp.requests.total counter uses 6 dimensions. Keep the total dimension count at 10 or fewer per instrument to stay on the OTel SDK fast path. See Performance Considerations for guidance.

Overview

MCP Gateway

AI Studio

MCP Fields Reference

Use Cases

MCP Traffic Volume by Method

Top Tools by Call Volume

Tool Execution Latency: Upstream

Total Request Duration with MCP Labels

JSON-RPC Error Classification

Per-Consumer Tool Usage

Multi-API MCP Backend Comparison

Session Efficiency

Complete Configuration Example

​MCP Fields Reference

​Use Cases

​MCP Traffic Volume by Method

​Top Tools by Call Volume

​Tool Execution Latency: Upstream

​Total Request Duration with MCP Labels

​JSON-RPC Error Classification

​Per-Consumer Tool Usage

​Multi-API MCP Backend Comparison

​Session Efficiency

​Complete Configuration Example

MCP Fields Reference

Use Cases

MCP Traffic Volume by Method

Top Tools by Call Volume

Tool Execution Latency: Upstream

Total Request Duration with MCP Labels

JSON-RPC Error Classification

Per-Consumer Tool Usage

Multi-API MCP Backend Comparison

Session Efficiency

Complete Configuration Example