vercel/ai · error · MCPClientError

Tool "${toolName}" returned content that does not match the

Error message

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

What it means

MCPClientError thrown when a tool returns no structuredContent, so the client falls back to parsing the tool's text content as JSON against the declared outputSchema, and that parse/validation fails. The safeParseJSON error is attached as `cause`. It guards callers against text output that doesn't conform to the tool's promised schema.

Source

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

          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) {
          throw new MCPClientError({
            message: `Tool "${toolName}" returned content that does not match the expected outputSchema`,
            cause: parseResult.error,
          });
        }

        return parseResult.value;
      }
    }

    throw new MCPClientError({
      message: `Tool "${toolName}" did not return structuredContent or parseable text content`,
    });
  }

  listResources({
    params,
    options,
  }: {

View on GitHub (pinned to 69428b1f8b)

Solutions

Check error.cause (safeParseJSON result) to see if the failure is a JSON syntax error or a schema mismatch
Fix the server tool to return valid JSON text matching its declared outputSchema
Prefer having the server return structuredContent instead of JSON-in-text
If the tool legitimately returns non-JSON text, remove/loosen the outputSchema on the client

Example fix

// before: server returns plain text 'Flight booked!' but outputSchema demands JSON
const tool = mcpTool({ outputSchema: z.object({ status: z.string() }) });

// after: make server return {"status":"booked"} as text or structuredContent,
// or drop the schema if output is unstructured
const tool = mcpTool(); // no outputSchema

Defensive patterns

Strategy: validation

Validate before calling

import { safeParseJSON } from '@ai-sdk/provider-utils';
// pre-check raw text content if available before trusting schema parse:
const check = await safeParseJSON({ text: rawText, schema: outputSchema });
if (!check.success) console.error('Text is not valid schema-conformant JSON:', check.error);

Type guard

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

Try / catch

try {
  const value = await mcpTool.execute(args, options);
} catch (error) {
  if (isTextSchemaMismatch(error)) {
    console.error('JSON/schema failure:', (error.cause as any)?.issues ?? error.cause);
    // decide: fix server output or drop the outputSchema
  } else {
    throw error;
  }
}

Prevention

Prefer servers that return structuredContent instead of JSON embedded in text
Verify server tools emit pure JSON text with no surrounding prose or markdown
Keep outputSchema aligned with the server's actual JSON shape
Inspect error.cause to distinguish JSON syntax errors from schema mismatches

When it happens

Trigger: Calling a tool with an outputSchema where the server returns only text content (no structuredContent), the text is either not valid JSON or valid JSON that doesn't satisfy the schema — e.g. the server emits a human-readable message, markdown, or JSON with a different shape.

Common situations: Server tool updated to return prose/error text instead of JSON output; server doesn't support structured output but client declares an outputSchema; JSON payload wrapped differently (array vs object) or missing required fields; model/server emitting JSON with surrounding text so raw parse fails.

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

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