[github-actions]

agentgateway/agentgateway#4182 — feat: report MCP request outcomes in metrics

Docs versions: standalone/main, kubernetes/main

What changes for users: The agentgateway_mcp_requests_total metric now has an outcome label. Dashboards and alerts can distinguish success, tool_error, protocol_error, gateway_error, and unknown, including tool errors that still return HTTP 200.

What the docs now say: The Kubernetes data plane metrics reference now documents the new outcome label and adds a PromQL query that groups MCP tool calls by server, resource, and outcome. The standalone metrics reference also mentions agentgateway_mcp_requests_total, but it was not in the authorized target list, so this report names that gap.

Not verified: No cluster; the metrics query and configuration are unrun.

How agentgateway-4182 was drafted, and what was not verified

• Code PR: feat: report MCP request outcomes in metrics agentgateway#4182
• Code issue: none linked
• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main and kubernetes/main; documented in the development tree, which is where unreleased changes go
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Add the MCP outcome label to the data plane metrics reference and PromQL examples.
• Did: Documented the label and PromQL grouping in assets/agw-docs/pages/observability/metrics/dataplane.md, and left the standalone metrics reference for reviewer follow-up.

Why a documentation change is necessary

The pull request adds an outcome label to the MCPCall metric labels in crates/agentgateway/src/telemetry/metrics.rs and sets the value from request status, JSON-RPC errors, and tools/call results in crates/agentgateway/src/telemetry/log.rs. The data plane metrics page already lists agentgateway_mcp_requests_total and includes an MCP tool-call PromQL query, so a reader looking for MCP metric labels would not discover the new outcome dimension. The diff's tests define the expected values: success, tool_error, protocol_error, gateway_error, and unknown.

What changed on disk

assets/agw-docs/pages/observability/metrics/dataplane.md: Added a main-only note for the outcome label on agentgateway_mcp_requests_total, and added a main-only PromQL query for MCP tool call outcomes by tool.

How to verify this change

1. Send MCP tools/call traffic through an existing agentgateway MCP route, including at least one tool response with "isError": true.

2. Query the proxy metrics endpoint.

   curl http://localhost:15020/metrics | grep 'agentgateway_mcp_requests_total.*outcome='

3. The output includes agentgateway_mcp_requests_total series with the outcome label. A tool error has outcome="tool_error", and a successful call has outcome="success".

What was not verified

• The configuration is unrun; no MCP route or traffic was applied in this sandbox.
• The PromQL query was not run against Prometheus.
• Internal links are unchecked; Hugo was not run.
• content/docs/standalone/main/documentation/observability/metrics/reference.md also lists agentgateway_mcp_requests_total, but the work-list did not authorize editing that page.

How the pages were chosen (triage report)

Draft a documentation change

agentgateway/agentgateway#4182 — feat: report MCP request outcomes in metrics

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, kubernetes/main
• Summary (read from the body): Some of my tool calls were failing while the HTTP response said 200 OK. That means the request was delivered successfully, but the tool itself may have returned an error.
• Not tested: no cluster was available, so every command in this diff is unrun

Release notes

This pull request also adds its release-note entries:

• content/docs/kubernetes/main/release-notes/release-notes.md: MCP request outcome metric label (feature, in a new 1.8 section)
• content/docs/standalone/main/release-notes/release-notes.md: MCP request outcome metric label (feature, in a new 1.8 section)

Check these release-note links and names. Each note is on its page, but a link may not reach the drafted content there, or a name may belong to the other mode:

• content/docs/kubernetes/main/release-notes/release-notes.md: feat: report MCP request outcomes in metrics agentgateway#4182's note names tool_error, which content/docs/standalone/main mentions and content/docs/kubernetes/main does not. Check that this tree's readers can set it, or word the note for this mode.
• content/docs/standalone/main/release-notes/release-notes.md: feat: report MCP request outcomes in metrics agentgateway#4182's note names protocol_error, which content/docs/kubernetes/main mentions and content/docs/standalone/main does not. Check that this tree's readers can set it, or word the note for this mode.
• content/docs/standalone/main/release-notes/release-notes.md: feat: report MCP request outcomes in metrics agentgateway#4182's note names gateway_error, which content/docs/kubernetes/main mentions and content/docs/standalone/main does not. Check that this tree's readers can set it, or word the note for this mode.

Draft branch: pr-tracker-draft-agentgateway-4182

[cloudflare-workers-and-pages]

Deploying agentproxy with    Cloudflare Pages

Latest commit:	6b52db9
Status:	⚡️  Build in progress...

View logs

[kristin-kronstain-brown]

Moved this PR's release-notes entry to the combined release-notes PR, #1482, so the draft PRs stop conflicting on the release-notes pages. Review or change the entry there.