vercel/ai · error · MCPClientError

Tool "${toolName}" returned structuredContent that does not

Error message

Tool "${toolName}" returned structuredContent that does not match the expected outputSchema

What it means

MCPClientError thrown after a tool call when the server returned `structuredContent` but it fails validation against the tool's declared `outputSchema`. The client validates structured output with safeValidateTypes before returning it, protecting callers from schema-violating server responses; the Zod validation error is attached as `cause`.

Source

Thrown at packages/mcp/src/tool/mcp-client.ts:1297

    return tools as McpToolSet<TOOL_SCHEMAS>;
  }

  /**
   * Extracts and validates structuredContent from a tool result.
   */
  private async extractStructuredContent(
    result: CallToolResult,
    outputSchema: FlexibleSchema<unknown>,
    toolName: string,
  ): Promise<unknown> {
    if ('structuredContent' in result && result.structuredContent != null) {
      const validationResult = await safeValidateTypes({
        value: result.structuredContent,
        schema: asSchema(outputSchema),
      });

      if (!validationResult.success) {
        throw new MCPClientError({
          message: `Tool "${toolName}" returned structuredContent that does not match the expected outputSchema`,
          cause: validationResult.error,
        });
      }

      return validationResult.value;
    }

    // Fallback
    if ('content' in result && Array.isArray(result.content)) {
      const textContent = result.content.find(c => c.type === 'text');
      if (textContent && 'text' in textContent) {
        const parseResult = await safeParseJSON({
          text: textContent.text,
          schema: outputSchema,
        });

        if (!parseResult.success) {

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Inspect validationResult error (error.cause) to see exactly which fields failed validation
2. Update the client's outputSchema to match the tool's current server-side schema
3. Fix the server tool so its structuredContent conforms to its declared outputSchema
4. Pin/align client and server tool versions so schemas agree

Example fix

// before: schema expects { result: number } but server returns { result: string }
const tool = mcpTool({ outputSchema: z.object({ result: z.number() }) });

// after: align with the server's actual output
const tool = mcpTool({ outputSchema: z.object({ result: z.string() }) });

import { safeValidateTypes } from '@ai-sdk/provider-utils';
import { asSchema } from 'ai';
// pre-check before/around the call if you have the raw structuredContent:
const check = await safeValidateTypes({ value: raw, schema: asSchema(outputSchema) });
if (!check.success) console.error('structuredContent mismatch:', check.error);

function isOutputSchemaMismatch(error: unknown): error is MCPClientError {
  return MCPClientError.isInstance(error) && error.message.includes('structuredContent that does not match the expected outputSchema');
}

try {
  const value = await mcpTool.execute(args, options);
} catch (error) {
  if (isOutputSchemaMismatch(error)) {
    console.error('Fields failed validation:', (error.cause as any)?.issues);
    // update schema or handle server-side shape change
  } else {
    throw error;
  }
}

When it happens

Trigger: Calling a tool whose server definition (or client-side outputSchema) declares an outputSchema, the server responds with structuredContent, and the payload's shape/types don't match the schema — wrong field names, missing required fields, type mismatches, or an outdated schema on the client side.

Common situations: Server upgraded and changed its structured output shape while the client caches an old outputSchema; client and server define divergent schemas for the same tool; server bug emitting null/undefined in required fields; numeric-vs-string type drift between implementations.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Tool "${toolName}" returned content that does not match the
• Tool "${toolName}" did not return structuredContent or parse
• No object generated: response did not match schema.
• No object generated: response did not match schema.
• The ACP implementation did not load the active harness-owned

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/038ebdcf09d4533b. Report an issue: GitHub.