mcp-data-platform-v1.81.1

Overview

v1.81.1 is a patch release on top of v1.81.0. It makes every failed tool call return a uniform, self-describing error so an LLM agent can tell a correctable mistake from a platform problem and act on it, instead of receiving an opaque, undifferentiated string and filling the gap with a plausible-but-wrong narrative (often a false "the platform is down" conclusion). For an agent-facing MCP, error quality is a reliability feature, not a cosmetic one.

A failure now carries a self-describing text message and a machine-readable structuredContent.error object:

{
  "isError": true,
  "content": [
    { "type": "text", "text": "the \"asset_id\" parameter is required (code: missing_required_parameter) Hint: Supply \"asset_id\" and retry. This is a problem with the call's arguments, not a platform fault." }
  ],
  "structuredContent": {
    "error": {
      "code": "missing_required_parameter",
      "category": "client_input",
      "message": "the \"asset_id\" parameter is required",
      "hint": "Supply \"asset_id\" and retry. This is a problem with the call's arguments, not a platform fault."
    }
  }
}

Why

The platform already produced excellent, actionable errors on some paths (the session gate's setup_required, auth and authz categorized errors) but collapsed others to bare strings, and the category it tracked for audit was never surfaced to the agent. This release makes the surface uniform by construction and pushes the category, a stable code, and a corrective hint to the agent.

How it works

flowchart LR
    H[Tool handler] -->|bare or categorized result, or panic| N[MCPErrorContractMiddleware]
    N -->|enrich / recover / pass-through| A[Audit + Metrics]
    A --> C[Client: text + structuredContent.error]
    subgraph Source-categorized
        AU[auth / authz] --> N
        SG[session gate: setup_required] --> N
        PT[portal: missing-param / not-found / unavailable / unauthorized] --> N
    end

• Contract type. PlatformError gains Code and Hint (keeping Category and Message). BuildErrorResult renders the self-describing text, sets structuredContent.error, and stashes the error so ErrorCategory() keeps feeding audit and metrics. It is built on the existing PlatformError / CategorizedError, not a parallel type.
• Central normalizer. MCPErrorContractMiddleware guarantees the envelope on every tools/call error result, even when an individual tool returns only a bare message; recovers a panicking handler into a categorized internal_error result instead of a dropped connection; and unwraps the legacy {"error":...} toolkit text into a clean message. It is registered inner to audit and metrics so they observe the normalized category, and it covers every toolkit (including the proxied trino, datahub, and s3 tools) at the shared chain, so no upstream-library change is required.
• Source categorization. Auth (unauthenticated) and authz (unauthorized) carry corrective hints; the session gate carries setup_required; the portal categorizes missing_required_parameter, not_found, feature_unavailable, and unauthorized.
• Metrics. ClassifyToolCallResult maps the new categories so client_input, not_found, setup_required, and feature_unavailable record as validation_err and internal records as internal_err, rather than all falling through to upstream_err.
• Audit. The audit row logs the bare error message (no code or hint suffix), so audit stays terse while the agent gets the rich text.

Error vocabulary

Category	Whose fault	Example codes
client_input	the call	missing_required_parameter
not_found	the call	not_found
authentication_failed	caller identity	unauthenticated
authorization_denied	caller identity	unauthorized
user_declined	the user	declined elicitation
feature_unavailable	deployment config	feature_unavailable
internal	the platform	internal_error
tool_error	unclassified	tool_error

Scope

The normalizer makes the contract uniform everywhere immediately. Precise codes are applied at the dispatch layer and the highest-traffic agent surface (the portal) in this release; the remaining toolkit error sites still get the envelope (category tool_error) with their original, already-descriptive message via the normalizer. Finer per-site codes for the long tail are a follow-up.

Not included in this release: a transient upstream category and toolkit-specific categorization of proxied trino, datahub, and s3 error text (the proxy toolkits cannot import the middleware package without an import cycle); and converting protocol-level JSON-RPC CodeInvalidParams (malformed requests) into tool-result errors, since this targets tool-execution errors.

Changelog

• fix(middleware): self-describing, uniform tool-execution error contract (#539, #563) by @cjimti

For the prior feature release (the first-class prompt library and relevance search across every surface), see v1.81.0. A theme-by-theme timeline of the whole project is in the Release Highlights.

Installation

Homebrew (macOS)

brew install txn2/tap/mcp-data-platform

Claude Code CLI

claude mcp add mcp-data-platform -- mcp-data-platform

Docker

docker pull ghcr.io/txn2/mcp-data-platform:v1.81.1

Verification

All release artifacts are signed with Cosign. Verify with:

cosign verify-blob --bundle mcp-data-platform_1.81.1_linux_amd64.tar.gz.sigstore.json \
  mcp-data-platform_1.81.1_linux_amd64.tar.gz