GraphOS MCP Server

GetSubgraphMetrics

Read-onlyIdempotent

Top subgraphs/connectors by traffic/health for a graph over a time window, as compact CSV. Columns: start timestamp, end exclusive timestamp, fetch service name, fetch count, fetch latency p50 ms, fetch latency p99 ms, fetch with errors count. Ranked by orderBy descending: default FETCH_COUNT (busiest); FETCH_WITH_ERRORS_COUNT for most error-prone, FETCH_LATENCY_P99_MS for slowest. variantName scopes to one or more variants (omit for all). subgraphName scopes to one or more subgraphs by exact name (omit for all); pattern/substring matching is not supported. clients scopes to the fetches driven by one or more clients; omit clientVersion to match every version of that client, and use GetClientMetrics to discover the names a graph sees. Keep the default resolution of ENTIRE_RANGE for totals and top-N, which gives one row per subgraph ranked over the whole window. DAY/HOUR/MINUTE give one row per subgraph per bucket ranked within each bucket, so a window total then needs a per-subgraph sum plus a limit big enough to cover every bucket; too small a limit silently undercounts. Only HOUR and MINUTE accept a to of now, so use them for bursts in the last 24 hours. Avoid MONTH: it labels buckets by calendar month, not by the requested window.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`to`	Yes	The ending timestamp for the report. Must be in the format: 2025-01-01T08:00:00Z (ISO 8601).
`from`	Yes	The starting timestamp for the report. Must be in the format: 2025-01-01T00:00:00Z (ISO 8601).
`limit`	No	Maximum number of records to return (default: 100, max 10000).
`clients`	No
`graphId`	Yes
`orderBy`	No		FETCH_COUNT
`resolution`	No	The resolution of the time groups for the report. This resolution will affect the range of times that can be used for the 'from' and 'to' timestamps: - For the MINUTE resolution, the total time between 'from' and 'to' must be no more than 1 day, and the 'from' time must be no earlier than 30 days ago. - For the HOUR resolution, the total time between 'from' and 'to' must be no more than 7 days, and the 'from' time must be no earlier than 90 days ago. - For the DAY, MONTH, and ENTIRE_RANGE resolutions, the 'from' time must be no earlier than 549 days ago (approx 18 months), and the 'to' time must be no later than 1 day ago. If these criteria are not met, this will return a REQUEST_INVALID error.	ENTIRE_RANGE
`variantName`	No
`subgraphName`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`data`	No
`errors`	No
`extensions`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed24 schema fields changedSep 18, 2026

addedInput schema / definitions / SubgraphInsightsTimeseriesReportClientFilterInInput / properties / clientName / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
removedInput schema / definitions / SubgraphInsightsTimeseriesReportClientFilterInInput / properties / clientName / type
```
Removed value: -"string"
```
addedInput schema / definitions / SubgraphInsightsTimeseriesReportClientFilterInInput / properties / clientVersion / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
removedInput schema / definitions / SubgraphInsightsTimeseriesReportClientFilterInInput / properties / clientVersion / type
```
Removed value: -"string"
```

addedInput schema / properties / clients / anyOf

Added value: +[
+  {
+    "items": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/SubgraphInsightsTimeseriesReportClientFilterInInput"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

removedInput schema / properties / clients / items

Removed value: -{
-  "oneOf": [
-    {
-      "$ref": "#/definitions/SubgraphInsightsTimeseriesReportClientFilterInInput"
-    },
-    {
-      "type": "null"
-    }
-  ]
-}

removedInput schema / properties / clients / type
```
Removed value: -"array"
```

addedInput schema / properties / limit / anyOf

Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / limit / default
```
Added value: +50
```
removedInput schema / properties / limit / type
```
Removed value: -"integer"
```

removedInput schema / properties / orderBy / $ref

Removed value: -"#/definitions/SubgraphInsightsTimeseriesReportMetric"

addedInput schema / properties / orderBy / anyOf

Added value: +[
+  {
+    "$ref": "#/definitions/SubgraphInsightsTimeseriesReportMetric"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / orderBy / default
```
Added value: +"FETCH_COUNT"
```

removedInput schema / properties / resolution / $ref

Removed value: -"#/definitions/TimeseriesReportResolution"

addedInput schema / properties / resolution / anyOf

Added value: +[
+  {
+    "$ref": "#/definitions/TimeseriesReportResolution"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / resolution / default
```
Added value: +"ENTIRE_RANGE"
```

addedInput schema / properties / subgraphName / anyOf

Added value: +[
+  {
+    "items": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

removedInput schema / properties / subgraphName / items

Removed value: -{
-  "oneOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ]
-}

removedInput schema / properties / subgraphName / type
```
Removed value: -"array"
```

addedInput schema / properties / variantName / anyOf

Added value: +[
+  {
+    "items": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

removedInput schema / properties / variantName / items

Removed value: -{
-  "oneOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ]
-}

removedInput schema / properties / variantName / type
```
Removed value: -"array"
```

addedOutput schema / properties / data / properties / graph / anyOf

Added value: +[
+  {
+    "properties": {
+      "subgraphInsightsTimeseriesReport": {
+        "description": " Returns a timeseries of subgraph and connector fetch metrics across a specified time range for this graph. Each\nrequest from the router to a subgraph or connector service is counted as a fetch. A single GraphQL operation can\nresult in multiple fetches, depending on the operation shape and query plan. This will return specified metrics (fetch\ncount, avg latency, etc.) grouped by time and the specified dimensions (fetch service ID, fetch service name, client\nname, etc.). This API is rate limited and only allows a small number of requests per minute, and will return a\nRATE_LIMIT_EXCEEDED error if too many requests are made for a graph. If a request to this field times out, we\nrecommend that you try a shorter time range or fewer dimensions.",
+        "properties": {
+          "csv": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "A CSV representation of the results. This includes a header and rows that have a column for start and end timestamp and all requested dimensions and metrics."
+          }
+        },
+        "type": "object"
+      }
+    },
+    "required": [
+      "subgraphInsightsTimeseriesReport"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / data / properties / graph / oneOf

Removed value: -[
-  {
-    "properties": {
-      "subgraphInsightsTimeseriesReport": {
-        "description": " Returns a timeseries of subgraph and connector fetch metrics across a specified time range for this graph. Each\nrequest from the router to a subgraph or connector service is counted as a fetch. A single GraphQL operation can\nresult in multiple fetches, depending on the operation shape and query plan. This will return specified metrics (fetch\ncount, avg latency, etc.) grouped by time and the specified dimensions (fetch service ID, fetch service name, client\nname, etc.). This API is rate limited and only allows a small number of requests per minute, and will return a\nRATE_LIMIT_EXCEEDED error if too many requests are made for a graph. If a request to this field times out, we\nrecommend that you try a shorter time range or fewer dimensions.",
-        "properties": {
-          "csv": {
-            "description": "A CSV representation of the results. This includes a header and rows that have a column for start and end timestamp and all requested dimensions and metrics.",
-            "oneOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          }
-        },
-        "type": "object"
-      }
-    },
-    "required": [
-      "subgraphInsightsTimeseriesReport"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]

Changed4 schema fields changedSep 11, 2026

addedInput schema / definitions / SubgraphInsightsTimeseriesReportClientFilterInInput

Added value: +{
+  "description": "The named type and version of the clients to include or exclude in the subgraph and connector timeseries report.",
+  "properties": {
+    "clientName": {
+      "description": "The client name.",
+      "type": "string"
+    },
+    "clientVersion": {
+      "description": "The client version.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

addedInput schema / definitions / TimeseriesReportResolution

Added value: +{
+  "description": "The size of each time bucket in a timeseries report.\n\nValues:\nDAY: One-day buckets.\nENTIRE_RANGE: Single bucket containing the entire time range.\nHOUR: One-hour buckets.\nMINUTE: One-minute buckets.\nMONTH: One-month buckets.",
+  "enum": [
+    "DAY",
+    "ENTIRE_RANGE",
+    "HOUR",
+    "MINUTE",
+    "MONTH"
+  ],
+  "type": "string"
+}

addedInput schema / properties / clients

Added value: +{
+  "items": {
+    "oneOf": [
+      {
+        "$ref": "#/definitions/SubgraphInsightsTimeseriesReportClientFilterInInput"
+      },
+      {
+        "type": "null"
+      }
+    ]
+  },
+  "type": "array"
+}

addedInput schema / properties / resolution

Added value: +{
+  "$ref": "#/definitions/TimeseriesReportResolution",
+  "description": "The resolution of the time groups for the report. This resolution will affect the range of times that can be used for the 'from' and\n'to' timestamps:\n- For the MINUTE resolution, the total time between 'from' and 'to' must be no more than 1 day, and the 'from' time must be no earlier than 30 days ago.\n- For the HOUR resolution, the total time between 'from' and 'to' must be no more than 7 days, and the 'from' time must be no earlier than 90 days ago.\n- For the DAY, MONTH, and ENTIRE_RANGE resolutions, the 'from' time must be no earlier than 549 days ago (approx 18 months), and the 'to' time must be no later than 1 day ago.\nIf these criteria are not met, this will return a REQUEST_INVALID error."
+}

Changed1 schema field changedAug 4, 2026

addedInput schema / properties / subgraphName

Added value: +{
+  "items": {
+    "oneOf": [
+      {
+        "type": "string"
+      },
+      {
+        "type": "null"
+      }
+    ]
+  },
+  "type": "array"
+}

First observedAug 3, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety burden is covered. The description goes far beyond annotations by disclosing output columns, CSV formatting, ranking/orderBy semantics, exact-match-only subgraph filtering, silent undercounting when limit is too small, and MONTH's calendar-bucket behavior. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but nearly every sentence adds a needed caveat or parameter semantic, and the critical output columns are front-loaded. It could be slightly improved with structured bullets or shorter sentences, but given the tool has 9 parameters and several non-obvious resolution behaviors, the length is largely justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a high-complexity analytics tool, the description covers the essential invocation decisions: default resolution, ranking metrics, scoping filters, client discovery via a sibling tool, and resolution-specific constraints like the now limitation and monthly bucketing. The required graphId and from/to timestamp remain schema-obvious, and an output schema exists, so nothing critical is missing for correct selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 44%, so the description carries most of the parameter-meaning burden, and it does so thoroughly. It explains orderBy values and defaults, variantName scoping, subgraphName exact-match limitations, clients/clientVersion behavior, resolution bucket semantics, and the limit undercount risk. This is strong compensation for the sparse schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource (top subgraphs/connectors by traffic/health for a graph), the action (Get), and the response format (compact CSV with explicit columns). It even differentiates itself from the sibling GetClientMetrics by positioning that tool as the way to discover client names, so an agent can distinguish this tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides unusually explicit usage guidance: keep ENTIRE_RANGE for totals and top-N, use DAY/HOUR/MINUTE per-bucket with a caveat about summing and limit, use HOUR/MINUTE for bursts in the last 24 hours, and avoid MONTH because of calendar-month labeling. It also directs the agent to GetClientMetrics when client names are unknown. This is model-quality routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All GraphOS MCP Server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?