feat(mcp): support structuredContent via useStructuredContent; return full CallToolResult

[SkinnnyJay]

Summary

• Adds support for structuredContent in MCP tool results.
• Returns full CallToolResult from MCPServer#callTool (previously returned content[]).
• Adds useStructuredContent option to MCP server constructors (stdio, streamable-http, SSE), default false to preserve backward compatibility.
• Updates mcpToFunctionTool to include structuredContent in tool outputs when enabled.
• Closes Support structureOutput from MCP server tools #468.
• Parity with Python feature: MCP: add support for tool_result.structuredContent openai-agents-python#1150.
• Fixes TypeScript compilation errors (TS2352) in MCP server shims that prevented builds from completing.

Motivation

Previously, MCP server callTool only returned result.content. If a tool returned only structuredOutput, agents saw an empty array. This PR brings parity with the Python SDK by exposing structuredContent and providing a toggle to control inclusion in tool outputs.

Changes

• API: MCPServer#callTool(...) now returns CallToolResult (full object: { content, structuredContent? }).
• Option: useStructuredContent?: boolean added to all MCP server options and stored on base classes. Default false to avoid duplicate data when servers include structured output inside content.
• Composition in mcpToFunctionTool:
  • Default (flag off):
    • Single content item → return that item object
    • Multiple content items → return array of items
  • With useStructuredContent true:
    • Single content item → return [contentItem, structuredContent]
    • Multiple content items → append structuredContent to the array
    • No content → return structuredContent object
• No stringification: We keep JS outputs as objects/arrays to avoid forcing downstream JSON.parse. This differs from Python’s string concatenation but preserves capability parity and improves ergonomics/perf in JS.

Before/After

Before

// Returned only content[]
const content = await server.callTool('tool', args); // [] when tool only returned structuredOutput

After

// Returns full object
const result = await server.callTool('tool', args);
// result: { content: [...], structuredContent?: any }

// Default (useStructuredContent: false)
// Single content → object; multiple → array

// With useStructuredContent: true
const server = new MCPServerStdio({ command: 'my-mcp', useStructuredContent: true });
// Single content + structured → [contentItem, structuredContent]
// Only structured → structuredContent object

Tests

• Added packages/agents-core/test/mcpStructuredContent.test.ts:
  • Default off: single content returns the item object.
  • With flag true:
    • Single content + structured → array with structured appended.
    • No content + structured → structured object.
    • Multiple content + structured → array with structured appended.
• Updated mcpToolFilter.integration.test.ts stub to return { content: [...] }.
• All tests pass: 393 tests across 62 files.

Docs

• Added a section to packages/agents-core/README.md documenting useStructuredContent, the new callTool return type, and rationale for not stringifying.

Breaking Impact

• Minimal breaking change: Only affects advanced users who directly call MCPServer#callTool and expect an array return type.
• Behavioral outputs for mcpToFunctionTool remain backward-compatible by default (objects/arrays), with optional structuredContent inclusion when enabled.

Checklist

• Builds and full test suite pass
• Docs updated
• Changeset added (patch bump for @openai/agents-core)
• Linked to issue Support structureOutput from MCP server tools #468 and Python PR parity

[changeset-bot]

🦋 Changeset detected

Latest commit: b075226

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@openai/agents-core	Patch
@openai/agents-openai	Patch
@openai/agents-realtime	Patch
@openai/agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[seratch]

@codex review this

[chatgpt-codex-connector]

Codex Review: Here are some suggestions.

Reply with @codex fix comments to fix any unresolved comments.

About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you open a pull request for review, mark a draft as ready, or comment "@codex review". If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex fix this CI failure" or "@codex address that feedback".

[seratch]

Thanks for quickly checking my comments! Once they're addressed, we will check this PR then.

[SkinnnyJay]

@codex review this

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

[SkinnnyJay]

@codex review this

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.