---
title: "把你的应用接入 ChatGPT"
description: "说明如何把产品接入 ChatGPT：先选明确用户结果，再设计少量 tools、MCP server 和可选 widget。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

把产品带进 ChatGPT，不应该从“把整个产品搬进去”开始。更稳的做法是先选一个明确用户结果，围绕它设计少量 tools，搭建 MCP server，必要时再做 widget，然后在 ChatGPT developer mode 里验证核心流程。

> [!IMPORTANT]
> ChatGPT app 的 v1 目标要窄：一个用户结果、少量 tools、清楚 metadata、可验证的本地 HTTPS 测试路径。

<Cards>
  <Card title="ChatGPT apps" href="https://developers.openai.com/codex/use-cases/chatgpt-apps">
    官方 Codex ChatGPT app 场景。
  </Card>
  <Card title="Apps SDK quickstart" href="https://developers.openai.com/apps-sdk/quickstart">
    当前 Apps SDK 构建入口。
  </Card>
  <Card title="MCP server" href="https://developers.openai.com/apps-sdk/build/mcp-server">
    先定义 tools 和 server contract，再做 widget。
  </Card>
</Cards>

## 构成

```mermaid
flowchart LR
    Outcome["core user outcome"] --> Tools["3-5 tools"]
    Tools --> MCP["MCP server"]
    MCP --> Widget["optional widget"]
    Widget --> Test["developer mode testing"]
    MCP --> Test
```

每个 ChatGPT app 通常由三部分组成：

- MCP server：定义 tools、返回数据、处理账号连接，并指向 ChatGPT 需要加载的 UI resources。
- 可选 web component：在 ChatGPT iframe 中渲染，可以用 React，也可以用轻量 HTML/CSS/JS。
- model-driven tool calls：模型根据 metadata 决定何时调用 app tools。

Codex 适合负责：

- 规划 tool surface 和 metadata。
- scaffold server 和 widget。
- 接好 local run scripts。
- 分阶段加入 auth 和 deployment。
- 写验证 loop，证明 app 在 ChatGPT 里能工作。

## 起始提示词

```text
请结合 ChatGPT Apps SDK 官方文档，在这个 repo 中为 [use case] 规划一个 ChatGPT app。

要求：
- 先锁定一个核心用户结果
- 提出 3-5 个 tools，每个 tool 都有名称、说明、inputs、outputs
- 判断 v1 是否需要 widget，还是可以先 data-only
- MCP server 优先按 repo 现有 TypeScript / Python 模式实现
- 标出 auth、deployment、test requirements

输出：
- Tool plan
- Proposed file tree
- Golden prompt set
- Risks and open questions
```

这个 prompt 只要求规划，不直接实现。先把 tools 和边界讲清楚，再 scaffold。

## 使用步骤

1. 从一个窄 outcome 开始，规划 3 到 5 个 tools。
2. 判断 v1 是否需要 widget。能 data-only 就先 data-only。
3. 按现有 repo patterns scaffold MCP server 和可选 widget。
4. 通过本地 HTTPS 路径运行，例如 ngrok 或 Cloudflare Tunnel。
5. 在 ChatGPT developer mode 里连接 app。
6. 用 small direct、indirect、negative prompt set 测试。
7. 迭代 metadata、state handling、`structuredContent` 和 `_meta` payloads。
8. 只有 user-specific data 或 write actions 需要时，再加入 OAuth。
9. 准备 hosted preview，保持稳定 `/mcp` endpoint。
10. 分享或提交前完成 launch checklist。

## Prompt 设计要点

强 prompt 通常包含：

- One clear outcome：app 要帮用户完成什么。
- Concrete stack：server 和 widget 使用什么技术栈。
- Explicit tool boundaries：每个 tool 只做一件事。
- Auth expectations：第一版是否 anonymous / read-only。
- Local development path：如何用 HTTPS 接入 ChatGPT。
- Verification steps：测哪些 prompts、回报哪些 evidence。

避免一个 prompt 同时要求 planning、implementation、auth、deployment、submission 和 polish。更稳的 milestone 是：

1. Plan the app before scaffolding。
2. Scaffold the first working version。
3. Add auth only after the core flow works。
4. Prepare deployment and review。

## Launch Readiness

上线前至少确认：

- app 只有一个用户一眼能看懂的窄 outcome。
- tool set 小而明确，metadata、inputs、outputs 都清楚。
- MCP server 能端到端工作，并返回简洁 `structuredContent`。
- widget-only data 放在 `_meta`，不要塞进对话正文。
- widget 如有必要，能在 ChatGPT 内正确渲染。
- 本地 HTTPS 测试 loop 能通过 developer mode 跑通。
- direct、indirect、negative prompt set 都按预期触发 conversation flow 和 tool payloads。
- 账号连接只加在 user-specific data 或 write actions 真正需要的地方。
- deployment plan 覆盖 metadata、tool hints、privacy 和 test prompts。

## 常见坑

- 让 Codex 把整个产品搬进 ChatGPT。
- 一个巨大 prompt 覆盖所有阶段。
- tool contract 还没清楚就写 UI。
- 不让 Codex 查当前官方 Apps SDK docs。
- metadata 最后才补。
- 核心 read flow 没通就加账号连接。
- 没在 ChatGPT 里测试就宣布完成。

## 官方资料

- [ChatGPT apps use case](https://developers.openai.com/codex/use-cases/chatgpt-apps)
- [Apps SDK quickstart](https://developers.openai.com/apps-sdk/quickstart)
- [Build an MCP server](https://developers.openai.com/apps-sdk/build/mcp-server)
- [Testing](https://developers.openai.com/apps-sdk/deploy/testing)
- [Codex skills](https://developers.openai.com/codex/skills)
