Repository navigation
MCP: Return readable tool results and errors #2627
Description
Some clients can show a blank result because Data API puts the response in structured output and leaves text content empty. Return readable content for successful commands and errors while preserving the full structured response, status, and warnings.
This is an independent follow-up under #2408. It becomes required for launch if a supported client cannot display useful results without it.
This ticket is done when tests cover data, status-only responses, partial failures, warnings, and serialization errors, and an endpoint test proves the content is readable. #2633 checks visibility in supported clients. #2628 handles errors that occur before a command result exists.
Status on October 23, 2026
PR #2652 fixes this. It returns the complete Data API response as readable JSON text and keeps structured content and status metadata unchanged. It sits in the MCP stack above #2645, so it has no CI run yet. The combined stack passed 381 focused tests locally. Client display still needs qualification in #2633.
Implementation requirements and source references
Tracking issue: #2408.
Tracking correspondence: Related changelog IDs are listed below. This is an independent follow-up, outside the launch milestone unless promoted for a demonstrated release blocker. Shared requirement IDs remain stable across the delivery plan and #2408.
Why
Data API currently returns an empty MCP content list for every tool call. Results are placed in structuredContent, and status-only results appear only in metadata. A client that displays text content can therefore show nothing after a successful command or an error.
This is an existing client-usability fix. It can ship independently and is not required to change the MCP package version. Treat it as an upgrade blocker only if a required client cannot use the existing result format.
Work
- Include a serialized Data API response in MCP text content.
- Preserve structured results, status, warnings, and both successful and failed parts of partial results.
- Return a useful tool error if response serialization fails.
Done when
Mapping tests cover data, status-only responses, errors, partial results, warnings, and serialization failure. An MCP endpoint test confirms that a client receives readable content. HTTP API responses remain unchanged.
#2628 handles failures before a command result exists. This ticket handles how that result is presented. Closed PRs #2503 and #2591 contain reusable work.
Modern protocol and OAuth acceptance details
Assert resultType: "complete" on normal tool results, including isError results. Preserve JSON Schema 2020-12-compatible structured output without assuming the protocol only permits objects. This ticket may keep the current object-shaped Data API response. A serialization failure must return a bounded readable error without credentials or payload leakage. Verify actual result visibility in each qualified client, including IBM Bob, under #2633. Treat this as a launch gate if a required client otherwise displays an empty result.
Changelog traceability
- M8 Tag every successful RPC result, lines 26 — Required.
Normative detail: Streamable HTTP, authorization, caching.
Required base protocol/schema behavior remains owned by #2625 and verified by #2626. This follow-up owns only its stated enhancement or proven gap.
Activity
[-]Include Data API results in MCP text content[/-][+]MCP: Include Data API results in text content[/+][-]MCP: Include Data API results in text content[/-][+]MCP: Return readable tool results and errors[/+]erichare commentedon Oct 28, 2026
Closing as not planned. After talking it through with @amorton, we decided not to repeat the response as text content, since structuredContent already carries it. Clients that only show text should read structuredContent instead, and we'll ask IBM Bob to support it upstream. Inserts, updates, and deletes return their status only in
_meta.status, so that request should cover_metatoo. #2652 is closed for the same reason, and #2633 still covers checking what each client displays.