feat(mcp): add structured tool output behind mcp.output_schema flag - #3136
Draft
asoorm wants to merge 5 commits into
Draft
feat(mcp): add structured tool output behind mcp.output_schema flag#3136asoorm wants to merge 5 commits into
asoorm wants to merge 5 commits into
Conversation
Implements MCP structured tool output (spec revision 2025-06-18) in the router MCP server, opt-in via mcp.output_schema.enabled (default false, env MCP_OUTPUT_SCHEMA_ENABLED): - every tool generated from a GraphQL operation declares an outputSchema derived from the operation's selection set (aliases, fragments, @skip/@include/@defer, abstract types, custom scalars); schemas are deliberately permissive so a valid response is never rejected, and a build failure only degrades the tool to schema-less registration - successful tool results additionally carry the response as structuredContent mirroring the text content (also for execute_graphql, which declares no output schema) Behavioral change, applied unconditionally (not gated by the flag): a response body that cannot be a GraphQL response (non-JSON, empty, or literal null) now returns IsError: true instead of a success-looking text result. Spec-valid GraphQL error envelopes and partial results keep their existing IsError semantics. Opt-in because output schemas inflate tools/list payloads and structured content roughly doubles result sizes, both of which consume MCP client context budgets.
Adds a Structured Tool Output section to the MCP tools page and the output_schema.enabled key to the configuration reference (options table, environment variables, full example), including the tools/list and result payload-size tradeoff.
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Router-nonroot image scan passed✅ No security vulnerabilities found in image: |
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
WalkthroughAdds the ChangesMCP structured output
Estimated code review effort: 4 (Complex) | ~60 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
Comment |
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #3136 +/- ##
==========================================
+ Coverage 62.37% 62.58% +0.20%
==========================================
Files 262 263 +1
Lines 31003 31232 +229
==========================================
+ Hits 19337 19545 +208
- Misses 10158 10165 +7
- Partials 1508 1522 +14
🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
router/pkg/mcpserver/server.go (1)
1024-1030: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick winCap the upstream body echoed into the tool result.
The error branch interpolates the whole response body into the tool result text. A proxy error page or an HTML gateway response can be large, and the result is sent to the AI model, where it consumes the context window. Truncate the body before formatting it.
♻️ Proposed truncation
var graphqlResponse *GraphQLResponse if err := json.Unmarshal(body, &graphqlResponse); err != nil || graphqlResponse == nil { + const maxEchoedBodyBytes = 2048 + echoedBody := body + if len(echoedBody) > maxEchoedBodyBytes { + echoedBody = append(echoedBody[:maxEchoedBodyBytes:maxEchoedBodyBytes], []byte("... (truncated)")...) + } return &mcp.CallToolResult{ - Content: []mcp.Content{&mcp.TextContent{Text: fmt.Sprintf("Response error: unexpected response from GraphQL endpoint: %s", body)}}, + Content: []mcp.Content{&mcp.TextContent{Text: fmt.Sprintf("Response error: unexpected response from GraphQL endpoint: %s", echoedBody)}}, IsError: true, }, nil }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@router/pkg/mcpserver/server.go` around lines 1024 - 1030, Cap the response body before interpolating it into the error text in the GraphQL response parsing branch around json.Unmarshal. Truncate oversized body content to a bounded length while preserving the existing unexpected-response error and IsError behavior, and use the truncated value in fmt.Sprintf rather than the full body.docs-website/router/mcp/tools.mdx (1)
305-305: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winSplit the packed sentences and remove the filler word.
Three places pack multiple distinct facts into one sentence. The documentation guidelines require short declarative sentences, structured lists for multiple distinct items, and no filler words. Line 321 also uses "just", which the guidelines list as a filler word to avoid.
✏️ Proposed rewrite
-This lets MCP clients know a tool's response shape ahead of time, validate results against the declared schema, and bind results to typed code instead of re-parsing a text blob. +MCP clients use the output schema to: + +- Know the response shape before calling the tool. +- Validate results against the declared schema. +- Bind results to typed code instead of parsing the text content.<Warning> - Output schemas are included in every `tools/list` response, which grows with the size of your operations' selection - sets, and structured content roughly doubles the size of each successful tool result because the response is carried - both as text and as structured content. Both consume the AI model's context window. Keep this feature disabled (the - default) unless your MCP clients consume output schemas or structured content. + This feature increases payload sizes in two ways. Every `tools/list` response carries the output schemas, which grow + with the size of your operations' selection sets. Every successful tool result carries the response twice, as text and + as structured content. Both consume the AI model's context window. Keep this feature disabled (the default) unless + your MCP clients consume output schemas or structured content. </Warning>-The generated schemas are intentionally permissive: they describe what the router returns without over-constraining it, so a valid GraphQL response is never rejected by a client validating against the schema. Fields behind `@skip`, `@include`, or `@defer` directives and fragments on abstract types are marked optional, and custom scalars accept any JSON value. If a schema cannot be derived for an operation, the tool is still registered, just without an output schema. +The generated schemas are permissive. A valid GraphQL response is never rejected by a client that validates against the schema: + +- Fields behind `@skip`, `@include`, or `@defer` directives are marked optional. +- Fields inside fragments on abstract types are marked optional. +- Custom scalars accept any JSON value. + +If a schema cannot be derived for an operation, the router still registers the tool without an output schema.As per path instructions: "Prefer short, declarative sentences. If a sentence has more than one comma-separated clause, consider splitting it.", "Use structured lists when presenting multiple distinct items. Do not pack them into a single paragraph." and "Avoid filler and hedging words like 'simply', 'just', 'easily'".
Also applies to: 314-321
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs-website/router/mcp/tools.mdx` at line 305, Revise the MCP tool response documentation around the sentence beginning “This lets MCP clients” and the related content through the “just” usage near the end of the section. Split sentences containing multiple comma-separated facts into short declarative sentences, use a structured list for distinct benefits or capabilities, and remove filler words such as “just” without changing the documented behavior.Source: Path instructions
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs-website/router/mcp/configuration.mdx`:
- Line 46: Qualify the output_schema.enabled documentation to state that
operation tools declare a derived output schema when schema derivation succeeds,
while retaining the tool without outputSchema when derivation fails. Apply this
wording consistently in docs-website/router/mcp/configuration.mdx at line 46 and
the configuration comment in router/pkg/config/config.go at lines 1365-1367.
---
Nitpick comments:
In `@docs-website/router/mcp/tools.mdx`:
- Line 305: Revise the MCP tool response documentation around the sentence
beginning “This lets MCP clients” and the related content through the “just”
usage near the end of the section. Split sentences containing multiple
comma-separated facts into short declarative sentences, use a structured list
for distinct benefits or capabilities, and remove filler words such as “just”
without changing the documented behavior.
In `@router/pkg/mcpserver/server.go`:
- Around line 1024-1030: Cap the response body before interpolating it into the
error text in the GraphQL response parsing branch around json.Unmarshal.
Truncate oversized body content to a bounded length while preserving the
existing unexpected-response error and IsError behavior, and use the truncated
value in fmt.Sprintf rather than the full body.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 7b338c3c-9047-4d45-9bf2-cd898da78880
📒 Files selected for processing (13)
docs-website/router/mcp/configuration.mdxdocs-website/router/mcp/tools.mdxrouter-tests/protocol/mcp_test.gorouter/core/router.gorouter/pkg/config/config.gorouter/pkg/config/config.schema.jsonrouter/pkg/config/fixtures/full.yamlrouter/pkg/config/testdata/config_defaults.jsonrouter/pkg/config/testdata/config_full.jsonrouter/pkg/mcpserver/response_schema.gorouter/pkg/mcpserver/response_schema_test.gorouter/pkg/mcpserver/server.gorouter/pkg/mcpserver/server_test.go
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
The router MCP server exposes GraphQL operations as MCP tools. Today, these tools declare only an input schema. MCP clients do not know the shape of a tool result before they call the tool. Results are one text blob that contains the raw GraphQL response as a string.
The structured tool output feature of the MCP spec (revision 2025-06-18) closes this gap. Tools declare an
outputSchema. Results carry machine-readablestructuredContent. This PR adds opt-in support for both to the router MCP server.Changes
router/pkg/mcpserver/response_schema.gobuilds a JSON schema for the{"data": ...}response envelope. It derives the schema from the selection set of each operation. It supports:@skip,@include, and@defermcp.output_schema.enabledcontrols the feature. The default isfalse. The environment variable isMCP_OUTPUT_SCHEMA_ENABLED.structuredContentthat mirrors the text content. Theexecute_graphqlbuilt-in tool has no declared output schema, but its successful results also carry structured content. The spec permits structured content without a declared schema.full.yamlfixture, and the config golden files are updated. The flag is wired throughcore/router.go.docs-website/router/mcp/tools.mdx, and the new key indocs-website/router/mcp/configuration.mdx.Behavioral change: non-GraphQL response bodies are now tool errors
The MCP server runs each tool call as a request against the router GraphQL endpoint. This change applies when the flag is on and when it is off. A response body that is not a GraphQL response (non-JSON, empty, or literal
null) now returnsIsError: true. Before this change, the router wrapped such a body in a text result that looked successful. Agents then parsed garbage as data. The GraphQL over HTTP spec requires a JSON body, so a non-JSON body is a transport failure, not a GraphQL result.IsErroris the MCP channel for a failed tool run.GraphQL error envelopes and partial results do not change. They returned
IsError: truebefore this change. They still do.Why opt-in
Output schemas make every
tools/listpayload larger. Structured content roughly doubles the payload of each successful result. Both consume the context budget of the client. The default is off.Test plan
cd router && go test ./pkg/mcpserver/covers:cd router && go test ./pkg/config/golden files showEnabled: falseby default andtruefromfull.yaml.cd router-tests && go test ./protocol/ -run 'TestMCP'covers:tools/listwith the flag on and offexecute_graphqlNot in scope
AddToolin go-sdk v1.7.0 leaves validation to the caller. A permissive schema never rejects a response at runtime.Blockers: None.
Summary by CodeRabbit
MCP_OUTPUT_SCHEMA_ENABLEDconfiguration; the feature is disabled by default.