Docs/mintlify native llms stack base

[enyst]

The MCP architecture page contains useful material but described an old action model and overstated result and annotation support. This stack base corrects it and includes the page in Mintlify's navigation and generated LLM index.

Changes

• Add MCP under SDK Architecture → SDK Components in docs.json.
• Correct the definition source link and explain schema validation separately from the MCPToolAction.data wrapper.
• Document text/image conversion and skipped unsupported result blocks.
• Correct annotation fields and distinguish hints from confirmation policy.

Stack order

#815 → this PR (stack base) → #817. #816 was squash-merged into this base branch rather than main, so this PR is what lands #816's content on main; the other two commits on the branch are already on main via #815. The net diff against main is exactly docs.json and sdk/arch/mcp.mdx. GitHub's native stacks do not support cross-fork PRs, so #815 itself could not join the native stack. Merge this, then rebase/retarget #817 onto main.

Source verification

• Client bridge.
• Argument validation and wrapper construction, raw schema and read-only hint handling.
• Action wrapper and supported result types.
• Annotation fields, confirmation policies.

Validation

• docs.json parses and the new sdk/arch/mcp entry resolves to the existing page.
• Internal destinations (including /sdk/arch/security) resolve.
• Mintlify preview deployment succeeded; link-rot and internal-link checks passed.

Note

Kept as draft until the stack dependency is resolved. After #815 landed on main, this base branch was synced with main; retarget/close the follow-up #817 onto main after this merges.

Description written by an AI agent (OpenHands) on behalf of the author.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
all-hands-ai	🟢 Ready	View Preview	Oct 3, 2026, 9:22 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[all-hands-bot]

Approved. The net change on this branch over main is exactly the intended MCP architecture correction (from #816) — docs.json (+1 nav entry) and sdk/arch/mcp.mdx (+48/−90) — so merging this lands #816's content on main. The two earlier docs/mintlify-native-llms-stack-base commits are content-identical to main (both already merged via #815) and add nothing.

Verified against software-agent-sdk at bd5fff0:

• MCPToolAction is a thin wrapper holding a data dict; to_mcp_arguments() returns self.data. The dynamic Pydantic validation model is created in mcp/tool.py (_create_mcp_action_type → Schema.from_mcp_schema) and used in both action_from_arguments() and __call__. The corrected MCPToolDefinition link (definition.py → tool.py) is right.
• action_from_arguments() validates the raw args, drops None values and DiscriminatedUnionMixin internal fields (kind), and stores the sanitized dict in data; the definition re-validates action.data before execution. The page describes this correctly.
• MCPClient extends FastMCP's Client; tools share one connected client, with no connection pool — "Connection Reuse" is accurate.
• MCPToolObservation.from_call_tool_result() maps TextContent/ImageContent and logs-and-skips everything else, including resources — matches the new "convert text and image blocks; log and skip unsupported blocks" wording.
• ToolAnnotations defines title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint; progressEnabled is not defined anywhere in the SDK — correctly removed.
• readOnlyHint suppresses the security_risk prediction field in the LLM-facing schema, while confirmation is governed by the configured policy (AlwaysConfirm/NeverConfirm/ConfirmRisky). The hints-vs-enforcement distinction is correct.

Mechanical checks: docs.json parses and the new sdk/arch/mcp entry sits under SDK Architecture → SDK Components; the internal /sdk/arch/security link resolves (200); the Mintlify preview deployment and link checks pass.

One non-blocking note: this is still a draft. Once you mark it ready, retarget/close the follow-up #817 (it currently stacks on this branch) so it rebases onto main after this merges.

This review was posted by an AI agent (OpenHands) on behalf of the reviewer.