Structured output and typed direct tools for MCP 2026-07-28 clients #257

Blocked by #247.

Clients that support MCP 2026-07-28 should get typed tools with structured output on the direct-tool surface (?codemode=false), so client-side Code Mode and programmatic tool calling can work with API results as data instead of parsing text. Older clients keep today's behaviour exactly.

GitHub's MCP server shipped the same thing in v2.0.0: output schemas and structured content, advertised only to clients on 2026-07-28 or later.

Why it waits for Forge

outputSchema is a promise: the spec says every structured result must conform, and clients should validate. Forge generates response bodies correctly, so its 2xx response schemas can back that promise. The OpenAPI spec we serve from today can't. #247 builds mcp-tools.json from Forge, and this work extends that generator.

Scope

Era gating

• createMcpHandler already passes era: 'legacy' | 'modern' to our factory. Pass it into createServer and add the new fields only for modern.
• Legacy responses stay byte-identical to today. Pin tools/list and tools/call output for legacy with snapshot tests.

Direct tools, modern era

• Typed nested inputSchema and annotations from the Forge artifact (today every parameter is a flat string and body is a string).
• outputSchema from each operation's 2xx response schema in Forge.
• structuredContent is the full parsed API response, never truncated and with no size cap. Clients making direct tool calls usually write results to a file.
• Truncation applies only to the text content. ?truncateToolResult=false now only affects text.
• Responses that aren't JSON stay text-only, as today.
• API errors return isError: true with text only and no structuredContent (see Preserve useful Cloudflare API errors in tool results #255).

tools/list caching

• feat(mcp): let clients cache tools/list for an hour and share it across users #245 adds ttlMs/cacheScope: 'public' for modern clients.
• Build the tools/list payload once per isolate per era instead of mapping ~2,900 tools on every request.
• Consider paginating tools/list: the Forge tools alone are ~7 MB before output schemas.

Code Mode, modern era (optional)

• Return structuredContent from execute and search.

Open questions

• Tool names: Forge uses cf CLI names (dns_records_create), which renames every direct tool. New names for modern clients only, or keep the current names everywhere?
• Legacy input schemas: keep them unchanged, or move everyone to typed bodies while still accepting body as a string?