Welcome to the AgntUX Documentation and Knowledge Base! This website serves as a comprehensive resource for understanding and building ChatGPT Apps and MCP Apps - two powerful new paradigms for creating interactive AI applications.

This documentation site has two primary purposes:

First and foremost, this is a public knowledge base that brings together all available information about ChatGPT Apps and MCP Apps. The AI agent space is evolving rapidly, with developments happening across multiple companies and open-source communities. This site consolidates that information in one place, making it easier to stay current with the latest developments.

Once AgntUX launches publicly, this site will also serve as the official product documentation for AgntUX - an AI agent that helps users plan, design, build, and deploy ChatGPT Apps and MCP Apps.

The space is moving quickly, and it can be difficult to keep up with everything happening. Various efforts across different companies and open-source groups have not yet merged into a cohesive solution. This repository helps bridge that gap by:

• Curating information from multiple sources (GitHub issues, blog posts, announcements, Stack Overflow, etc.)
• Summarizing and organizing content in a logical, easy-to-navigate structure
• Staying current with daily automated updates

Behind the scenes, an AI agent automatically updates the content in this repository on a daily basis. The agent:

• Monitors GitHub issues, new articles, blog posts, and announcements
• Tracks Stack Overflow discussions and community conversations
• Summarizes and curates relevant information
• Creates pull requests with updates
• A human reviewer then reviews and merges the PRs

This ensures the documentation stays current with the rapidly evolving landscape of ChatGPT Apps and MCP Apps.

We welcome contributions from the community! If you have updates, corrections, new examples, or troubleshooting information to share, please submit a pull request. Your contributions help keep this knowledge base accurate and comprehensive for all developers building ChatGPT Apps and MCP Apps.

This documentation website offers multiple ways to access and use the content, depending on your workflow and preferences.

The most straightforward way to use this site is to browse and read the documentation directly in your web browser. You can:

• Navigate through categories and topics using the left sidebar
• Use the search feature (⌘K or click the Search button) to find specific information
• Click on headings to get shareable anchor links
• Scroll through the long-form content to read everything in order

The left navigation includes an "AI-Friendly Options" dropdown menu with three ways to access the documentation:

This documentation is available as an MCP (Model Context Protocol) server, allowing AI coding assistants to access and reference the content directly.

To connect:

1. Click the "AI-Friendly Options" dropdown in the left navigation
2. Select "Connect as MCP Server"
3. Follow the instructions for your specific coding assistant (Cursor, Claude Desktop, Windsurf, VSCode, etc.)
4. Once connected, your AI assistant can reference and cite information from this documentation

This is particularly useful when building ChatGPT Apps or MCP Apps, as your AI assistant can pull in relevant information from the docs to help guide your development.

You can view the entire documentation as raw Markdown text in your browser.

1. Click the "AI-Friendly Options" dropdown in the left navigation
2. Select "View as Markdown"
3. The documentation will open in a new tab as raw Markdown text
4. This is useful for copying content, viewing the source format, or using with tools that process Markdown

You can download the entire documentation as a single Markdown file for offline reading or integration into other tools.

1. Click the "AI-Friendly Options" dropdown in the left navigation
2. Select "Download as Markdown"
3. The file agntux_docs.md will be downloaded
4. Use it in your preferred Markdown reader, documentation tool, or version control system

The downloaded file includes a table of contents and all content organized in the same order as the website.

AgntUX is an AI agent designed to help users plan, design, build, and deploy ChatGPT Apps and MCP Apps.

AgntUX simplifies the process of creating interactive AI applications by providing:

• Planning assistance - Help structure your app idea and requirements
• Design assistance - AgntUX designs the UI based on your design guidelines
• Build support - Code generation and implementation help
• Deployment tools - Full app deployment and hosting infrastructure

Whether you're building a ChatGPT App, an MCP App, or a single app that works as both, AgntUX aims to make the entire development lifecycle smoother and more accessible.

AgntUX is currently in private beta. We're working hard to refine the product and prepare for a public launch.

Interested in being among the first to use AgntUX? Join our waitlist to be notified when we launch publicly!

Simply click the "Join Waitlist" button in the top navigation bar, enter your email address (and optionally your name), and we'll notify you as soon as AgntUX becomes available.

We're excited to help you build the next generation of AI applications!

This section defines key terms and concepts used throughout this documentation related to agentic apps, ChatGPT Apps, and MCP Apps.

An agentic app is an interactive application that uses AI agents to perform tasks, make decisions, and interact with users through natural language and rich user interfaces. Agentic apps combine conversational AI capabilities with interactive UI components to create seamless user experiences.

A host is an AI application or platform that can run and display ChatGPT Apps or MCP Apps. Hosts provide the runtime environment, user interface framework, and communication protocols needed for apps to function. Examples include ChatGPT, Nanobot, Claude Desktop, and other MCP-compatible applications.

A ChatGPT App is an interactive application built using the OpenAI Apps SDK that runs within ChatGPT. These apps provide rich, interactive user interfaces and can integrate with external services through tools and resources. ChatGPT Apps are designed specifically for OpenAI's ChatGPT platform and follow OpenAI's guidelines and policies.

Key characteristics:

• Built with the OpenAI Apps SDK
• Runs within ChatGPT
• Uses MCP as its backbone protocol
• Must be submitted to OpenAI for approval before public release

An MCP App is an interactive application built using the MCP Apps Extension (SEP-1865) that can work across multiple MCP-compatible hosts. Unlike ChatGPT Apps, MCP Apps are platform-agnostic and can run on any host that supports the MCP Apps Extension standard.

Key characteristics:

• Built using the MCP Apps Extension (SEP-1865)
• Works across multiple MCP-compatible hosts
• Uses standardized UI resource declarations
• Deploy once, work everywhere (with host support)

MCP-UI was the original name for what is now called MCP Apps. The MCP-UI project was created by Ido Salomon and Liad Yosef as an open-source initiative to enable rich, interactive user interfaces in MCP servers. The concepts and patterns from MCP-UI were later standardized as the MCP Apps Extension (SEP-1865). Apps built with MCP-UI are compatible with the MCP Apps Extension standard.

MCP (Model Context Protocol) is an open protocol that enables AI assistants to securely access external data sources and tools. MCP provides a standardized way for AI applications to interact with external systems, databases, APIs, and services.

Key features:

• Secure communication between AI assistants and external systems
• Standardized tool and resource definitions
• Support for multiple programming languages
• Extensible architecture

An MCP server is an application that implements the MCP protocol to expose tools, resources, and prompts to MCP clients (hosts). MCP servers can provide access to databases, APIs, file systems, or any other external system that AI assistants need to interact with.

An MCP client is an application that connects to MCP servers to access their tools and resources. Hosts like ChatGPT, Claude Desktop, and Nanobot act as MCP clients when they connect to MCP servers.

The MCP Apps Extension (also known as SEP-1865) is a standardized extension to the MCP protocol that enables interactive user interfaces. It defines how UI components are declared, how tools link to UI resources, and how bidirectional communication works between UI components and hosts.

Key components:

• UI Resource Declarations (ui:// URI scheme)
• Tool-to-UI Linking
• Bidirectional Communication
• Security Model (sandboxed iframes)

A tool is a function or capability exposed by an MCP server that an AI assistant can call to perform actions or retrieve information. Tools are defined with names, descriptions, and input schemas that help AI assistants understand when and how to use them.

A resource is data or content exposed by an MCP server that an AI assistant can read or reference. Resources can include files, database records, API responses, or UI components (in the case of MCP Apps).

A UI resource is a special type of resource in MCP Apps that declares an interactive user interface component. UI resources use the ui:// URI scheme and are linked to tools through metadata, enabling rich, interactive experiences in agentic apps.

A prompt is a template or instruction that an MCP server can provide to help guide AI assistant behavior. Prompts can include context, examples, or structured instructions for specific tasks.

An SDK (Software Development Kit) is a collection of tools, libraries, and documentation that helps developers build applications for a specific platform or protocol. Examples include the OpenAI Apps SDK for ChatGPT Apps and the MCP SDK for building MCP servers.

The OpenAI Apps SDK is the official development kit for building ChatGPT Apps. It provides the tools, libraries, and APIs needed to create interactive applications that run within ChatGPT.

Apps SDK is an alternative name for the OpenAI Apps SDK, used in some contexts to refer to the development kit for ChatGPT Apps.

SEP-1865 is the proposal number for the MCP Apps Extension standard. SEP stands for "Standard Extension Proposal" and is part of the MCP protocol's standardization process. The proposal defines how interactive UI components work within the MCP ecosystem.

Standardization refers to the process of creating official specifications and protocols that ensure interoperability across different implementations. The MCP Apps Extension was standardized through collaboration between Anthropic, OpenAI, and the MCP-UI team.

Interoperability is the ability of different systems, platforms, or applications to work together seamlessly. MCP Apps are designed for interoperability, allowing the same app to work across multiple MCP-compatible hosts.

Platform-agnostic describes software or applications that are not tied to a specific platform or vendor. MCP Apps are platform-agnostic, meaning they can work with any host that supports the MCP Apps Extension, not just one specific platform.

Sandboxed refers to an execution environment that isolates code from the rest of the system for security purposes. In MCP Apps, UI components run in sandboxed iframes to prevent malicious code from accessing sensitive data or system resources.

This definitions page is automatically updated by our AI agent as new terms and concepts emerge in the agentic apps ecosystem.

This section provides links to official documentation, community resources, development tools, and other helpful materials for building ChatGPT Apps and MCP Apps.

• MCP Specification - Official MCP protocol documentation
• MCP Apps Extension (SEP-1865) - Proposal for MCP Apps Extension
• MCP GitHub Repository - Official MCP repositories and examples

• OpenAI Apps Documentation - Official OpenAI Apps SDK documentation
• Introducing Apps in ChatGPT - Announcement and overview of ChatGPT Apps

• MCP-UI Documentation - Community-maintained documentation for MCP-UI
• MCP-UI Supported Hosts - List of hosts supporting MCP Apps
• MCP-UI Team - Information about the MCP-UI creators (Ido Salomon and Liad Yosef)

• @modelcontextprotocol/sdk - Official TypeScript/JavaScript MCP SDK
• MCP-UI TypeScript SDKs - Community TypeScript tools

• MCP Python SDK - Official Python SDK for MCP

• MCP Ruby SDK - Official Ruby SDK for MCP

For detailed information about supported hosts, including feature support levels and documentation links, see the Supported Hosts section.

• MCP GitHub Discussions - Official MCP community discussions
• Stack Overflow - MCP Tag - MCP-related questions and answers

• MCP Servers - Collection of example MCP servers
• MCP-UI Examples - Example MCP-UI implementations
• AgntUX Docs - This documentation repository (contribute here!)

• MCP Blog - Official MCP blog with announcements and guides
• OpenAI Blog - OpenAI announcements and updates

• MCP-UI Guides - Getting Started Guides
• MCP Examples - Browse example implementations in the MCP Servers repository

• GitHub Issues - Report bugs or request features in relevant repositories
• Community Forums - Ask questions in community discussion forums
• Documentation Issues - File issues for this documentation

• Follow the MCP Blog for protocol updates
• Monitor OpenAI Announcements for ChatGPT Apps news
• Watch the MCP GitHub Organization for new repositories and releases

• Contribute to AgntUX Docs - Help improve this documentation
• Contribute to MCP - Contribute to the MCP protocol and tools
• Contribute to MCP-UI - Help improve MCP-UI tools and documentation

This resources page is automatically updated by our AI agent. If you notice any broken links or have suggestions for additional resources, please open an issue or submit a pull request.

This section provides an overview of where things currently stand with the development of ChatGPT Apps and MCP Apps, what's possible to build today, and what's coming next.

ChatGPT Apps are interactive applications that run within ChatGPT, providing rich user interfaces and specialized functionality. As of late 2025, developers can:

• Build apps using the OpenAI Apps SDK
• Create interactive UIs with HTML/CSS/JavaScript
• Deploy apps that integrate with ChatGPT's conversational interface
• Submit apps for review (OpenAI plans to begin accepting submissions before the end of 2025)

MCP Apps are applications built on the Model Context Protocol that can work across multiple AI host applications. Currently, you can:

• Build MCP servers that expose tools and resources
• Create interactive UI components using the MCP Apps Extension (SEP-1865)
• Deploy apps that work with various MCP-compatible hosts
• Use standardized patterns for UI resources and tool integration

Both ChatGPT Apps and MCP Apps are in active development, with new features and capabilities being added regularly. The ecosystem is rapidly evolving as more companies and open-source projects contribute to the standards and tooling.

Understanding how we got to where we are today helps contextualize the current state of ChatGPT Apps and MCP Apps.

The journey began with MCP-UI, an open-source project created by Ido Salomon and Liad Yosef. This project pioneered the concept of delivering rich, interactive user interfaces as first-class MCP resources.

MCP-UI demonstrated that:

• UI components could be natural extensions of MCP servers
• Interactive interfaces could be delivered as resources
• Agentic apps could fit seamlessly within the MCP architecture

The project gained significant community support and was adopted by leading companies including Postman, Shopify, Hugging Face, Goose, and ElevenLabs.

The OpenAI Apps SDK further validated the demand for rich UI experiences within conversational AI interfaces. The Apps SDK is largely based on MCP-UI, with OpenAI building their platform using MCP as its backbone and adopting the patterns and concepts pioneered by the MCP-UI project.

To enable interoperability between MCP-UI apps and ChatGPT, the MCP-UI team built an adapter that allows MCP-UI HTML widgets to run inside ChatGPT. The Apps SDK adapter in @mcp-ui/server automatically translates MCP-UI primitives to Apps SDK compatible code, enabling developers to build apps that work with both MCP-UI hosts and ChatGPT without requiring separate implementations.

This adoption by a major platform provider signaled strong industry interest and helped establish UI capabilities as a core feature rather than an experimental add-on.

To ensure interoperability and establish consistent security and usage patterns across the ecosystem, Anthropic, OpenAI, and the MCP-UI team collaborated to create an official MCP extension for interactive interfaces.

This collaboration resulted in SEP-1865: MCP Apps Extension, which standardizes:

• UI resource declarations
• Tool-to-UI linking patterns
• Bidirectional communication between embedded interfaces and host applications
• Security models for hosting interactive content

The general progression has been:

1. November 2024: Model Context Protocol (MCP) introduced by Anthropic
2. Late 2024 - Early 2025: MCP-UI project launches, proving the concept of interactive UIs in MCP
3. Early 2025: Community adoption grows, major companies integrate MCP-UI
4. March 2025: OpenAI adopts MCP, integrating it across ChatGPT desktop app, Agents SDK, and Responses API
5. November 2025: OpenAI announces Apps SDK at Dev Day conference
6. November 2025: MCP Apps Extension proposal (SEP-1865) published, standardizing the approach
7. 2025 (Ongoing): Standardization work continues, more hosts add support

The collaboration between MCP-UI creators, OpenAI, and Anthropic represents a commitment to building an open, interoperable ecosystem. This foundation will enable developers to build apps that work across multiple platforms while maintaining consistent patterns and security models.

MCP Apps and UI-enabled MCP servers are supported by a growing number of MCP-compatible hosts. Feature support is constantly expanding as the ecosystem matures.

• Focus: OpenAI's conversational AI platform that supports ChatGPT Apps and MCP servers
• Documentation: OpenAI Platform

• Focus: AI coding assistant focused on software development and code generation
• Documentation: Nanobot Documentation

• Focus: API development and testing platform with MCP integration for API workflows
• Documentation: Postman MCP Documentation

• Focus: AI assistant platform designed for productivity and workflow automation
• Documentation: Goose Documentation

• Focus: Open-source ChatGPT alternative with support for multiple AI providers and MCP servers
• Documentation: LibreChat Documentation

• Focus: AI agent platform focused on building and deploying conversational AI applications
• Documentation: Smithery Documentation

• Focus: Development environment and playground for testing and building MCP applications
• Documentation: MCPJam Documentation

• Focus: Fast, lightweight AI agent framework for building and running MCP-compatible applications
• Documentation: fast-agent GitHub

• Focus: Popular code editor with planned MCP Apps support
• Status: Support planned (TBA)

Legend:

• ✅: Fully Supported
• ⚠️: Partial Support
• ❌: Not Supported (yet)
• ?: Status Unknown

Hosts with full support can:

• Render interactive UI components from MCP servers
• Handle UI-initiated tool calls and actions
• Support bidirectional communication between UI and host

Hosts with partial support can:

• Render UI components and display interactive interfaces
• May have limitations on UI-initiated actions
• May require additional configuration or have specific constraints

Hosts with rendering-only support can:

• Display UI components visually
• Cannot handle interactive actions from the UI
• Useful for visualization and display purposes

For the most up-to-date information on host support, visit:

• MCP-UI Supported Hosts
• Individual host documentation
• MCP community discussions

Building ChatGPT Apps and MCP Apps involves understanding both the underlying protocols and the tools available for development.

Before you begin building, you should have:

• Basic understanding of web development (HTML, CSS, JavaScript)
• Familiarity with REST APIs and JSON
• Understanding of the Model Context Protocol (MCP) basics
• Development environment set up (Node.js, Python, or Ruby depending on your chosen SDK)

Various SDKs and tools are available. For a complete list with links to official documentation and repositories, see the Development Tools & SDKs section in Resources.

Available SDKs:

• TypeScript SDKs - For Node.js/TypeScript development
• Python SDKs - For Python-based development
• Ruby SDKs - For Ruby development
• MCP-UI SDKs - Community-maintained tools with rich UI support

The following sections will cover:

• Setting up your development environment
• Creating your first app
• Building interactive UIs
• Integrating with tools and resources

The fundamental difference between traditional web/mobile apps and ChatGPT/MCP Apps is the ownership of the user experience.

In traditional apps:

• The app is the primary interface
• The app controls the entire user experience
• Users interact directly with the app

In ChatGPT/MCP Apps:

• The AI agent host (ChatGPT, Claude, etc.) is the primary owner of the user's experience
• The app's role is to supplement and enhance the host's ability to help the user
• The app provides richer interactions than text-only responses, but doesn't take over the entire experience
• Apps work within the conversational context provided by the host

Key principle: Apps should feel like natural extensions of the host's conversation, not separate applications that interrupt the flow. The intention is not for the app to completely take over the user's experience, but rather to enable the host to provide a richer UX than is possible with text only.

ChatGPT Apps and MCP Apps run inside sandboxed iframes for security and isolation. This architecture provides a controlled environment where apps can execute safely while maintaining clear boundaries.

Communication Model:

• Apps and hosts communicate through a defined set of events that can be passed in both directions
• Events use the standard MCP JSON-RPC protocol over postMessage
• All communication is structured, auditable, and follows consistent patterns

Common Event Types:

1. Tool Call Events - Apps can request the host to execute tools with specific parameters
2. Intent Events - Apps communicate user intentions or actions to the host
3. Prompt Events - Apps can request the host to display prompts or confirmations to the user
4. Notification Events - Apps send status updates or notifications to the host
5. Link Events - Apps can request the host to open URLs or navigate

Host-to-App Communication:

• Hosts can send data and updates to apps
• Hosts can trigger app state changes
• Hosts provide context about the conversation and user

App-to-Host Communication:

• Apps can request tool executions
• Apps can send user interaction data
• Apps can request user confirmations or prompts

This bidirectional event system enables rich, interactive experiences while maintaining security and allowing the host to remain in control of the overall user experience.

For detailed information about event handling and communication patterns, see the MCP-UI documentation and the MCP Apps Extension proposal (SEP-1865).

It's possible to build a single app that works on both ChatGPT and MCP-compatible hosts by using the MCP-UI SDK. The MCP-UI team has built an Apps SDK adapter that enables MCP-UI HTML widgets to run inside ChatGPT while maintaining compatibility with traditional MCP hosts.

Key benefits:

• Write once, deploy to multiple platforms
• Use the same codebase for both ChatGPT Apps and MCP Apps
• The adapter automatically translates MCP-UI primitives to Apps SDK compatible code
• No HTML changes required - the bridge handles the translation

How it works:

• Create a static template with the Apps SDK adapter enabled for ChatGPT
• Return standard MCP-UI embedded resources for MCP-native hosts
• The adapter switches the MIME type to text/html+skybridge and injects the Apps bridge script automatically

For detailed instructions, see the MCP-UI Apps SDK Integration guide.

Note: If you want your app to work on both ChatGPT and MCP hosts, consider using the MCP-UI SDK with the Apps SDK adapter instead of building a platform-specific app.

ChatGPT Apps are interactive applications that run within ChatGPT, providing specialized functionality and rich user interfaces.

ChatGPT Apps allow developers to create interactive experiences directly within ChatGPT. These apps can:

• Provide specialized tools and capabilities
• Display rich, interactive user interfaces
• Integrate with external services and APIs
• Enhance ChatGPT's functionality for specific use cases

For more information, see OpenAI's introduction to Apps in ChatGPT.

The OpenAI Apps SDK provides the foundation for building ChatGPT Apps. It uses MCP as its backbone and enables:

• UI component creation
• Tool integration
• Resource management
• Communication with ChatGPT

ChatGPT Apps support interactive UI built with standard web technologies:

• HTML for structure
• CSS for styling
• JavaScript for interactivity
• Standard browser APIs (with security restrictions)

Apps integrate with ChatGPT through:

• Tools - Functions that the app can call
• Resources - Data and content the app can access
• UI Resources - Interactive interfaces displayed to users

1. Plan your app - Define functionality and user experience
2. Set up development environment - Install SDK and dependencies
3. Build UI components - Create interactive interfaces
4. Implement tools - Add backend functionality
5. Test locally - Use development tools to test your app
6. Prepare for submission - Follow OpenAI's guidelines
7. Submit for review - When submission process opens (before end of 2025)

• Apps must follow OpenAI's guidelines and policies
• UI is built using standard web technologies (HTML/CSS/JavaScript)
• Apps integrate with ChatGPT's conversational interface
• Submission process will be available before end of 2025

• Design for conversational context - Apps should feel natural within ChatGPT
• Provide clear user feedback - Interactive elements should be responsive
• Handle errors gracefully - Show helpful error messages
• Follow security guidelines - Ensure your app is secure and respects user privacy
• Optimize performance - Keep UI responsive and efficient

MCP Apps are applications built on the Model Context Protocol that can work across multiple AI host applications, providing a standardized way to create interactive AI experiences.

MCP Apps leverage the MCP Apps Extension (SEP-1865) to deliver interactive user interfaces. These apps can:

• Work across multiple MCP-compatible hosts
• Provide consistent experiences regardless of host
• Use standardized patterns for UI and tool integration
• Deploy once, work everywhere (with host support)

For more information, see the MCP Apps Extension proposal.

The MCP Apps Extension standardizes:

• UI Resource Declarations - Templates with ui:// URI scheme
• Tool-to-UI Linking - Connecting tools to their UI components
• Bidirectional Communication - UI components can communicate with hosts via MCP JSON-RPC
• Security Model - Sandboxed iframes and pre-declared templates

UI templates are declared as resources:

{
  uri: "ui://my-app/dashboard",
  name: "Dashboard View",
  mimeType: "text/html+mcp"
}

Tools reference these resources in their metadata:

{
  name: "show_dashboard",
  _meta: {
    "ui/resourceUri": "ui://my-app/dashboard"
  }
}

UI components communicate with hosts using the standard MCP JSON-RPC protocol over postMessage, ensuring:

• Structured, auditable communication
• Compatibility with existing MCP features
• Standard SDK usage (@modelcontextprotocol/sdk)

1. Design your app - Plan functionality and UI components
2. Set up MCP server - Create server with tool and resource definitions
3. Create UI templates - Build HTML interfaces for your components
4. Link tools to UI - Connect tools with their corresponding UI resources
5. Implement communication - Set up bidirectional messaging
6. Test with hosts - Verify compatibility across different hosts
7. Deploy - Make your app available

• Apps use the MCP Apps Extension (SEP-1865) for UI capabilities
• UI resources are declared and linked to tools
• Apps can work with any MCP-compatible host
• More flexible deployment options

MCP Apps Extension includes multiple security layers:

• Iframe Sandboxing - All UI runs in restricted iframes
• Pre-declared Templates - Hosts can review HTML before rendering
• Auditable Messages - All communication is logged
• User Consent - Hosts can require approval for UI-initiated actions

MCP Apps is an optional extension. Your apps should:

• Provide text-only fallbacks for all UI-enabled tools
• Return meaningful content even when UI is unavailable
• Work with both UI-capable and text-only hosts

Note: Using the MCP-UI SDK with the Apps SDK adapter allows your MCP App to also work in ChatGPT without requiring separate implementations.

Thorough testing is essential for ensuring your ChatGPT Apps and MCP Apps work correctly across different hosts and scenarios. Testing these apps can be challenging as it requires setting up hosts locally or running them in development mode.

Test individual components and functions in isolation:

• UI component rendering
• Tool function logic
• Data transformation
• Error handling

Test how components work together:

• Tool-to-UI communication
• Resource loading and rendering
• Host-to-app interactions
• End-to-end user flows

Since MCP Apps can work with multiple hosts, test your app with:

• Different host applications
• Various host capabilities (full support, partial support, rendering only)
• Different host configurations
• Host-specific behaviors

• Verify UI components display correctly in iframes
• Test responsive layouts across different host contexts
• Check styling and theming compatibility
• Validate accessibility features
• Test UI rendering in hosts with different support levels

• Test tool calls with various inputs and parameters
• Verify error handling for invalid inputs
• Check response formatting and structure
• Validate data transformations
• Test tool execution through different hosts
• Verify tool-to-UI linking works correctly

• Test UI-to-host messaging via postMessage
• Verify host-to-UI updates and state changes
• Check bidirectional communication flows
• Validate message formatting (JSON-RPC protocol)
• Test event handling (tool calls, intents, prompts, notifications)
• Verify communication security and sandboxing

• Test with invalid inputs and malformed requests
• Verify error message display in UI
• Check fallback behaviors when UI is unavailable
• Validate recovery mechanisms
• Test network failures and timeout scenarios
• Verify graceful degradation to text-only mode

• Test iframe sandboxing restrictions
• Verify pre-declared template validation
• Check message auditing and logging
• Test user consent flows for UI-initiated actions
• Validate authentication and authorization
• Test against common security vulnerabilities

Most SDKs provide development tools for local testing:

• TypeScript/Node.js SDKs: Use @modelcontextprotocol/sdk with local server setup
• Python SDKs: Run MCP servers locally with development mode enabled
• Ruby SDKs: Use local server runners for testing

• Preview UI components in isolation
• Test styling and layout without full host integration
• Debug CSS and JavaScript issues
• Validate responsive design

• Use browser developer tools to inspect iframe content
• Monitor postMessage communication
• Inspect JSON-RPC requests and responses
• Debug tool execution and resource access
• Use network tab to monitor API calls

• Create mock hosts for isolated testing
• Simulate different host capabilities
• Test error scenarios and edge cases
• Validate backward compatibility

• Test early and often - Don't wait until the end; test as you build
• Test across hosts - Ensure compatibility with all target hosts
• Test error cases - Handle failures gracefully with clear error messages
• Test performance - Keep apps responsive and optimize loading times
• Test accessibility - Ensure usability for all users
• Test locally first - Use local development tools before testing with actual hosts
• Use HTTPS for local testing - Tools like ngrok are essential for ChatGPT testing
• Test with different host support levels - Verify your app works with full, partial, and rendering-only hosts
• Maintain text-only fallbacks - Ensure your app works even when UI is unavailable
• Document your testing process - Keep notes on what works and what doesn't across different hosts

ChatGPT offers a Developer Mode that allows you to create, test, and deploy custom MCP connectors. This is the primary way to test ChatGPT Apps during development.

• Developer Mode is available for ChatGPT Business, Enterprise, and Education plans
• Your MCP server must be accessible over HTTPS (required for production, but can use tools like ngrok for local testing)

1. Access Settings:

   • Open ChatGPT and click on your profile icon
   • Navigate to Settings

2. Enable Developer Mode:

   • Within Settings, go to Apps & Connectors
   • Click on Advanced Settings
   • Toggle Developer Mode to the "On" position

1. In ChatGPT, navigate to Settings → Connectors
2. Click on Create to add a new connector

Provide the necessary metadata:

• Connector Name: A descriptive title (e.g., "Kanban Board")
• Description: A brief explanation of the connector's functionality
• Connector URL: The public /mcp endpoint of your server (e.g., https://abc123.ngrok.app/mcp)
• Choose the appropriate authentication method (e.g., OAuth) if required
• Click Create and verify the tools your server advertises

1. Open a new chat in ChatGPT
2. Click the "+" button near the message composer, select More, and choose your connector
3. Prompt ChatGPT to perform actions using the connector (e.g., "What are my available tasks?")
4. Review tool-call payloads in the UI to confirm inputs and outputs
5. For write tools, manual confirmation is required unless approvals are remembered for the conversation

After updating your MCP server:

1. In ChatGPT Settings → Connectors, select your connector and click Refresh
2. Verify tool list updates and test the updated flows

When testing locally, your MCP server must be accessible over HTTPS. Use one of these tools to expose your local server:

Create a secure tunnel to your local server:

ngrok http 3000

Use the provided HTTPS URL (e.g., https://abc123.ngrok.app) as your connector URL.

Alternative to ngrok for exposing local servers with Cloudflare's infrastructure.

1. Start your local MCP server on a local port (e.g., localhost:3000)
2. Expose the server using ngrok or Cloudflare Tunnel to get an HTTPS URL
3. Create a connector in ChatGPT Developer Mode using the HTTPS URL
4. Test your app by interacting with it through ChatGPT
5. Iterate and refresh - Make changes to your server and refresh the connector metadata

• Ensure your server is running and accessible
• Verify the ngrok tunnel is active
• Check that the URL in the connector matches your server endpoint

• Refresh the connector metadata after server changes
• Verify your server is returning tools in the correct format
• Check that the MCP protocol is implemented correctly

• Verify authentication configuration in connector settings
• Check that your server handles authentication correctly
• Ensure tokens are being passed properly

For detailed instructions, refer to OpenAI's documentation on connecting from ChatGPT.

MCP Apps can be tested using various tools and methods. This section covers the primary testing approaches for MCP Apps.

Postman is a versatile API client that allows you to test MCP servers by sending JSON-RPC requests directly to your endpoints.

1. Install and Configure:

   • Install Postman and open it
   • Create a new request and set the method to POST
   • Set the URL to your MCP server's endpoint (e.g., http://localhost:3000/mcp)

2. Configure Headers:

   • Add necessary headers:
     • Content-Type: application/json
     • Authentication tokens if required by your server

3. Configure Request Body:

   • Set the body type to raw and format to JSON
   • Create a JSON-RPC request following the MCP protocol:

     {
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/list",
       "params": {}
     }
     

4. Send Requests and Analyze:

   • Click Send to execute the request
   • Review the response status, headers, and body
   • Test various MCP methods (see Common MCP Methods below)

5. Automate Testing:

   • Use Postman's collection runner to automate a series of tests
   • Create test scripts to validate responses
   • Set up environments for different testing scenarios (local, staging, production)

• initialize - Establish connection with the server
• tools/list - Retrieve all available tools
• tools/call - Execute a tool with parameters
• resources/list - Get list of available resources
• resources/read - Read a specific resource
• prompts/list - List available prompts
• prompts/get - Get a specific prompt

Initialize Connection:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "postman-test",
      "version": "1.0.0"
    }
  }
}

List Tools:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Call a Tool:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "my_tool",
    "arguments": {
      "param1": "value1"
    }
  }
}

MCPJam is a specialized development environment and playground designed for testing and building MCP applications. It provides an interactive interface for testing MCP-UI apps.

1. Install and Configure:

   • Install MCPJam according to your development environment
   • Configure it to point to your MCP server's endpoint
   • Ensure your server is running and accessible

2. Create Test Scenarios:

   • Define test cases that cover different functionalities:
     • UI rendering tests
     • Tool execution tests
     • Resource access tests
     • Communication flow tests
     • Error handling tests

3. Execute Tests:

   • Run the test scenarios and monitor outputs in real-time
   • Observe UI components as they render
   • Verify tool calls and responses
   • Check bidirectional communication flows

4. Analyze Results:

   • Review logs and reports generated by MCPJam
   • Identify any issues or unexpected behaviors
   • Debug communication problems
   • Validate UI rendering across different scenarios

• Interactive UI testing environment
• Real-time MCP protocol inspection
• Visual debugging of UI components
• Support for testing multiple hosts
• Rendering-only mode for UI validation

For more information, see the MCPJam Documentation.

In addition to Postman and MCPJam, you can test your MCP Apps with various MCP-compatible hosts. Each host may have different levels of support, so testing across multiple hosts is important.

• Support Level: Full support for MCP Apps (rendering and UI actions)
• Use Cases:
  • Test complete app functionality
  • Verify tool execution and UI interactions
  • Test bidirectional communication
• Documentation: Nanobot Documentation

• Support Level: Partial support (rendering and basic interactions)
• Use Cases:
  • Test UI rendering
  • Verify basic tool functionality
  • Test with productivity-focused host
• Documentation: Goose Documentation

• Support Level: Partial support
• Use Cases:
  • Test compatibility with open-source ChatGPT alternative
  • Verify multi-provider support
  • Test in self-hosted environment
• Documentation: LibreChat Documentation

• Support Level: Rendering only
• Use Cases:
  • Test UI rendering without interactive features
  • Verify fallback behaviors
  • Test in conversational AI context
• Documentation: Smithery Documentation

• Support Level: Rendering only
• Use Cases:
  • Test lightweight agent framework
  • Verify basic rendering capabilities
  • Test performance in minimal environment

Test with hosts that have different support levels:

• Full Support: Test complete functionality (e.g., Nanobot)
• Partial Support: Verify compatibility and graceful degradation (e.g., Goose, LibreChat)
• Rendering Only: Ensure fallbacks work correctly (e.g., Smithery, MCPJam)

Ensure your app:

• Provides text-only fallbacks for all UI-enabled tools
• Returns meaningful content even when UI is unavailable
• Works with both UI-capable and text-only hosts
• Handles missing features gracefully

Test error scenarios:

• Network failures
• Invalid tool calls
• Missing resources
• Host-specific limitations
• Authentication failures

1. Start with Postman - Test basic MCP protocol functionality
2. Use MCPJam - Test UI rendering and interactions
3. Test with Multiple Hosts - Verify compatibility across different hosts
4. Test Error Cases - Ensure graceful handling of failures
5. Validate Fallbacks - Confirm text-only mode works correctly

OpenAI plans to begin accepting submissions for ChatGPT Apps before the end of 2025. This section covers what you need to know about the release process.

While the exact submission process details are still being finalized, you should prepare for:

• Complete development - Your app should be fully functional
• Thorough testing - Test all features and edge cases
• Documentation - Prepare clear documentation for reviewers
• Compliance - Ensure your app follows OpenAI's policies and guidelines
• Privacy and security - Verify data handling and security measures

The submission process will likely include:

• Application form with app details
• Code review and security audit
• Functionality testing by OpenAI
• Policy compliance verification
• Approval or feedback for improvements

Before submitting, ensure your ChatGPT App:

• Follows OpenAI's usage policies
• Respects user privacy and data protection
• Implements proper security measures
• Provides clear user value
• Has appropriate error handling
• Includes helpful user documentation

Once approved:

• Your app will be available in ChatGPT
• Users can discover and use your app
• You'll receive usage analytics
• You can iterate based on user feedback

• Before end of 2025: OpenAI begins accepting submissions
• Ongoing: Review and approval process
• Post-approval: Apps go live in ChatGPT

Stay tuned for official announcements from OpenAI regarding the exact submission process and timeline.

MCP Apps can be released as hosts build support for the MCP Apps Extension features. The release process is more flexible than ChatGPT Apps since MCP Apps work across multiple platforms.

MCP Apps become available as individual hosts add support:

• Full support hosts - Your app works with full UI and action capabilities
• Partial support hosts - Your app works with limited features
• Rendering-only hosts - Your app displays but with limited interactivity

MCP Apps are served via an MCP server. The MCP server acts as the backend that handles requests and serves the app's UI resources, tools, and functionality to MCP-compatible hosts. You can deploy your MCP server (which serves your app) through various methods:

Server Deployment Methods:

• Remote Deployments - Host your MCP server externally (cloud providers, third-party services). Clients connect over HTTPS using a provided URL. This offers quick setup, scalability, and centralized maintenance.

• Managed Deployments - Deploy your MCP server within managed infrastructure:

  • Managed-Dedicated - Each user/agent has their own container instance for isolation
  • Managed-Shared - Multiple users/agents share a single container instance for resource efficiency

• Workstation Deployments - Install and run the MCP server locally on a user's machine. Useful when the server needs access to local files or programs.

Distribution Methods:

• Public repositories - Share your MCP server code via GitHub, GitLab, etc.
• Package registries - Publish server code via npm, PyPI, RubyGems (for SDKs)
• Direct distribution - Share server code directly to users
• MCP registries - Community-maintained app directories (as they emerge)

Key Point: Users install and run your MCP server, which then serves your app to MCP-compatible hosts. The server exposes tools, resources, and UI templates that hosts can discover and use.

Before releasing your MCP App:

• Documentation - Clear setup and usage instructions
• Examples - Working examples and demos
• Compatibility - List of supported hosts
• Installation - Simple installation process
• Configuration - Clear configuration options
• Support - Way for users to get help (issues, discussions, etc.)

Consider versioning your MCP App:

• Follow semantic versioning (major.minor.patch)
• Document breaking changes
• Provide migration guides
• Maintain backward compatibility when possible

This changelog tracks updates to the AgntUX documentation, including new content, improvements, and updates based on the latest developments in ChatGPT Apps and MCP Apps.

When adding new changelog entries, the following format is used. (Changelog entries are created automatically by an AI agent)

## [Date Range]

### Added
- **Feature/Content Name** - Brief description
  - [Article/Announcement Link](URL) (if available)
  - [PR #XX](https://github.com/agntux/docs/pull/XX) (if available)

### Updated
- **Section/Content Name** - Brief description of what was updated
  - [Reference Link](URL) (if available)
  - [PR #XX](https://github.com/agntux/docs/pull/XX) (if available)

### Removed
- **Content/Feature Name** - Brief description of what was removed
  - [PR #XX](https://github.com/agntux/docs/pull/XX) (if available)

• Added - New content, sections, or features added to the documentation
• Updated - Existing content that was revised, expanded, or improved
• Removed - Content that was deprecated or removed (use sparingly)

• Include links to relevant articles, announcements, or blog posts when available
• Always link to the PR where the documentation change was merged
• Use descriptive link text that indicates what the link contains

This section showcases real-world examples of ChatGPT Apps and MCP Apps that have been built and deployed. Each example is tagged to indicate which platform(s) it supports.

Examples are tagged to indicate which platform(s) they support:

• ChatGPT App - Built using the OpenAI Apps SDK and available in ChatGPT
• MCP App - Built using the MCP Apps Extension (SEP-1865) and works with MCP-compatible hosts
• Examples can have multiple tags if they support both platforms

Note: MCP-UI was the original name for what is now called MCP Apps. The name change occurred in November 2025 as part of the standardization process. Apps built with MCP-UI are compatible with the MCP Apps Extension standard.

When adding new examples, use the following format:

### [App Name] - [Brief Description]

**Tags:** `ChatGPT App` or `MCP App` or both

**Description:** Detailed description of the app and its purpose.

**Features:**
- Feature 1
- Feature 2
- Feature 3

**Announcement:**
- Date announced: YYYY-MM-DD (if available)
- [Announcement Link](URL) (if available)

**Status:** Current availability status

**Links:**
- [Documentation](URL) (if available)
- [Repository](URL) (if available)
- [Demo](URL) (if available)

If you know of a ChatGPT App or MCP App that should be featured here, please create a pull request with:

• Links to the app repository, documentation, or demo
• A brief description of the app's functionality
• Note which platform(s) it supports (ChatGPT App, MCP App, or both)
• Links to official announcements or documentation
• Date announced (if available)

Note: This section is automatically updated by our AI agent as new ChatGPT Apps and MCP Apps are announced and released. The examples listed here are based on publicly available information.

Tags: ChatGPT App

Description: Pizzaz is a pizza-inspired collection of interactive widgets and tools that demonstrate various Apps SDK patterns. It includes multiple widget types including a main pizza ordering interface, albums view, carousel, list view, and e-commerce shop modal.

Features:

• Interactive pizza ordering interface
• Multiple widget display patterns (albums, carousel, list, shop modal)
• Demonstrates tool calls and structured outputs
• Shows integration with MCP servers (both Node.js and Python implementations)
• Example of combining structured data with UI widgets

Announcement:

• Date announced: 2025-10-06
• Part of the OpenAI Apps SDK Examples repository
• OpenAI Apps SDK Examples Repository

Status: Open Source - Available as example code

Links:

• Repository
• Pizzaz Server (Node.js)
• Pizzaz Server (Python)

Tags: ChatGPT App

Description: A 3D interactive solar system viewer that demonstrates advanced visualization capabilities within ChatGPT Apps. Users can explore the solar system with an interactive 3D interface.

Features:

• 3D visualization of the solar system
• Interactive exploration of planets and celestial bodies
• Demonstrates complex UI rendering in iframe
• Example of rich media integration with Apps SDK

Announcement:

• Date announced: 2025-10-06
• Part of the OpenAI Apps SDK Examples repository
• OpenAI Apps SDK Examples Repository

Status: Open Source - Available as example code

Links:

• Repository
• Solar System Server (Python)

Tags: ChatGPT App

Description: A simple todo list widget that demonstrates basic task management functionality within ChatGPT Apps. Shows how to implement interactive lists and state management.

Features:

• Create, update, and delete todo items
• Interactive list management
• Demonstrates state persistence patterns
• Example of simple widget implementation

Announcement:

• Date announced: 2025-10-06
• Part of the OpenAI Apps SDK Examples repository
• OpenAI Apps SDK Examples Repository

Status: Open Source - Available as example code

Links:

• Repository

Tags: ChatGPT App

Description: Zillow created a ChatGPT App that helps users search for homes and get real estate information through natural conversation.

Features:

• Interactive home search with conversational interface
• Property details and neighborhood information
• Integration with Zillow's property database

Announcement:

• Date announced: 2025-11-06
• Featured at OpenAI's Dev Day conference in November 2025
• OpenAI Dev Day Announcement

Status: Available in ChatGPT

Links:

• OpenAI Dev Day Announcement

Tags: ChatGPT App

Description: Spotify's ChatGPT App allows users to create personalized playlists through natural conversation with ChatGPT.

Features:

• Create playlists based on listening history or specific themes
• Generate tailored playlists for events, moods, or activities
• Seamless integration with Spotify's music library

Announcement:

• Date announced: 2025-11-06
• Featured at OpenAI's Dev Day conference in November 2025
• OpenAI Dev Day Announcement

Status: Available in ChatGPT

Links:

• OpenAI Dev Day Announcement

Tags: ChatGPT App

Description: Canva's ChatGPT App enables users to design presentations, social media graphics, and other visual content directly within ChatGPT.

Features:

• Transform outlines into slide decks
• Create flyers, invitations, and social media graphics
• Interactive design tools within the chat interface

Announcement:

• Date announced: 2025-11-06
• Featured at OpenAI's Dev Day conference in November 2025
• OpenAI Dev Day Announcement

Status: Available in ChatGPT

Links:

• OpenAI Dev Day Announcement

Tags: ChatGPT App

Description: Booking.com's ChatGPT App allows users to plan and book travel accommodations seamlessly within ChatGPT.

Features:

• Search and book hotels and accommodations
• Plan travel itineraries through conversation
• Access Booking.com's extensive property database

Announcement:

• Date announced: 2025-11-06
• Featured at OpenAI's Dev Day conference in November 2025
• OpenAI Dev Day Announcement

Status: Available in ChatGPT

Links:

• OpenAI Dev Day Announcement

Tags: ChatGPT App

Description: Coursera's ChatGPT App enables users to access and enroll in online courses, with ChatGPT providing additional context and explanations.

Features:

• Browse and enroll in online courses
• Get explanations and elaborations on course content
• Access Coursera's course catalog through conversation

Announcement:

• Date announced: 2025-11-06
• Featured at OpenAI's Dev Day conference in November 2025
• OpenAI Dev Day Announcement

Status: Available in ChatGPT

Links:

• OpenAI Dev Day Announcement

Tags: ChatGPT App

Description: Expedia's ChatGPT App helps users organize and book complete travel itineraries, including flights and hotels, through conversational prompts.

Features:

• Book flights and hotels
• Plan complete travel itineraries
• Access Expedia's travel services within ChatGPT

Announcement:

• Date announced: 2025-11-06
• Featured at OpenAI's Dev Day conference in November 2025
• OpenAI Dev Day Announcement

Status: Available in ChatGPT

Links:

• OpenAI Dev Day Announcement

Tags: ChatGPT App

Description: Figma's ChatGPT App allows users to collaborate on design projects with interactive interfaces directly within ChatGPT.

Features:

• Design and prototype within ChatGPT
• Collaborate on design projects
• Access Figma's design tools through conversation

Announcement:

• Date announced: 2025-11-06
• Featured at OpenAI's Dev Day conference in November 2025
• OpenAI Dev Day Announcement

Status: Available in ChatGPT

Links:

• OpenAI Dev Day Announcement

Tags: MCP App

Description: Interactive sandbox environment for exploring and testing MCP-UI components.

Features:

• Hands-on experience with MCP-UI components
• Simulates tool calls and user interactions
• Debugging capabilities for message passing
• Live examples and demonstrations

Announcement:

• Date announced: Not available
• Part of the MCP-UI project

Status: Available as demo

Links:

• MCP-UI Demos
• MCP-UI GitHub Repository

This section provides solutions to common issues encountered when building ChatGPT Apps and MCP Apps. Each issue includes a summary, links to relevant resources, and information about contributors who helped resolve it.

When adding new troubleshooting entries, use the following format:

### [Issue Title]

**Summary:** Brief description of the problem and its symptoms.

**Solution:** Step-by-step solution or workaround.

**Resources:**
- [Link to relevant documentation](URL)
- [Link to GitHub issue or discussion](URL)
- [Link to Stack Overflow or forum post](URL)

**Reported by:** @username (if available)
**Date Reported:** YYYY-MM-DD (if available)
**Date Resolved:** YYYY-MM-DD (if available)
**Contributors:** @username1, @username2 (if available)

If you encounter an issue not listed here, please create a pull request with:

• A clear issue title and summary
• Step-by-step solution or workaround
• Error messages, logs, and steps to reproduce (if applicable)
• Links to relevant documentation, GitHub issues, or discussions
• Information about who reported the issue and contributors (if available)
• Date reported (if available)
• Date resolved (if available)

Note: This section is automatically updated by our AI agent as new issues are discovered and resolved. The troubleshooting entries are based on community reports, GitHub issues, and developer discussions.

Summary: The @modelcontextprotocol/ext-apps SDK sends ui/message requests with content as an array, but SEP-1865 specifies it as a single object. This causes hosts implementing strictly per SEP-1865 to fail when extracting text from SDK-generated ui/message requests.

Solution:

1. For app developers: Be aware that the SDK currently sends content as an array: content: [{ type: "text", text: "..." }]
2. For host developers: Handle both formats (array and object) until the SDK is updated to match the specification
3. Check the SDK version and monitor for updates that align with SEP-1865
4. As a workaround, hosts can check if content is an array and extract the first element if needed

Resources:

• GitHub Issue #48
• SEP-1865 Specification

Reported by: @chelojimenez Date Reported: 2025-11-27 Date Resolved: Not yet resolved Contributors: @chelojimenez

Summary: When importing createUIResource from @mcp-ui/server, TypeScript reports that the module has no exported member with that name, causing build errors.

Solution:

1. Check the version of @mcp-ui/server you're using - the export may have been renamed or moved
2. Verify the correct import path - it may be exported from a different module or subpath
3. Check the MCP-UI documentation for the current API
4. As a workaround, check if the function is available under a different name or import path
5. Update to the latest version of @mcp-ui/server if available

Resources:

• GitHub Issue #110
• MCP-UI Documentation

Reported by: @kdawgwilk Date Reported: 2025-09-19 Date Resolved: Not yet resolved Contributors: @kdawgwilk

Summary: When trying to connect an MCP server to ChatGPT Apps, developers encounter a "Connector is not safe" error that prevents the connection from being established.

Solution:

1. Ensure your MCP server is running and accessible
2. Verify the connector configuration in your ChatGPT App settings
3. Check that the MCP server URL is correct and uses HTTPS in production
4. Review OpenAI's connector safety requirements
5. Ensure the server implements proper security headers
6. Check if the error occurs in development mode - some safety checks may be stricter in production

Resources:

• GitHub Issue #115
• OpenAI Apps SDK Documentation

Reported by: @gbmarcos Date Reported: 2025-11-15 Date Resolved: Not yet resolved Contributors: @gbmarcos

Summary: When using a Python MCP server, the widget HTML fails to load even though the MCP inspector shows the server is working correctly. The UI component doesn't render in the host.

Solution:

1. Verify the MCP server is returning UI resources with the correct MIME type (text/html+mcp)
2. Check that the resource URI is properly formatted and accessible
3. Ensure the tool's _meta field includes "ui/resourceUri" pointing to the correct resource
4. Test the resource URL directly to ensure it's accessible
5. Check Python MCP server implementation against the MCP-UI examples
6. Verify the host supports UI rendering and is configured correctly
7. Use MCP inspector to verify the resource is being returned correctly

Resources:

• GitHub Issue #127
• MCP Inspector Documentation

Reported by: @Sateesh-karagana Date Reported: 2025-11-20 Date Resolved: Not yet resolved Contributors: @Sateesh-karagana

Summary: Calls to sendFollowUpMessage are being ignored by the host, causing follow-up messages not to appear in the conversation.

Solution:

1. Verify you're calling sendFollowUpMessage at the correct time in the app lifecycle
2. Check that the message format matches the expected structure
3. Ensure the app is in the correct state (e.g., not in a loading or error state)
4. Review the Apps SDK documentation for proper usage of sendFollowUpMessage
5. Check browser console for any errors that might indicate why the message is being ignored
6. Verify the host supports follow-up messages

Resources:

• GitHub Issue #126
• OpenAI Apps SDK Documentation

Reported by: @EAntropov-tofu Date Reported: 2025-11-19 Date Resolved: Not yet resolved Contributors: @EAntropov-tofu

Summary: When calling sendFollowUpMessage, the widget unexpectedly re-renders, causing UI flickering and potential loss of user input or state.

Solution:

1. Check if the re-render is caused by state changes triggered by the follow-up message
2. Implement proper state management to prevent unnecessary re-renders
3. Use React's useMemo or useCallback hooks to stabilize references if using React
4. Review the component lifecycle and ensure sendFollowUpMessage isn't triggering state updates
5. Check if the host is re-rendering the widget in response to the follow-up message
6. Consider debouncing or throttling follow-up message calls if they're being called frequently

Resources:

• GitHub Issue #129
• OpenAI Apps SDK Documentation

Reported by: @diegoquiroz-jpg Date Reported: 2025-11-24 Date Resolved: Not yet resolved Contributors: @diegoquiroz-jpg

Summary: When using UiResourceRendererWC with a text/uri-list resource, the ui-message-response is missing payload details that should be included.

Solution:

1. Verify the resource is properly formatted as text/uri-list
2. Check that the resource content includes all required payload information
3. Ensure the UiResourceRendererWC component is configured correctly
4. Review the MCP-UI documentation for proper text/uri-list resource format
5. Check if the issue is specific to certain hosts or occurs across all hosts
6. Verify the resource URI is accessible and returns the expected content

Resources:

• GitHub Issue #97
• MCP-UI Documentation

Reported by: @benjaminsattler Date Reported: 2025-08-28 Date Resolved: Not yet resolved Contributors: @benjaminsattler

Summary: The MCP-UI Client SDK encounters React version compatibility errors when used with the Goose host, causing the app to fail to render or function incorrectly.

Solution:

1. Check the React version requirements for the MCP-UI Client SDK
2. Verify the Goose host's React version matches SDK requirements
3. Update React to a compatible version if there's a mismatch
4. Check for peer dependency warnings during installation
5. Review the MCP-UI documentation for React version requirements
6. Consider using React version resolution in your package manager if using multiple React instances

Resources:

• GitHub Issue #90
• MCP-UI Documentation

Reported by: @aharvard Date Reported: 2025-08-19 Date Resolved: Not yet resolved Contributors: @aharvard

Summary: In development mode, the app container is missing a style class that affects mobile layout, causing layout issues on mobile devices that don't occur in production.

Solution:

1. Check if the missing style class is only absent in development mode
2. Verify your development environment matches production configuration
3. Add the missing style class manually in development if needed
4. Check if the issue is related to how the host renders apps in dev mode
5. Review the Apps SDK documentation for dev mode differences
6. Ensure your CSS includes styles for the app container that work in both dev and production
7. Test on actual mobile devices, not just browser dev tools

Resources:

• GitHub Issue #110
• OpenAI Apps SDK Documentation

Reported by: @zekebergida Date Reported: 2025-11-12 Date Resolved: Not yet resolved Contributors: @zekebergida

Summary: When an app transitions from Picture-in-Picture (PiP) or fullscreen mode back to inline mode, it retains the height from the previous mode instead of resetting to the appropriate inline height.

Solution:

1. Implement height reset logic when transitioning between display modes
2. Use the Apps SDK's display mode change events to detect mode transitions
3. Call notifyIntrinsicHeight with the correct height when returning to inline mode
4. Check if the host is properly handling height updates during mode transitions
5. Review the Apps SDK documentation for proper height management across display modes
6. Test mode transitions to ensure height is updated correctly

Resources:

• GitHub Issue #97
• OpenAI Apps SDK Documentation

Reported by: @gbmarcos Date Reported: 2025-11-05 Date Resolved: Not yet resolved Contributors: @gbmarcos

Summary: The MCP Apps Extension specification (SEP-1865) is missing display mode negotiation, making it unclear how apps and hosts should negotiate and communicate about display modes (inline, fullscreen, PiP).

Solution:

1. Monitor the SEP-1865 specification for updates on display mode negotiation
2. Check the MCP Apps Extension repository for discussions or proposals on this feature
3. For now, rely on host-specific implementations for display mode handling
4. Follow the Apps SDK approach if building for both platforms
5. Check GitHub issues and discussions for workarounds or proposed solutions

Resources:

• GitHub Issue #41
• SEP-1865 Specification

Reported by: @antonpk1 Date Reported: 2025-11-27 Date Resolved: Not yet resolved Contributors: @antonpk1

Summary: When trying to connect a ChatGPT App in business plan, developers encounter errors: "Failed to Load subscription" and "Failed to load connectors", preventing the app from being connected and used.

Solution:

1. Verify your OpenAI account has the necessary subscription tier (business plan or higher)
2. Check that your app is properly configured in the OpenAI platform
3. Ensure all required API keys and credentials are correctly set
4. Verify the connector configuration matches the expected format
5. Check for any account-level restrictions or limitations
6. Review OpenAI's documentation for business plan requirements
7. Contact OpenAI support if the issue persists after verifying configuration

Resources:

• GitHub Issue #128
• OpenAI Apps SDK Documentation

Reported by: @ashwinsekaran Date Reported: 2025-11-24 Date Resolved: Not yet resolved Contributors: @ashwinsekaran

Summary: On the ChatGPT mobile app, scrolling in fullscreen mode is very jittery, requiring many swipes to navigate through content. This affects the user experience on mobile devices.

Solution:

1. Check if the issue is specific to fullscreen mode or occurs in other display modes
2. Review your app's CSS for overflow and scrolling properties
3. Ensure proper touch event handling for mobile devices
4. Test scrolling performance with different content sizes
5. Check if the issue is related to how the host renders fullscreen apps on mobile
6. Consider implementing custom scroll handling if needed
7. Test on actual mobile devices, not just browser dev tools
8. Monitor for updates to the Apps SDK that may address mobile scrolling issues

Resources:

• GitHub Issue #111
• OpenAI Apps SDK Documentation

Reported by: @samhirtarif Date Reported: 2025-11-12 Date Resolved: Not yet resolved Contributors: @samhirtarif, @trylaarsdam

Summary: When in fullscreen mode, follow-up questions that should update the widget or display a new widget instead create an inline version, leaving the fullscreen widget unchanged. Users must exit fullscreen to see new results, limiting interactive chat experiences.

Solution:

1. Be aware that widget updates in fullscreen mode can be unreliable
2. Consider using a "universal" widget that shows different components based on structured output (though this may be an anti-pattern)
3. Even returning the same widget URL doesn't always update predictably
4. Monitor for SDK updates that improve fullscreen widget update behavior
5. As a workaround, implement custom state management to handle widget transitions
6. Consider informing users they may need to exit fullscreen to see updates
7. Check if the issue is specific to certain widget types or configurations

Resources:

• GitHub Issue #108
• OpenAI Apps SDK Documentation

Reported by: @dustfire Date Reported: 2025-11-11 Date Resolved: Not yet resolved Contributors: @dustfire, @henritoivar

Summary: When running an MCP server locally (e.g., on localhost:8000), accessing the root URL returns "Not Found" even though the server is running and MCP endpoints are accessible. This can cause confusion about whether the server is working correctly.

Solution:

1. Understand that MCP servers typically don't serve content at the root URL - this is expected behavior
2. The root URL returning "Not Found" is normal - MCP servers expose specific endpoints (e.g., /mcp for SSE stream)
3. Verify the server is working by checking the MCP-specific endpoints (e.g., /mcp for SSE, /mcp/messages for POST)
4. Use MCP Inspector or other MCP testing tools to verify server functionality
5. Don't expect a web UI at the root URL - MCP servers communicate via the MCP protocol, not HTTP web pages
6. Check server logs to confirm MCP endpoints are responding correctly

Resources:

• GitHub Issue #107
• MCP Inspector Documentation

Reported by: @ajayrathi2004 Date Reported: 2025-11-11 Date Resolved: Not yet resolved Contributors: @ajayrathi2004

Summary: The live demo on the MCP-UI website is not working, with all API calls returning 500 (Internal Server Error) status codes, preventing users from testing MCP-UI functionality.

Solution:

1. Check if the issue is temporary - demo services may experience outages
2. Try accessing the demo at a later time if it's a server-side issue
3. Check the MCP-UI repository for any announcements about demo availability
4. Consider setting up a local development environment to test MCP-UI instead
5. Monitor the GitHub issues for updates on demo status
6. Use alternative testing methods like MCP Inspector or local examples

Resources:

• GitHub Issue #145
• MCP-UI Documentation

Reported by: @ZiqiYe77 Date Reported: 2025-11-21 Date Resolved: Not yet resolved Contributors: @ZiqiYe77, @thecoder93