vercel/ai · error · MCPClientError

Tool "${toolName}" did not return structuredContent or parse

Error message

Tool "${toolName}" did not return structuredContent or parseable text content

What it means

MCPClientError thrown as the terminal fallback in output-schema-aware tool result processing: the tool returned neither `structuredContent` nor text content that could be parsed against the declared outputSchema. When a client supplies an outputSchema, the SDK guarantees a validated structured value or throws — this error signals the server simply produced nothing usable.

Source

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

      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,
  }: {
    params?: PaginatedRequest['params'];
    options?: RequestOptions;
  } = {}): Promise<ListResourcesResult> {
    return this.listResourcesInternal({ params, options });
  }

  readResource({
    uri,
    options,
  }: {

View on GitHub (pinned to 69428b1f8b)

Solutions

Log the full tool result (result.content) to see what the server actually returned
Check the server tool for bugs/empty returns and fix it to emit structuredContent or JSON text
Remove the outputSchema from the client if the tool's output is genuinely unstructured or multimodal
Verify auth/connectivity so the server isn't returning empty error responses

Example fix

// before: expecting JSON but tool returns only an image block
const tool = mcpTool({ outputSchema: z.object({ url: z.string() }) });

// after: either have the server wrap output as structuredContent
// { structuredContent: { url: '...' } }
// or handle the raw content without an outputSchema
const tool = mcpTool();

Defensive patterns

Strategy: try-catch

Validate before calling

const result = await client.callTool({ name, arguments });
const hasUsableOutput =
  result.structuredContent != null ||
  (Array.isArray(result.content) && result.content.some(c => c.type === 'text' && c.text?.trim() !== ''));
if (!hasUsableOutput) {
  throw new Error('Tool returned no structuredContent or text content');
}

Type guard

function isEmptyToolOutput(error: unknown): error is MCPClientError {
  return MCPClientError.isInstance(error) && error.message.includes('did not return structuredContent or parseable text content');
}

Try / catch

try {
  const value = await mcpTool.execute(args, options);
} catch (error) {
  if (isEmptyToolOutput(error)) {
    // inspect raw result/health of the server; retry or surface a clear message
  } else {
    throw error;
  }
}

Prevention

Only declare an outputSchema for tools known to return structured or JSON-text output
Check server tool health/empty-result handling; alert on empty content arrays
Inspect the full result.content to see what the server actually returned before blaming the schema

When it happens

Trigger: Calling a tool with a declared outputSchema where the result contains no structuredContent and either no text content at all, empty text, or only non-text content blocks (images, audio, resource links).

Common situations: Server tool errored internally and returned an empty result; tool returns binary/multimodal content only while the client expects structured JSON; server not yet implementing structured output and returning an empty content array; connectivity or auth issues yielding truncated empty responses.

Related errors

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