Deploy ChatGPT Apps

​

Requirements

• ChatGPT Apps developer access
• Deployed MCP server with unauthenticated access enabled (mcp-agent deploy ... --no-auth)
• Optional: frontend bundle (React, vanilla JS) if you want rich widgets; the bundle should have build output (JS, CSS) at web/build/static or web/dist/static

​

Recommended project structure

chatgpt-app/
├── main.py                    # MCP server (FastMCP or MCPApp)
├── web/                       # Front-end assets (React build)
│   ├── build/                 # React build (or dist) output
│   │   └── static/            # Built static resources (JS, CSS, etc.)
│   └── src/                   # Optional, your React source files
├── mcp_agent.config.yaml
└── requirements.txt

​

1. Build the widget assets

cd web
yarn install
yarn build          # Produces web/build/*
cd ..

​

2. Define widget metadata

from dataclasses import dataclass
from fastmcp import FastMCP, EmbeddedResource

@dataclass
class CoinFlipWidget:
    template_uri: str
    html: str

    def to_tool_annotations(self) -> dict:
        return {
            "openai/outputTemplate": self.template_uri,
            "openai/toolInvocation/invoking": [
                {"type": "text", "text": "Flipping the coin…"}
            ],
            "openai/toolInvocation/invoked": [
                {"type": "text", "text": "Heads or tails?"}
            ],
            "openai/widgetAccessible": True,
            "openai/resultCanProduceWidget": True,
        }

​

3. Deploy with --no-auth

mcp-agent deploy chatgpt-coin-flip \
  --app-description "Coin flip widget for ChatGPT Apps" \
  --no-auth

SERVER_URL = "https://<app_id>.deployments.mcp-agent.com"
COIN_FLIP_WIDGET = CoinFlipWidget(
    template_uri=f"ui://widget/coin-flip-{DATE_STAMP}.html",
    html=DEPLOYED_HTML_TEMPLATE.replace("{{SERVER_URL}}", SERVER_URL),
)

​

4. Register the action in ChatGPT Apps

1. Open developers.openai.com/apps.
2. Create or open your app, then add a new Action.
3. Choose MCP as the action type.
4. Provide the server URL (https://<app_id>.deployments.mcp-agent.com). <app_id> matches the hostname shown in the deployment output (for example, app_abc123xyz).
5. Select Server-Sent Events as the transport (all mcp-agent cloud deployments currently expose SSE endpoints).
6. Save and test—ChatGPT will list available tools (coin-flip) and display widgets declared via annotations.

​

5. Iterate on the widget

• Cache busting – update template_uri (include a timestamp or semantic version) whenever you change the HTML so ChatGPT fetches the new template.
• State – return structured data from the tool. The client-side widget receives this in state.result.
• Accessibility – provide meaningful openai/toolInvocation strings and fallback text for users who cannot render widgets.

​

6. Optional enhancements

• Hybrid auth – combine a public endpoint with per-user rate limiting by inspecting request metadata (e.g., custom query params) inside your tool and calling your own auth service.
• Telemetry – use context.logger.info to log widget usage; stream via mcp-agent cloud logger tail.
• Publishing – once stable, add metadata (name, description, icon) when you create the ChatGPT App so users can discover it in the directory.

​

Troubleshooting

​

Resources

• ChatGPT App example source
• OpenAI Apps SDK MCP documentation
• Deploying MCP servers →
• Authentication overview →