gpt-subagents-subscription

gpt-subagents-subscription

An MCP server that exposes GPT "subagent" tools backed by your ChatGPT subscription — using OpenAI's "Sign in with ChatGPT" OAuth instead of a pay-per-use API key. Sibling to gpt-subagents-api (which uses an API key), and it ships the same orchestration patterns system.

Note: Authenticates via OpenAI's "Sign in with ChatGPT" OAuth — the mechanism OpenAI introduced (through Codex CLI) for bringing your ChatGPT subscription to a third-party tool — and calls the ChatGPT backend with the resulting token. Not affiliated with or endorsed by OpenAI. These backend endpoints aren't versioned and can change; if a call starts failing, the stable alternative is the API-key sibling gpt-subagents-api.

---

Tools

Tool	What it does
ask_gpt	Ask a GPT model via your ChatGPT subscription. You pick model and write instructions (the system prompt) every call — both required, no defaults. Any valid model id is accepted; known suggestions: gpt-5.6-sol (frontier), gpt-5.6-terra (balanced), gpt-5.6-luna (fast/cheap) — use the explicit ids (the bare gpt-5.6 alias is rejected by the subscription backend); older gpt-5.5 / gpt-5.4 / gpt-5.4-mini still work. Optional reasoning_effort (none/low/medium/high/xhigh/max; the full scale is a gpt-5.6 feature).
ask_gpt_batch	Run up to 8 independent asks concurrently in one tool call (each ask has the same fields as ask_gpt). Results return together, labeled per ask; one failed ask doesn't abort the others.
check_usage	Remaining ChatGPT/Codex subscription quota
list_patterns / get_pattern	Orchestration patterns for driving the model well (see below)

All tools are annotated readOnlyHint: true — they never mutate state, only consume quota — so MCP clients that key on it (Claude Code does) can dispatch several ask_gpt calls from one message in parallel instead of serializing them. The backend accepts concurrent requests on one account; ask_gpt_batch guarantees that concurrency server-side regardless of the client's scheduling.

---

Orchestration patterns

Patterns are reusable playbooks (Markdown in patterns/) that describe how to drive the expert tools — splitting work, bundling context, calling the expert, verifying its output against ground truth, and aggregating. They're exposed via list_patterns (catalog) and get_pattern("<name>") (full text), read from disk at call time (no rebuild to add one), and the server's instructions nudge the agent to consult them before non-trivial expert work.

name	what it does
two-layer-cross-model-expert	Wrap the GPT expert in verifying Claude subagents so the orchestrator only ever sees parallel, context-cheap, ground-truth-checked conclusions.
worker-orchestrator	Fan concrete work out to the GPT worker (ask_gpt with a fast model) through cheap Sonnet wrapper subagents — validated by execution, not a verification gate.

Both patterns ship a rendered diagram under patterns/html/. See patterns/README.md to add your own.

---

CLI

The same capability as a shell command (dist/cli.js, bin name gpt-subagents-subscription) — no MCP framing, raw answer on stdout, so an agent driving it through a shell tool spends zero tokens on protocol boilerplate:

# ask (the subcommand is optional); model is REQUIRED (no default)
gpt-subagents-subscription ask -m gpt-5.6-luna "why is the sky blue?"

# piped stdin becomes the prompt — or the context when a prompt is given
git diff | gpt-subagents-subscription ask -m gpt-5.6-sol -e high -p "review this diff"

# subscription quota, patterns, and per-machine OAuth login
gpt-subagents-subscription usage
gpt-subagents-subscription patterns
gpt-subagents-subscription pattern worker-orchestrator
gpt-subagents-subscription login          # (--logout to clear tokens)

-i/--instructions overrides the system prompt (CLI default: terse expert; the MCP tool keeps instructions required). For 2+ independent asks, run multiple invocations concurrently (shell & / xargs -P) — the CLI equivalent of ask_gpt_batch. Install the bin with npm link or invoke via node dist/cli.js / npm run cli --.

---

Setup

Requires Node 18+ and an active ChatGPT subscription.

npm install
npm run build
npm run login     # prints a sign-in URL to open; sign in with ChatGPT (one-time)

npm run login runs an OAuth flow on http://localhost:1455/auth/callback and stores tokens at ~/.gpt-subagents-subscription/auth.json (mode 0600, never committed). Run npm run login -- --logout to clear them.

Register with Claude Code

claude mcp add gpt-subagents-subscription -- node /absolute/path/to/gpt-subagents-subscription/dist/server.js

Long-running calls

Hard ceiling first: the subscription backend terminates a single response stream at ~15 minutes (measured at ~902s on both HTTP/1.1 and HTTP/2, with events actively flowing; background mode is rejected — "Store must be set to false"). An ask whose reasoning+output exceeds the window dies with its work lost, and the server reports it as such. Scope each ask to fit; split larger jobs into independent asks (ask_gpt_batch runs them concurrently — the patterns show how).

Below that ceiling, this server keeps every other timeout out of the way. MCP clients kill a tool call whose HTTP response stays byte-silent for too long — Claude Code (observed on v2.1.183) aborts at ~5 minutes, and empirically neither MCP_TOOL_TIMEOUT nor the per-server timeout field prevents it for a byte-silent call. This server therefore keeps bytes flowing itself:

• SSE response mode + 30s heartbeats. In HTTP mode the server answers tool calls as an SSE stream and emits a notification every 30s while the backend call is in flight (a progress notification when the client sent a progressToken, else a logging notification). The response is never byte-silent, so client first-byte/inactivity timers don't fire.
• Server-side wall-clock deadline — default 3h15m per backend request (a backstop against a hung backend). Override in ms via GSS_RESPONSES_DEADLINE_MS, no rebuild needed.
• Client wall-clock — Claude Code's MCP_TOOL_TIMEOUT (ms; default ≈28h) bounds total call time. If you set it, keep it above the server deadline.
• Cancellation propagates. If the client aborts a call, the server aborts the in-flight backend request instead of letting it burn subscription quota to completion.

The backend connection is hardened for silence too: undici header/body inactivity timeouts are disabled and TCP keepalive probes are enabled, so NAT/firewall idle tracking won't drop a quiet stream during a long reasoning phase.

Keeping the HTTP server always-on (macOS)

A hand-launched HTTP server dies on reboot and keeps serving stale code after rebuilds. Manage it with launchd instead — deploy/com.wally.gpt-subagents-subscription.plist starts it at login, restarts it on crash, and pins GPT_MCP_HTTP_PORT=8791:

# one-time install (adjust paths in the plist if the repo lives elsewhere)
cp deploy/com.wally.gpt-subagents-subscription.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.wally.gpt-subagents-subscription.plist

# after every rebuild — restart the managed process so it loads the new dist/
npm run build && npm run restart:http

Pin the client-side wall-clock too by adding "timeout": 12600000 to the server's entry in the MCP registration (and see the env settings above for MCP_TOOL_TIMEOUT / CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT on newer Claude Code versions).

---

How it works

1. npm run login → PKCE OAuth against auth.openai.com → tokens stored locally.
2. The MCP server reads and auto-refreshes those tokens.
3. Tool calls POST to chatgpt.com/backend-api/codex/responses with Authorization: Bearer + ChatGPT-Account-Id, using the Responses API schema.

---

Security

• Tokens live outside the repo (~/.gpt-subagents-subscription/) and are gitignored everywhere.
• No credentials are committed; .env.example holds only optional model overrides.
• This project never reads your existing ~/.codex/auth.json — it mints its own tokens.
• Local agent/editor state (.mempalace/, .claude/, CLAUDE.local.md, IDE folders) is gitignored.

---

Credits / prior art

The "Sign in with ChatGPT" subscription flow has been documented by the community, e.g. EvanZhouDev/openai-oauth and various write-ups.

License

MIT