Repository navigation
docs: Claude Desktop install routes + verified ChatGPT connector path - #12
Merged
Merged
Conversation
…ad routes Adds a Claude Desktop install section (spec D4) covering both routes from Settings -> Plugins: Add marketplace (Synter-Media-AI/plugin) and Upload plugin (the zip attached to the v1.0.0 GitHub Release, built by release.yml). Keeps the existing Claude Code /plugin marketplace add instructions unchanged. Co-authored-by: Joel Horwitz <joel@synterai.com>
…flag the gap Adds a ChatGPT (Developer Mode / Connectors) section (spec D5). Verified against OpenAI's current documentation before writing anything: - https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-connectors-in-chatgpt-beta - https://developers.openai.com/apps-sdk/build/auth Both describe only two auth mechanisms for a ChatGPT connector: no authentication, or a full OAuth 2.1 flow. Neither documents a static API key / custom-header field. Synter's hosted MCP server authenticates via a static X-Synter-Key header (no OAuth support), so the header assumption in the original spec does not hold: pointing ChatGPT's connector picker directly at https://mcp.syntermedia.ai will not authenticate today. Documents this gap explicitly instead of glossing over it, and points to the working paths already on this page (Claude Code/Desktop/Cursor, direct-header MCP clients, and the stdio fallback via @synterai/mcp-server for clients with no remote-MCP support). Co-authored-by: Joel Horwitz <joel@synterai.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
D4 and D5 of the approved distribution spec (Blueprint
art_RH6inobj) call for install docs covering Claude Desktop's two routes and a ChatGPT connector path. The spec's ChatGPT section carried an unverified assumption — that ChatGPT's connector auth accepts a customX-Synter-Keyheader — which needed checking against OpenAI's own docs before shipping it as instructions.What
D4 — Claude Desktop (
docs(desktop-install)): added a### Claude Desktopsection under Install with both routes:Synter-Media-AI/plugin.github/workflows/release.yml)Existing Claude Code
/plugin marketplace addinstructions are untouched.D5 — ChatGPT connector (
docs(chatgpt-connector)): verified OpenAI's current documentation before writing anything —Both describe exactly two supported auth mechanisms for a ChatGPT connector: no authentication or OAuth 2.1. Neither documents a static API-key / custom-header field.
Finding: the spec's header assumption does not hold. Synter's hosted MCP server authenticates every request with a static
X-Synter-Keyheader and doesn't implement OAuth — so pointing ChatGPT's connector picker directly athttps://mcp.syntermedia.aiwill not authenticate today. This is a real product gap (closing it needs an OAuth 2.1 front end on the MCP server), not a doc omission, and it's out of scope for this PR.The new
### ChatGPT (Developer Mode / Connectors)section documents this gap explicitly and points to the working paths already on the page: Claude Code/Desktop/Cursor (header sent automatically), any MCP client that supports custom headers (direct HTTP wiring), and the stdio fallback via@synterai/mcp-serverfor clients with no remote-MCP support (noting that fallback doesn't help ChatGPT specifically, since ChatGPT's connector only reaches remote HTTPS servers).Tradeoffs
Considered writing the ChatGPT section as originally speced (custom header) — rejected because it would document a setup flow that fails at the auth step, wasting a user's time and creating a support burden. Documenting the gap honestly costs a "nice complete story" but is accurate; the alternative (silently omitting the caveat) would be worse.
How to Review
README.mdonly — two new subsections, both additive, no existing content changed.releases/latest/download/synter-plugin-1.0.0.zip) follows the naming from PR ci(build): package plugin into archive-root zip with validate/release workflows #9's release workflow.Test Evidence
claude plugin validate . --strict(claude CLI installed fresh in the sandbox for this run — not preinstalled):Also ran the repo's own manifest validator (
node scripts/validate-manifests.js):All manifests, skill frontmatter, and interpolation guards passed.Human author: Joel Horwitz (joel@synterai.com)
🔗 Obvious Project · 🧵 Obvious Thread