fix: type structured MCP call errors

src/resources/responses/responses.ts

@@ -69,6 +69,28 @@ export interface ParsedResponse<ParsedT> extends Response {
   output_parsed: ParsedT | null;
 }
 
+/**
+ * Structured error returned by an MCP tool call.
+ */
+export interface ResponseMcpCallError {
+  /**
+   * The error type returned by the MCP server or transport layer.
+   */
+  type: 'mcp_protocol_error' | 'protocol_error' | 'tool_execution_error' | 'http_error' | (string & {});
+
+  /**
+   * The error message.
+   */
+  message: string;
+
+  /**
+   * Protocol or HTTP status code, when provided.
+   */
+  code?: number;
+
+  [key: string]: unknown;
+}
+
 export type ResponseParseParams = ResponseCreateParamsNonStreaming;
 
 export class Responses extends APIResource {
@@ -4415,7 +4437,7 @@ export namespace ResponseInputItem {
     /**
      * The error from the tool call, if any.
      */
-    error?: string | null;
+    error?: string | ResponseMcpCallError | null;
 
     /**
      * The output from the tool call.
@@ -4848,7 +4870,7 @@ export namespace ResponseItem {
     /**
      * The error from the tool call, if any.
      */
-    error?: string | null;
+    error?: string | ResponseMcpCallError | null;
 
     /**
      * The output from the tool call.
@@ -5316,7 +5338,7 @@ export namespace ResponseOutputItem {
     /**
      * The error from the tool call, if any.
      */
-    error?: string | null;
+    error?: string | ResponseMcpCallError | null;
 
     /**
      * The output from the tool call.
@@ -8415,6 +8437,7 @@ export declare namespace Responses {
     type ResponseInputTextContent as ResponseInputTextContent,
     type ResponseItem as ResponseItem,
     type ResponseLocalEnvironment as ResponseLocalEnvironment,
+    type ResponseMcpCallError as ResponseMcpCallError,
     type ResponseMcpCallArgumentsDeltaEvent as ResponseMcpCallArgumentsDeltaEvent,
     type ResponseMcpCallArgumentsDoneEvent as ResponseMcpCallArgumentsDoneEvent,
     type ResponseMcpCallCompletedEvent as ResponseMcpCallCompletedEvent,

tests/responsesItems.test.ts

@@ -14,6 +14,25 @@ describe('responses item types', () => {
   test('response output items are compatible with input items', async () => {
     expect(true).toBe(true);
   });
+
+  test('mcp_call output items accept structured errors', () => {
+    const item: OpenAI.Responses.ResponseOutputItem.McpCall = {
+      id: 'mcp_abc',
+      type: 'mcp_call',
+      approval_request_id: null,
+      arguments: '{"query":"latest tech gadgets"}',
+      error: {
+        type: 'mcp_protocol_error',
+        code: 32600,
+        message: 'Session terminated',
+      },
+      name: 'search',
+      output: null,
+      server_label: 'my-mcp-server',
+    };
+
+    expect(item.error).toMatchObject({ message: 'Session terminated' });
+  });
 });
 
 const unused = async () => {