Skip to content
← Blog

Release

TurboMCP v3.4.0: Handler Errors, Structured Output, and Server Instructions Reach the Wire

TurboMCP 3.4.0 closes seven gaps where information a handler held was discarded before the client saw it: tool error kinds, structured error data, structuredContent, instructions, and prompt errors.

TurboMCP Engineering Team · · 7 min read

TurboMCP 3.4.0 (2026-09-14) came out of a downstream team’s report of seven gaps in the handler contract: places where what a handler returned was not what reached the client. All seven are fixed. They shared one shape, which was information the handler held and the SDK discarded before the wire.

The 3.x line exists to keep existing servers working, and breaking work belongs in 4.x, so the bar for this release was an uneventful upgrade. Nearly everything is additive or a spec-compliance correction. Two spots need a moment of attention, covered in Upgrade notes below.

What changed

Tool errors keep their kind

A #[tool] returning Err(McpError) still reports a tool execution error (isError: true, per SEP-1303, so the model can self-correct). What changed is that the classification the SDK used to flatten into display text now travels in _meta:

_meta key Value
io.turbomcp/errorKind The ErrorKind, snake_case
io.turbomcp/errorCode Its JSON-RPC code
io.turbomcp/errorData The with_data payload, when set

A client can finally tell bad input from an internal fault. The spec reserves _meta for data the client application consumes rather than the model, which is what this is. It applies to argument-validation failures too. Hand-written handlers can use McpError::to_tool_result, and the key names are available as turbomcp_core::meta_keys.

Structured error detail with McpError::with_data

with_data attaches a serde_json::Value that reaches the client, both as the JSON-RPC error object’s data member (previously hard-coded to None) and as io.turbomcp/errorData in a tool result’s _meta. Nothing else in the error is forwarded: operation, component and source_location stay server-side. That makes with_data the one place for machine-readable detail such as a field path, a retry hint or a validation report.

Server instructions

The MCP schema defines an instructions string on the initialize result, and InitializeResult has the field, but no code path emitted it. #[server(instructions = "...")] now fills it. It is backed by a new McpHandler::instructions method that defaults to None, so the field stays off the wire unless a server supplies one.

CompositeHandler gains with_instructions. A mount’s own instructions are deliberately not merged, since each was written for a standalone server and would contradict the composite’s prefixed tool names.

Server metadata as expressions

#[server] now accepts title, website_url and icons, and every value is an expression rather than a string literal, so server identity can come from the build or the environment.

use turbomcp::prelude::*;

#[derive(Clone)]
struct Contract;

#[server(
    name = "contract",
    version = env!("CARGO_PKG_VERSION"),
    title = "Contract Server",
    instructions = "Call `boom` to see a typed failure.",
    website_url = "https://example.com/contract",
    icons = ["https://example.com/icon.png"]
)]
impl Contract {
    /// Fails with a caller-fault kind.
    #[tool]
    async fn bad_input(&self) -> McpResult<String> {
        Err(McpError::invalid_params("start must precede end")
            .with_data(serde_json::json!({ "field": "start" })))
    }

    /// Fails with a server-fault kind.
    #[tool]
    async fn broken(&self) -> McpResult<String> {
        Err(McpError::internal("upstream timed out"))
    }
}

The two tools above report different io.turbomcp/errorKind values in _meta, and the first also carries {"field": "start"} in io.turbomcp/errorData.

Content types re-exported from turbomcp

Assembling a result by hand used to mean depending on turbomcp-types directly. These are now re-exported from turbomcp: Content, TextContent, ImageContent, AudioContent, EmbeddedResource, TextResourceContents, BlobResourceContents, ResourceTemplate, Annotations, ToolAnnotations, ToolOutputSchema, Icon and MetaMap.

Fixes

Json<T> populates structuredContent

Json<T> is the wrapper whose purpose is typed output, and it only ever produced a text block. Callers built ToolResult by hand to get structuredContent. The value is now placed in structuredContent when it serializes to a JSON object, and it is always mirrored into a text block for clients that ignore structured output.

structuredContent can no longer hold a non-object

Every MCP schema version the SDK speaks types the field as { [key: string]: unknown }, but ToolResult::json wrote any JSON value there. Returning a Vec<T> or a serde_json::Value array from a tool produced a result that strict clients reject outright, the same failure mode as the 3.3.0 $defs bug. Arrays and scalars now travel in the text block only.

This is a behaviour change: ToolResult::json(&vec![...]).structured_content is now None. Use an object wrapper if a client depends on that field.

#[prompt] errors propagate

A #[prompt] handler returning Err had it rendered as a user message reading Error: .... A failed render was indistinguishable from a successful one, and the model was asked to act on the failure. A prompt returning McpResult<T> or Result<T, McpError> now returns a JSON-RPC error. Handlers with other error types keep the old rendering in 3.4.0, which is all a bare Display value allows. (3.5.0 later extended propagation to any Result-shaped return.)

Handler bodies no longer inflate dispatch futures

call_tool, read_resource and get_prompt are each generated as one async block with a match arm per handler, so the resulting state machine was at least as large as the largest handler body. It is returned by value, moved into tasks and held for the whole call. The changelog reports a measurement on a synthetic server: with 30 tools, the largest holding a 10 KiB local, the call_tool future was 10776 bytes, and boxing each arm brought it to 192 bytes. The size is now independent of handler count and body size, at the cost of one allocation per dispatch, against JSON parsing already on that path.

The original report attributed the cost to arms summing into one frame. They do not: rustc overlaps disjoint match arms, so the cost was the maximum over arms. Boxing removes it either way.

Unknown #[server] keys are compile errors

Unknown attribute keys used to be silently dropped. They are now a compile error, matching what #[tool] has done since 3.2.0. This only affects code carrying a key that never did anything, such as a typo.

Upgrade notes

[dependencies]
turbomcp = "3.4"

ErrorContext has a new public field. Storing the with_data payload required adding a field to turbomcp_core::error::ErrorContext. cargo semver-checks classes that as a major break (constructible_struct_adds_field), because code that builds the struct with an exhaustive literal, ErrorContext { operation, component, request_id }, stops compiling. The maintainers shipped it in a minor on purpose: ErrorContext is a context bag meant to be defaulted and filled through McpError::with_operation, with_component and with_request_id, nothing in the repository constructs it literally, and the alternative was leaving a real defect open until 4.x. If you do build it literally, add ..Default::default().

Three behaviour corrections where the old behaviour was itself the bug:

  1. ToolResult::json no longer writes arrays or scalars into structuredContent. Wrap them in an object if a client depends on the field.
  2. A #[prompt] returning McpResult<T> or Result<T, McpError> now yields a JSON-RPC error on Err, not a successful prompt containing error text.
  3. Unknown #[server] attribute keys fail to compile.

Everything else in the release is additive, and the workspace is otherwise clean against the 3.3.0 baseline.

The release also drops 22 unused entries from [workspace.dependencies] (with Cargo.lock unchanged and no published manifest moved) and replaces two flaky wall-clock-bounded mmap tests with deterministic ones.

For more, see the TurboMCP repository, the TurboMCP product page, or get in touch.

  • TurboMCP
  • Rust
  • MCP
  • Error Handling
  • Structured Output
  • Macros
  • v3

Keep reading

Want this running in your business?

We build and deploy production AI for enterprises. Let's talk about what you're working on.