> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Metrics: Distribution Examples

> Distribution query examples for Gateway MCP metrics API

## Distribution queries

Aggregated snapshots of MCP metrics over a time window. Every example below posts JSON to:

```
POST https://{your_control_plane_url}/api/svc/v1/llm-gateway/metrics/query
```

with `Authorization: Bearer <your_api_key>` and `Content-Type: application/json`. To keep the snippets short, only the JSON body is shown; the wrapper is identical to the [Overview Quick Start](/docs/ai-gateway/fetch-mcp-metrics#quick-start).

<Note>
  MCP metrics include **all JSON-RPC methods** by default. Many of the examples below pin the tool-call subset with `{"fieldName": "method", "operator": "IN", "value": ["tools/call"]}` so `toolName` is populated.
</Note>

<AccordionGroup>
  <Accordion title="Top servers by request count">
    Count requests per server, alongside p99 latency:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "mcpServerName"},
            {"type": "p99", "column": "latencyMs"}
        ],
        "groupBy": ["mcpServerName"]
    }
    ```
  </Accordion>

  <Accordion title="Tool calls grouped by tool name">
    Restrict to `tools/call` and group by `toolName`:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "toolName"}
        ],
        "groupBy": ["toolName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Method distribution per server">
    Traffic mix per server (initialize / tools/list / tools/call / ...):

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "method"}
        ],
        "groupBy": ["mcpServerName", "method"]
    }
    ```
  </Accordion>

  <Accordion title="Latency percentiles by tool">
    p50, p90, and p99 latency per tool:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "p50", "column": "latencyMs"},
            {"type": "p90", "column": "latencyMs"},
            {"type": "p99", "column": "latencyMs"}
        ],
        "groupBy": ["toolName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Distinct tools per server">
    How many unique tools each server exposed:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "countDistinct", "column": "toolName"}
        ],
        "groupBy": ["mcpServerName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Exclude internal tools">
    Count tool calls excluding internal/debug tools using `NOT_IN`:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "toolName"}
        ],
        "groupBy": ["toolName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]},
            {"fieldName": "toolName", "operator": "NOT_IN", "value": ["internal-debug", "healthcheck", "echo"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="High-latency tool calls">
    Find slow tool calls (above 5 seconds):

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "toolName"}
        ],
        "groupBy": ["mcpServerName", "toolName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]},
            {"fieldName": "latencyMs", "operator": "GREATER_THAN", "value": 5000}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Group by metadata">
    Tool-call counts per metadata key:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "toolName"}
        ],
        "groupBy": ["toolName", "metadata.environment"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Filter by team">
    Tool-call activity scoped to a team:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "toolName"}
        ],
        "groupBy": ["mcpServerName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]},
            {"fieldName": "team", "operator": "ARRAY_HAS_ANY", "value": ["team-alpha"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Complex filter combination">
    Tool-call traffic on a known list of servers, latency window, scoped to a team:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "toolName"},
            {"type": "p99", "column": "latencyMs"}
        ],
        "groupBy": ["mcpServerName", "toolName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]},
            {"fieldName": "mcpServerName", "operator": "IN", "value": ["github-mcp", "atlassian-mcp"]},
            {"fieldName": "latencyMs", "operator": "BETWEEN", "value": [100, 10000]},
            {"fieldName": "team", "operator": "ARRAY_HAS_ANY", "value": ["team-alpha"]}
        ]
    }
    ```
  </Accordion>
</AccordionGroup>