Skip to content

Closed outputSchemas make every added output field break clients holding an older tools/list #2293

Open

Description

@sentry-junior

Problem

Our tool output schemas are closed: every object in a listed outputSchema has additionalProperties: false. MCP SDK clients check structuredContent against the outputSchema they cached from tools/list. So when we add an output field, a client still holding the older schema rejects every response from that tool, including writes that succeeded on the server:

MCP error -32602: Structured content does not match the tool's output schema: data/changes must NOT have additional properties, data/current must NOT have additional properties

That is the exact error in feedback MCP-SERVER-GQS (update_issue, opencode 1.19.3, HTTP transport).

Repro (code only)

  • I ran the server at 3bb34d3 in memory with the same SDK client as opencode 1.19.3 (@modelcontextprotocol/sdk@1.29.0). update_issue output validates against today's listed schema, with status=resolved, status=ignored, ignoreMode=forever, priority and assignedTo against the MSW fixtures.
  • I then gave the client the schema as it was before feat(mcp): Add priority parameter to update_issue #2155, which is today's schema minus priority. All five calls failed with the error above.
  • feat(mcp): Add priority parameter to update_issue #2155 (d8dc5bf, 2026-11-11) is the only change that added a key to both changes and current (update-issue.ts:520 and :526). feat(tools): Add outputSchema to update_issue #2002 (2026-11-05) introduced the closed schema. server.ts:406 registers the Zod outputSchema as-is, and the listed JSON Schema has "additionalProperties": false on changes, current and each {from,to} object.

Why clients keep old schemas

opencode 1.19.3 lists tools once on connect (packages/opencode/src/mcp/catalog.ts:145) and lists again only on tools/list_changed (mcp/index.ts:462). Its SDK patch re-runs initialize on session expiry but does not list tools again. A long-running client therefore keeps its first tool list and output validators across our deploys. Newer opencode (dev, packages/core/src/mcp/client.ts:728-733) skips SDK output validation on purpose. Older versions and other SDK-based clients with long-lived sessions still hit this.

Inference, not verified: the reporting client's cached tools/list came from before #2155 was deployed.

Suggested fix

  • Advertise open output schemas, with no additionalProperties: false on output objects. Then adding a field is backward compatible, and validation still catches missing or mistyped fields. One option is to post-process the JSON Schema at registration in server.ts. Another is .loose() on output objects.
  • Add a server.all-tools.test.ts check that no listed outputSchema contains additionalProperties: false.
  • Write down in docs/contributing/tool-responses.md that output fields are additive-only.

Reports

Report count: 4 (two distinct clients, two tools)

via automation evt_905b9c478746fd9deeb853f85ad7441b · Run ID dispatch_97a5d97c109364580f93a51a0bcb62cd, automation evt_905b9c478746fd9deeb853f85ad7441b · Run ID dispatch_4aa65545842f411a52539c78bc8c50bc, automation evt_905b9c478746fd9deeb853f85ad7441b · Run ID dispatch_1e4fa19455dad79f043ed20cf498acc8.

--

View Session [Sentry]

Activity

  1. linear-code commented on Nov 16, 2026

    @linear-code
  2. sentry-junior commented on Nov 17, 2026

    @sentry-junior
    ContributorAuthor

    Another report: MCP-SERVER-GRA (2026-11-17, feedback event 9df1fdf8b7ee40b181e20b513e7e869a).

    • Same client as GQS and GQT (same opencode install, HTTP transport, server 0.42.0), about a day later. feedback.tool=update_issue, kind=broken, impact=worked_around.
    • Same error, verbatim: MCP -32602: Structured content does not match the tool's output schema: data/changes must NOT have additional properties, data/current must NOT have additional properties, this time on update_issue(status='resolvedInNextRelease', ...).
    • The write landed: the reporter confirmed the resolved status and a set_resolved_in_release activity with get_issue_details / get_issue_activity. Every server-side tools/call update_issue span for this client in the last 3 days has status ok, so the rejection is in the client's output validation.
    • Not a new schema bug for resolvedInNextRelease: at 50a47ba, changes and current always carry the same four keys whatever the status (update-issue.ts:514-527, built at :1051-1057, :1113, :1153), so today's listed schema accepts this output. The stale cached tools/list from the original report is still the best explanation, now surviving more than a day of deploys. Inference, not verified: tools/list isn't traced, so I can't see when the client last listed tools.
    • The reporter calls out the impact: an error after a successful write prompts the agent to retry, which means duplicate writes.

    No fix PR or fix/* branch exists yet, and nothing on main since 2026-11-16 changes the output schemas.

    Report count: 3 (GQS, GQT, GRA; one distinct client)

  3. sentry-junior commented on Nov 20, 2026

    @sentry-junior
    ContributorAuthor

    Another report: MCP-SERVER-GT6 (2026-11-20, feedback event 8cd03fe29de4473e9f111ee9fa8de086). This one is a second distinct client and a different tool, so the pattern is not specific to opencode or update_issue.

    • Client: a different OAuth client from GQS/GQT/GRA (app.client.family=node, User-Agent: node, HTTP transport, Mcp-Protocol-Version: 2025-11-25, server 0.42.0). feedback.tool=get_issue_details, kind=broken, impact=worked_around.
    • Error: MCP error -32602: structured content does not match output schema: data/event must NOT have additional properties, on get_issue_details(issueId=…, fresh=true). The agent worked around it with get_sentry_resource(resourceType=issue), which renders the same event.
    • Likely added field: fix(mcp): Return the event-level stacktrace from issue and event tools #2402 (f442d28, merged 2026-11-19, on production since at least the 7c618d5 deploy on 2026-11-20 03:02 UTC) added stacktrace directly on event: schema at packages/mcp-core/src/tools/support/issue-event-payload.ts:89, always emitted at :508. Ajv reports the extra key at the path of its parent object, and data/event is exactly where stacktrace sits. No other top-level event key changed since feat(mcp): Return structured get_issue_details for every event type #2041 (packageVersions and the rest date from 2026-11-12).
    • Today's server output matches today's schema: at 7c618d5, buildIssueEventPayload (issue-event-payload.ts:498-523) returns only the keys issueEventSchema declares (:67-157). So the rejection comes from a schema the client cached before the fix(mcp): Return the event-level stacktrace from issue and event tools #2402 deploy, not from the current listed schema.
    • The same client called get_issue_details successfully on 2026-11-18 01:26 UTC (before fix(mcp): Return the event-level stacktrace from issue and event tools #2402), which fits a long-lived client that kept its first tools/list. Inference, not verified: tools/list isn't traced, and the failing get_issue_details call itself has no span in sentry/mcp-server (sampled out or not recorded), so I can't see its response.

    No fix PR or branch exists yet for this issue. The suggested fix above (open output schemas plus an all-tools check that no listed outputSchema has additionalProperties: false) would have prevented this report too.

    Report count: 4 (GQS, GQT, GRA, GT6; two distinct clients, two tools)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions