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

Related MCP server: MCP Server with OpenAI Integration

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.

Both patterns ship a rendered diagram under patterns/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

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

License

MIT