Skip to main content
Glama
Wally-Ahmed

gpt-subagents

by Wally-Ahmed
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

gpt-subagents-api

An MCP server and CLI that lets Claude Code delegate to OpenAI "expert" models as subagents — and ships a small, extensible library of orchestration patterns that teach the calling agent how to use those experts well.

Claude orchestrates; GPT gives a second opinion from a different model family (different blind spots). The patterns make that second opinion parallel, context-cheap, and ground-truth-checked.

The subagent tool

There's one tool — ask_gpt. You choose the model, write the instructions (its system prompt), supply a prompt, and optionally set reasoning_effort and context.

There's no separate "worker" and "architect" tool: that distinction is just which orchestration pattern you apply, plus the model and effort you pick —

Role

How

Pattern

Worker — routine coding, patches, debugging, tests, repo inspection

ask_gpt with a fast model (e.g. gpt-5.6-terra, or gpt-5.6-luna for high-volume)

worker-orchestrator

Architect — hard reasoning, architecture, security / threat modeling, review of large/high-risk changes

ask_gpt with a strong model (gpt-5.6-sol) + reasoning_effort: "high" or above

two-layer-cross-model-expert

The gpt-5.6 family: sol (frontier — deepest reasoning), terra (balanced intelligence/cost), luna (fast/cheap, high-volume). The bare gpt-5.6 alias routes to sol. reasoning_effort spans the full none | minimal | low | medium | high | xhigh | max scale on gpt-5.6; gpt-5.5 tops out at xhigh, older models at high. Reserve max for the hardest quality-first audits.

model, instructions, and prompt are required (any valid OpenAI model id is accepted — the server hardcodes none). Inbound instructions, prompt, and context are run through a sanitizeContext pass that redacts obvious secrets before they leave your machine — a backstop, not a guarantee; avoid pasting secrets.

Related MCP server: CodexMCP

Orchestration patterns

Patterns are reusable playbooks (Markdown files 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 results.

Two tools expose them to the agent:

  • list_patterns — catalog of every pattern (name, title, summary, when to use).

  • get_pattern("<name>") — the full text of one pattern.

Patterns are read from disk at call time, so adding or editing one needs no rebuild. The server's startup instructions nudge the agent to consult patterns before any non-trivial ask_gpt work — or any review, audit, or large-document analysis.

Shipped patterns

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 through cheap Sonnet wrapper subagents — validated by execution, not a verification gate.

Both patterns ship a rendered, styled diagram under patterns/html/ — open one in a browser for the visual walkthrough.

See patterns/README.md to add your own.

CLI

Everything the MCP server does is also available as a plain shell command — same client, same patterns library, but the answer comes back as raw text on stdout with zero JSON-RPC framing. For agents that can run shell commands, this is the token-cheap way to delegate: no MCP envelope in either direction, and piped stdin means large inputs (diffs, logs, files) never have to be echoed through the model's context at all.

npm run build        # compiles dist/cli.js
npm link             # optional: puts `gpt-subagents-api` on your PATH

# ask (the subcommand is optional); raw answer on stdout
gpt-subagents-api ask -m gpt-5.6-luna "why is the sky blue?"
gpt-subagents-api ask -m gpt-5.6-sol -e max "prove sqrt(2) is irrational"

# piped stdin becomes the prompt — or the context when a prompt is given
git diff | gpt-subagents-api ask -m gpt-5.6-sol -e high -p "review this diff for bugs"
gpt-subagents-api ask -m gpt-5.6-terra -p "summarize" --context-file big-report.md

# patterns
gpt-subagents-api patterns
gpt-subagents-api pattern two-layer-cross-model-expert

Flags mirror the MCP tool: -m/--model (required, no default), -i/--instructions (defaults to a terse general-purpose prompt), -p/--prompt, -c/--context (each with a --*-file variant), and -e/--effort (none…max). --help shows the full reference. Exit codes: 0 success, 2 usage error, 1 API/network error.

Setup

Requirements: Node 18+ and an OpenAI API key.

# 1. Install dependencies
npm install

# 2. Add your key (this file is gitignored and must never be committed)
cp .env.example .env
#   then edit .env and set OPENAI_API_KEY=sk-...

# 3. Build
npm run build

This compiles to dist/. The server loads .env from the project root (one level up from dist/server.js), or falls back to an inherited OPENAI_API_KEY in the environment.

Register with Claude Code

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

Or add it to your MCP client config manually:

{
  "mcpServers": {
    "gpt-subagents-api": {
      "command": "node",
      "args": ["/absolute/path/to/gpt-subagents-api/dist/server.js"]
    }
  }
}

Once connected, the server advertises three tools: ask_gpt, list_patterns, and get_pattern.

Project layout

gpt-subagents-api/
├── server.ts        # MCP server: the ask_gpt tool + server instructions
├── cli.ts           # CLI twin of the server (ask / patterns / pattern)
├── gptAgents.ts     # The OpenAI call (ask_gpt) and secret sanitization
├── patterns.ts      # Loads/parses pattern Markdown from patterns/
├── patterns/        # Orchestration patterns (one Markdown file each)
│   ├── README.md
│   ├── two-layer-cross-model-expert.md
│   └── worker-orchestrator.md
├── .env.example     # Placeholder; copy to .env (gitignored)
└── dist/            # Build output (gitignored)

Security notes

  • .env is gitignored and never tracked — only the .env.example placeholder is committed. Local agent/editor state (.mempalace/, .claude/, CLAUDE.local.md, IDE folders) is gitignored too, so dev-environment data doesn't leak into the repo.

  • sanitizeContext redacts sk-… keys and OPENAI_API_KEY= / ANTHROPIC_API_KEY= assignments from outbound context. It's a backstop, not a guarantee — keep secrets out of prompts.

  • Verify expert output against ground truth. The two-layer-cross-model-expert pattern is the recommended way to drive ask_gpt (architect-style) so its output is checked before you act on it.

License

MIT

Available Tools

3 tools
ask_gptA

Ask an OpenAI model as an expert subagent. ONE tool for everything: you choose the model, write the instructions (its system prompt), and optionally set reasoning_effort. There is no separate 'worker' vs 'architect' tool — the difference is the orchestration PATTERN you apply plus your model/effort choice: a fast model (e.g. gpt-5.6-terra, or gpt-5.6-luna for high-volume) with the worker-orchestrator pattern for concrete code work (patches, debugging, tests, repo inspection); a strong model (gpt-5.6-sol) + reasoning_effort 'high' or above with the two-layer-cross-model-expert pattern for hard reasoning, architecture, security/threat modeling, and review. Call list_patterns / get_pattern first for non-trivial work.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelYesThe OpenAI model id (required): gpt-5.6-sol (frontier — deepest reasoning, architecture, hard review), gpt-5.6-terra (balanced general-purpose/coding), gpt-5.6-luna (fast/cheap, high-volume). The bare 'gpt-5.6' alias routes to sol. Any valid OpenAI model id is accepted (older gpt-5.5 etc. still work).
promptYesThe task or question for the model.
contextNoCode snippets, error messages, stack traces, constraints, or other relevant context.
instructionsYesSystem instructions for the model (required): its role and how to respond. Write these for the task at hand — e.g. a coding-subagent prompt for worker-style work, or a reviewer/architect prompt for analysis.
reasoning_effortNoReasoning effort (higher = deeper but slower). gpt-5.6 supports the full scale none→max; gpt-5.5 tops out at xhigh, older models at high. Use 'high' or above for deep audits / architecture review; reserve 'max' for the hardest quality-first work.

TDQS

A4.4/5.0
Behavior3/5

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

No annotations are provided, so the description must carry the full burden. It mentions that higher reasoning_effort is deeper but slower, and that models have different capabilities (e.g., max effort per model). However, it fails to disclose potential behavioral traits such as token limits, cost implications, or timeout behavior.

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?

The description is dense but every sentence adds value. It front-loads the core purpose, then provides clear guidelines and examples. No redundant or filler content.

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?

Given the absence of an output schema, the description does not explain what the tool returns (e.g., plain text response). It covers usage patterns well but lacks details on error handling or maximum response size. Still, it provides sufficient context for an AI agent to use correctly with the sibling tools.

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 coverage is 100% (all parameters have descriptions), so baseline is 3. The description adds significant value by explaining model aliases and use cases (sol for reasoning, terra for coding, luna for high-volume), the reasoning_effort scale with model-specific caps, and how to write instructions. This goes beyond the schema's minimal descriptions.

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's purpose: 'Ask an OpenAI model as an expert subagent. ONE tool for everything.' It specifies the key parameters (model, instructions, reasoning_effort) and distinguishes from sibling tools (list_patterns, get_pattern) by noting they are for patterns, not LLM calls.

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?

Provides extensive guidance: when to use fast models (gpt-5.6-luna) for high-volume work, strong models (gpt-5.6-sol) for reasoning, different reasoning_effort levels, and the orchestration patterns (worker vs two-layer-cross-model-expert). Explicitly recommends calling list_patterns/get_pattern first for non-trivial work.

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?

No annotations exist, so the description carries the burden. It discloses the tool returns pattern text but does not mention behavior on invalid pattern names, error handling, or whether the result is cached. For a read-only retrieval tool, this is adequate but could be improved.

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 unnecessary words. Front-loaded with the action and immediately clarifies usage. Every sentence serves a purpose.

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?

With only one simple parameter, no output schema, and no complex behavior, the description fully covers what the agent needs—return value, source of names, and when to use it.

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

Parameters3/5

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

Schema covers 100% of parameter description including example. The description adds 'by name (see list_patterns)' which ties the parameter to the sibling tool but no additional semantic detail 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 it returns the full text of an orchestration pattern by name, and references list_patterns, distinguishing the tool from its sibling. The verb 'return' and resource 'pattern' are specific.

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 use this tool to apply the pattern when orchestrating ask_gpt calls, and mentions list_patterns for obtaining names, giving clear when-to-use and alternative reference.

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 ask_gpt. Call this before non-trivial expert work — reviews, audits, threat modeling, large-document 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?

No annotations provided, but the description discloses the return structure (name, title, summary, when to use). It doesn't mention potential side effects or access requirements, but for a read-only list operation 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?

Two sentences, front-loaded with purpose and usage, no fluff. Every sentence adds value.

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 zero parameters and no output schema, the description fully covers what the tool does, what it returns, and when to use it in relation to sibling tools.

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; baseline score is 4 since the description does not need to compensate for any missing param info.

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?

Clearly states it lists orchestration patterns for driving ask_gpt, and distinguishes from siblings by mentioning get_pattern as the next step and ask_gpt as the consumer.

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 when to call: before non-trivial expert work like reviews, audits, threat modeling, and large-document analysis. Provides workflow: call this, then read the chosen pattern with get_pattern.

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. 3 tool updatesv1.0.0
    • First observedask_gpt
    • 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.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool serves a clear, distinct purpose: ask_gpt for executing model calls, list_patterns for browsing patterns, and get_pattern for retrieving pattern details. No functional overlap exists.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (ask_gpt, list_patterns, get_pattern), making it predictable for an agent.

Tool Count4/5

With 3 tools, the set is compact but well-scoped for its purpose: a single execution tool and two pattern retrieval utilities. Slightly on the small side, but not underdeveloped.

Completeness4/5

The core functionality and pattern management are covered. Minor gaps exist (e.g., no tool to view conversation history or manage context), but the overall surface is sufficient for the intended use.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • CodexMCP

    JohanFJ101
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables Claude to offload mechanical, output-heavy tasks like boilerplate, type generation, and summarization to OpenAI while keeping reasoning in-context.
    -

  • handoff-mcp

    felkru
    A
    license
    A
    quality
    C
    maintenance
    Enables Claude to delegate tasks to external coding agents (Codex or Antigravity) for independent reviews, separate quota usage, and async processing.
    6
    MIT