Skip to main content
Glama
Wally-Ahmed

gpt-subagents-subscription

by Wally-Ahmed
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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.

Related MCP server: codex-mcp

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

Available Tools

4 tools
ask_gptA

Ask a GPT model via your ChatGPT subscription. You must choose model explicitly AND write instructions (the model's system prompt) yourself — there are no defaults. Any valid model id is accepted; known suggestions: gpt-5.4 (general), gpt-5.4-mini (faster/cheaper), gpt-5.5 (deepest reasoning — use with reasoning_effort 'high' for architecture, security/threat modeling, and hard review). Treat output as a hypothesis to verify.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelYesWhich model to use (required, no default). Any valid model id is accepted. Known suggestions: gpt-5.4 (capable general-purpose), gpt-5.4-mini (faster/cheaper for lighter tasks), gpt-5.5 (deepest reasoning — architecture, security/threat modeling, hard review).
promptYesThe task or question for the model
contextNoCode, errors, constraints, or other relevant context
instructionsYesSystem instructions for the model (required, no default): its role, persona, and how to respond. Write these explicitly for the task at hand.
reasoning_effortNoReasoning effort (higher = deeper but slower). Best with gpt-5.5 for hard tasks.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It mentions treating output as a hypothesis, hinting at potential inaccuracy. However, it does not disclose error handling, rate limits, cost implications, or what happens with invalid model IDs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two well-structured sentences. The first states the core action and key requirements. The second provides model recommendations and a caveat. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks output format details (no output schema). It does not explain what the tool returns (e.g., text, JSON). For a 5-param tool with no output schema, this is a significant gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, baseline 3. The description adds value by linking model IDs to use cases (e.g., gpt-5.5 for deep reasoning) and suggesting reasoning_effort coupling, going beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool asks a GPT model via ChatGPT subscription. The verb 'ask' and resource 'GPT model' are specific. Sibling tools (check_usage, get_pattern, list_patterns) have distinct purposes, so no confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says you must choose model and write instructions yourself, and provides model recommendations with use cases. It lacks explicit when-not-to-use or alternatives, but the context is clear and practical.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

check_usageA

Show remaining ChatGPT/Codex subscription quota for the signed-in account.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description clearly indicates a read-only query with no side effects. It doesn't specify output format, but for a simple quota check this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One succinct sentence conveying the tool's purpose without any wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple no-parameter tool, the description is complete enough. It explains what the tool does and its scope. Lacks details on output format, but output schema is not provided.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, and schema coverage is 100%. The description doesn't need to add parameter info; baseline for zero parameters is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool shows remaining subscription quota for the signed-in account, using a specific verb and resource. It easily distinguishes from siblings like ask_gpt (for questions) and pattern tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. While it's unique among siblings, the description doesn't suggest best practices like checking quota before API calls.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_patternA

Return the full text of an orchestration pattern by name (see list_patterns). Use it to apply the pattern when orchestrating ask_gpt calls.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesThe pattern name from list_patterns, e.g. 'two-layer-cross-model-expert'

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the burden. It implies a read-only operation ('Return the full text'), but does not explicitly state non-destructive behavior, permissions, or side effects. Given the simplicity, it is adequate but not exemplary.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. The main action and purpose are front-loaded, and the secondary sentence provides usage guidance. Perfectly concise for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only one parameter, no output schema, and is straightforward, the description is complete. It covers what the tool returns, how to get the input, and why to use it. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers the parameter with 100% coverage and a description. The tool description adds value by reinforcing the relationship to list_patterns and giving an example pattern name, which helps the agent understand how to select a valid name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Return' and the resource 'full text of an orchestration pattern', and explicitly references sibling tool list_patterns for how to get valid names. It distinguishes from siblings by focusing on retrieval of full text vs listing or usage.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description tells when to use the tool: 'Use it to apply the pattern when orchestrating ask_gpt calls.' It also directs the agent to see list_patterns for available names, providing clear context for correct usage, though it does not explicitly state when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_patternsA

List available orchestration patterns for driving the GPT subagents. Call this before non-trivial expert work — reviews, audits, threat modeling, large analysis — then read the chosen one with get_pattern. Returns each pattern's name, title, summary, and when to use it.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses that it lists patterns and returns each pattern's name, title, summary, and when to use it. It implies a read-only operation, though not explicitly stated. Sufficient for a simple list tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. First states core function, second adds usage guidance and return details. Efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters and no output schema, the description covers purpose, when to use, what to do next, and what it returns. Complete for its simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist; schema coverage is 100%. The description correctly avoids parameter details. Baseline 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List', the resource 'available orchestration patterns', and the context 'for driving the GPT subagents'. It differentiates from siblings by mentioning subsequent use of get_pattern.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to call this before non-trivial expert work (reviews, audits, etc.) and then read the chosen pattern with get_pattern. Provides clear when-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedask_gpt
    • First observedcheck_usage
    • First observedget_pattern
    • First observedlist_patterns
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a distinct purpose: ask_gpt for queries, check_usage for quota, get_pattern and list_patterns for orchestration patterns. No overlap in functionality.

Naming Consistency5/5

All tools follow a consistent verb_noun snake_case pattern (ask_gpt, check_usage, get_pattern, list_patterns), making them predictable and easy to understand.

Tool Count4/5

With 4 tools, the set is concise and focused on core subscription-GPT and pattern orchestration needs. Could possibly benefit from a tool to list available models, but the count is appropriate for its scope.

Completeness4/5

The set covers querying GPT, checking usage, and managing orchestration patterns. A minor gap is the absence of a tool to list models or subscription details beyond quota, but core workflows are well-supported.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • GPT MCP Service

    jmillpps
    F
    license
    Not graded
    quality
    D
    maintenance
    Private OAuth-backed MCP server for ChatGPT, supporting GPT Apps via MCP Streamable HTTP and GPT Actions via REST endpoints with OpenAPI 3.1.
    -

  • codex-mcp

    j-token
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server wrapping OpenAI Codex SDK to run Codex agents for code generation, debugging, and more, authenticating via ChatGPT OAuth.
    18 npm
    MIT

  • open-subagent-mcp

    g2zz
    A
    license
    A
    quality
    D
    maintenance
    A local MCP server that delegates tasks to a subagent runtime via OpenAI-compatible interfaces, enabling file operations, command execution, and rollback of local file changes.
    5
    MIT