gpt-subagents-subscription

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

⚠️ Read this first

This project talks to undocumented OpenAI endpoints (auth.openai.com + chatgpt.com/backend-api/codex) — the same ones Codex CLI's "Sign in with ChatGPT" uses — and reuses Codex's public OAuth client_id.

• Not affiliated with or endorsed by OpenAI.

• It may violate OpenAI's Terms of Service and could get your account rate-limited or banned.

• The endpoints are unpublished and can change or break at any time.

• Use entirely at your own risk. The official, stable path is an API key — see gpt-subagents-api.

Related MCP server: MCP Server with OpenAI Integration

Tools

⚠️ These models can be confidently wrong. Treat output as a hypothesis and verify against real files, docs, and tests — the orchestration patterns exist largely to make that automatic.

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.

A rendered diagram lives at patterns/html/two-layer-cross-model-expert.html. See patterns/README.md to add your own.

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

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

Reverse-engineering of the ChatGPT subscription flow is documented by the community, e.g. EvanZhouDev/openai-oauth and various write-ups.

License

ISC