[Tracking] ChatGPT plugin: list docs.plus in the OpenAI Plugin Directory #388

Goal

List docs.plus in the OpenAI Plugin Directory, so any ChatGPT user can find it and add it in one click.

We build no new server. A ChatGPT plugin is a plugin.json package that points at the MCP connector we already run (https://prodback.docs.plus/api/mcp). OpenAI reviews the package once. Then the plugin appears in the directory, on every plan and on mobile.

What exists today

• The MCP connector, OAuth, the consent card, and Settings > Connected apps are live. See [Tracking] MCP connector: reach docs.plus from Claude and ChatGPT #230 and docs/mcp/README.md.
• ChatGPT connects in developer mode. A person pastes the server URL by hand. Developer mode is web only, works on paid plans only, and shows the ChatGPT app as unverified.
• No full tool run in ChatGPT is on record yet. That is Test the MCP connector in three AI apps, then finish its connect guide #357.
• Every tool already has a title, readOnlyHint, destructiveHint and openWorldHint.

Old ChatGPT plugins (ai-plugin.json) closed in 2024. Nothing from them applies. The current format is the 2026 Plugin Directory package described below.

Before you start (agents)

• Read AGENTS.md, then apps/hocuspocus.server/CLAUDE.md §MCP Connector.
• Bun only. Never run npm, npx, yarn or pnpm.
• Do not commit, push or open a PR unless the maintainer asks.
• Do not add a password sign-in path. Do not bring back passkeys. Do not add a tool that replaces a whole section or page. These are maintainer rulings in CLAUDE.md and apps/hocuspocus.server/CLAUDE.md §MCP Connector.
• Never write reviewer credentials into the repo, an issue, or a commit. They go only into the OpenAI dashboard form.
• Do not claim audience binding anywhere. Supabase always sets aud to authenticated. The token's client_id claim is the gate.

Rulings needed (maintainer)

Rule R2 and R3 before the first submission. After publication, a hint change waits for OpenAI's daily scan, and the old hint stays live until then.

R1. How does the OpenAI reviewer sign in?

The Submit page wants a reviewer account that works "without MFA approval, email or SMS codes, magic links, or private-network access". docs.plus signs in with Google or an email link only. That rules out the email link.

Recommendation: A. Test it the way a reviewer would. Use a fresh browser on a desktop, on a network other than the maintainer's usual one. If Google shows a device challenge, A fails, and the maintainer must rule on B.

• R1 ruled

R2. openWorldHint on the five read tools

Today all five read tools set false. OpenAI says to use true for "public or open-ended entities", and that connectivity alone does not decide it. find_documents with scope: "public" searches anyone's public documents. The other four read tools can open those documents too.

Recommendation: true on all five.

• R2 ruled

R3. destructiveHint on post_chat_message

Today it is false. OpenAI uses true for irreversible sends, and says undo alone does not justify false. A post can notify members who are away, and a notification cannot be recalled.

Recommendation: true. ChatGPT then asks the person to confirm before a post that other people will see.

create_document notifies no users. append_to_document, edit_blocks and replace_text produce batched digest notices to followers through the normal save path. That is the same path a person's edit takes, so this issue changes nothing for them.

• R3 ruled

Work plan

Each step has an owner: M (maintainer), C (code agent), O (ops).

Step 0. Ship what is built

• M Push the Refuse a connected-app rewrite of a section that holds media #329 fix to main (positioned edits: edit_blocks and replace_text replace replace_section).
• O Deploy it. Production must not list replace_section when the directory review starts.
• M Press Refresh on the ChatGPT app, or create it again with the listing icon, name and description. If you create it again, Disconnect the old row in Settings > Connected apps.
• M Run one live create_document, one replace_text and one edit_blocks on a scratch document.
• C After the push, close Keep unchanged blocks when a connected app replaces a section #347 as superseded. Update the Test the MCP connector in three AI apps, then finish its connect guide #357 tool list and the [Tracking] MCP connector: reach docs.plus from Claude and ChatGPT #230 tool list.

Done when ChatGPT lists edit_blocks and replace_text, and all three live calls pass.

Step 1. Prove the connector in ChatGPT

• M Run the ChatGPT part of Test the MCP connector in three AI apps, then finish its connect guide #357. Remove the <!-- PENDING-HOST-TEST: ChatGPT --> marker in docs/mcp/README.md (§Connect in ChatGPT) when it passes.
• M Make one write call on the maintainer's own plan. Two OpenAI pages disagree on whether Plus and Pro can call write tools in developer mode. Only a live call settles it.

Done when every tool has run once in ChatGPT, and the plan's write limit is known.

Step 2. Code work (C)

Start only after the #329 fix is on main. Until then, main still has replace_section, and these files do not match this issue.

Tool hints (after R2 and R3). No test asserts a hint today. typecheck is the only automated check.

• apps/hocuspocus.server/src/modules/mcp/tools/documentTools.ts: openWorldHint on find_documents, get_outline and read_document.
• apps/hocuspocus.server/src/modules/mcp/tools/chatTools.ts: openWorldHint on list_chat_rooms and read_chat_thread. Set destructiveHint on post_chat_message, and rewrite the comment above it ("A post only adds…").
• Update every doc that states the hints:
  • docs/mcp/reference.md: the hints prose, the Hints column, and the post_chat_message note.
  • apps/hocuspocus.server/API.md: the tool table and the Hints. paragraph.
  • apps/hocuspocus.server/CHANGELOG.md: the Tool hints follow the MCP and OpenAI definitions. paragraph under ## [Unreleased]. It is not published yet, so edit it in place.

Plugin package.

• Add a folder integrations/openai-plugin/ with plugin.json, mcp.json and assets/logo.png. The folder sits outside the workspace globs and outside docs/. Add no package.json.
• Copy the logo from apps/webapp/public/icons/icon-192x192.png. Do not use a maskable_* icon.
• Do not add an apps field, a .app.json file, lifecycle hooks, test_credentials or reviewer_instructions. OpenAI refuses a package that has any of them. Plugin Creator output contains .app.json, so do not submit it as it is.
• Run bun run check once, to confirm the lint and format gates accept the new JSON. If Prettier fails, run bun run format:fix, then check again.

Package skeleton (only 1 positive and 1 negative case shown; the full set is below):

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "docs-plus",
  "version": "1.0.0",
  "description": "Find, read, create and edit your docs.plus documents and their heading chats.",
  "extensions": {
    "com.openai": {
      "interface": {
        "displayName": "docs.plus",
        "shortDescription": "Read and edit your documents",
        "longDescription": "<at most 4000 characters>",
        "developerName": "<must match the verified OpenAI identity>",
        "category": "Productivity",
        "websiteURL": "https://docs.plus",
        "supportURL": "https://github.com/docs-plus/docs.plus/issues",
        "privacyPolicyURL": "https://docs.plus/privacy",
        "termsOfServiceURL": "https://docs.plus/terms",
        "defaultPrompt": ["Find my docs.plus document called Launch plan and show me its outline."],
        "logo": "./assets/logo.png"
      },
      "review": {
        "test_cases": {
          "positive": [
            {
              "description": "Find a document and show its outline",
              "prompt": "Find my docs.plus document called Launch plan and show me its outline.",
              "tools_triggered": "find_documents, get_outline",
              "expected_behavior": "Shows the heading tree of Launch plan."
            }
          ],
          "negative": [
            { "description": "No document is needed", "prompt": "Write a short poem about autumn." }
          ]
        },
        "demo_recording_url": "<public video URL>"
      },
      "publication": { "release_notes": "First release." }
    }
  }
}

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "docs-plus": { "type": "streamable-http", "url": "https://prodback.docs.plus/api/mcp" }
  }
}

Field rules from the Submit page:

• name: at most 64 characters. Lowercase letters, numbers and single hyphens.
• displayName and shortDescription: at most 30 characters each. longDescription: at most 4000. developerName: at most 80.
• The display name must not add "MCP" or "Plugin". Do not list it as "docs.plus for ChatGPT", because that can read as an OpenAI endorsement.
• tools_triggered is one string, not an array.
• defaultPrompt: up to 3, at most 128 characters each, with no @ mentions.
• Leave out screenshots. That field is only for plugins that return UI.
• Leave out publication.countries on the first upload.

Review test cases. The first review needs exactly 5 positive and 3 negative cases. These are drafts for the maintainer to approve. They assume the reviewer account owns a Launch plan document with Budget, Risks and Timeline headings. The Timeline body holds the text Q3 exactly once. The Timeline chat room holds a few messages.

Domain token.

• The maintainer posts the dashboard token on this issue. The file serves it publicly, so it is not a secret. Add it as plain text at apps/webapp/public/.well-known/openai-apps-challenge. apps/webapp/public/.well-known/security.txt is the precedent. apps/webapp/src/proxy.ts already skips .well-known, so do not edit it. A (build): front deploy then serves the file at https://docs.plus/.well-known/openai-apps-challenge.
• Check that the response is the bare token as text/plain. If Next sends another type, add a header in apps/webapp/next.config.js headers(), as /robots.txt does.

Privacy page.

• M rules how long the per-call record is kept. C then adds one sentence to apps/webapp/src/pages/privacy.tsx. The page already says a connected app gets name, profile picture and email, and never a phone number.

Before a public listing.

• M Rule how rate limiting treats /api/mcp. C builds it after the ruling. The global limiter in apps/hocuspocus.server/src/middleware/index.ts runs before the MCP router. It keys on the client IP over 15 minutes. ChatGPT calls come from OpenAI's servers, not from each person's device. The per-person tool budget lives in apps/hocuspocus.server/src/modules/mcp/infra/toolBudget.ts. Do not key the global limiter on a token before the token is verified.
• Land Cap the get_outline and list_chat_rooms output #380 (output caps on get_outline and list_chat_rooms). OpenAI does not list it as a review blocker. A public listing brings more callers, so the caps matter more.
• RFC: should a burst of connected-app writes wait instead of failing busy? #360 and Test parallel connected-app writes across two collab replicas #381 track write contention under load. No action here.

Checks for code agents:

cd apps/hocuspocus.server && env -u REDIS_HOST bun test src/modules/mcp src/modules/document-content/__tests__/unit

bun run --filter @docs.plus/hocuspocus typecheck

bun run check:push

Step 3. Account work (M)

• Complete individual or business verification in the OpenAI organization. The directory shows the verified name, whatever the package says.
• Use a project with global data residency. Projects with EU data residency cannot submit MCP plugins for now.
• Make sure the submitter is an organization owner or holds "Apps Management Write" (api.apps.write on the Review page).
• Create the reviewer account (R1) and its sample data for P1–P5. Keep both live for later reviews. After each P4 run, change Q4 back to Q3, and remove the added risk.
• Record the demo video. Show the main tools. OpenAI asks for every supported platform, and a published plugin must work on mobile. Developer mode is web only, so a mobile recording may not be possible before publication. Say so in the review notes.
• Zip integrations/openai-plugin/ for upload. Check the root layout against Package your plugin.
• Approve the listing text: description, category, default prompts, release notes.

Done when the dashboard shows no open finding before Submit for review.

Step 4. Submit and review (M)

• Upload the ZIP at https://platform.openai.com/plugins. Run the tool scan. Enter reviewer credentials in the dashboard form only.
• Submit. OpenAI publishes no review time. Plan for at least one rejection cycle. To appeal, reply to the rejection email.
• After approval, press Publish plugin.
• Post the directory link here. Add it to docs/mcp/README.md. Add it to Settings > Connected apps (apps/webapp/src/components/settings/components/ConnectedAppsSection.tsx) after the brand-rules open question is settled.

After publication, OpenAI scans the server daily. A new tool stays unavailable until it is approved. A change to metadata or assets needs a new ZIP and a new review. A change to the MCP URL needs OpenAI support.

Out of scope

• A widget inside ChatGPT (MCP Apps UI). That is RFC: should the MCP connector ship a UI widget, or stay text-only? #237. One widget built on MCP Apps would run in both ChatGPT and Claude.
• OpenAI-only plugin extensions (sidebar, file viewers, rich forms). Revisit only with real usage data.
• The Claude directory. That is RFC: should docs.plus submit its connector to the Anthropic directory? #232.

Acceptance

• R1, R2 and R3 are ruled on this issue.
• Production lists the positioned-edit tools, and every tool has run once in ChatGPT.
• The hint changes, the package folder, the domain token and the privacy sentence have landed.
• The plugin is published, and its directory link is posted here.

Open questions

References

• OpenAI: Submit · Review · Submission errors · Guidelines · Package your plugin · Authentication · Developer mode · Build plugins (Plugin Creator)
• Related: [Tracking] MCP connector: reach docs.plus from Claude and ChatGPT #230 (tracking) · RFC: should docs.plus submit its connector to the Anthropic directory? #232 (Claude directory) · RFC: should the MCP connector ship a UI widget, or stay text-only? #237 (UI widget) · Refuse a connected-app rewrite of a section that holds media #329 (positioned edits; its body describes an older plan) · Add links and Comment quotes to MCP reads #343 (links in reads) · Keep unchanged blocks when a connected app replaces a section #347 (superseded) · Test the MCP connector in three AI apps, then finish its connect guide #357 (host test) · RFC: should a burst of connected-app writes wait instead of failing busy? #360 · Cap the get_outline and list_chat_rooms output #380 · Test parallel connected-app writes across two collab replicas #381