Add cross-host portability guide for MCP Apps

[hatgit]

This guide covers cross-host portability issues for MCP Apps, including endpoint requirements, metadata formats, size notifications, and debugging tips.

This guide covers cross-host portability issues for MCP Apps, including endpoint
requirements, metadata formats, size notifications, and debugging tips.

Motivation and Context

While building an MCP App that needed to work across Claude, ChatGPT, and a
custom web host, I encountered a non-obvious issue: widgets rendered correctly in
ChatGPT but failed silently in Claude with "MCP error 32600: Session
terminated", despite successful mcp tool responses."

After many hours of debugging, I discovered the root cause: my authenticated
endpoint handled initialize, tools/list, and tools/call, but returned 404
for resources/list and resources/read. Claude requires these to fetch widget
HTML; ChatGPT uses direct URLs instead.

This information isn't documented anywhere that I am aware of. The existing migration guide covers
converting from OpenAI to MCP Apps, but not the nuances of supporting multiple
hosts simultaneously. This guide fills that gap. Related issue: #413

How Has This Been Tested?

Yes, tested in a production MCP server across the following, with widgets rendering successfully after tool calls:

• Claude.ai (web)
• Claude Desktop
• ChatGPT web and mobile (OpenAI Apps SDK)
• Custom web app/ host

Breaking Changes

None. This is documentation only.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• [x ] Documentation update

Checklist

• [x ] I have read the MCP Documentation
• [x ] My code follows the repository's style guidelines
• [x ] New and existing tests pass locally
• [x ] I have added appropriate error handling
• [ x] I have added or updated documentation as needed

Additional context

This guide intentionally avoids duplicating content from the existing migration
guide (migrate_from_openai_apps.md). It focuses specifically on cross-host
compatibility issues that aren't covered elsewhere—particularly the resources/*
endpoint requirement that causes silent failures in Claude.