gpt-subagents-api

An MCP server 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 verified instead of blindly trusted.

The subagent tools

Both tools require a model parameter — pass any valid OpenAI model id. Suggested defaults are shown above, but the server does not hardcode any model.

⚠️ Expert reasoning models can be confidently wrong. Treat ask_gpt_architect output as a hypothesis and verify claims against real files, docs, and tests before acting. The same caution applies to any review or audit — use the orchestration patterns below to make verification automatic.

Both tools take a task/question plus optional context. Inbound context is run through a sanitizeContext pass that redacts obvious secrets (OpenAI/Anthropic keys) before it leaves your machine — but don't rely on it as your only safeguard; avoid pasting secrets.

Related MCP server: Task Agents

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_architect work — or any review, audit, or large-document analysis.

Shipped patterns

The two-layer pattern also ships a rendered, styled diagram at patterns/html/two-layer-cross-model-expert.html — open it in a browser for the visual walkthrough.

See patterns/README.md to add your own.

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 four tools: ask_gpt_worker, ask_gpt_architect, list_patterns, and get_pattern.

Project layout

gpt-subagents-api/
├── server.ts        # MCP server: tool defs + server instructions
├── gptAgents.ts     # OpenAI calls (worker + architect) 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
├── .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. Expert reasoning models are powerful but can be confidently wrong; the two-layer-cross-model-expert pattern is the recommended way to act on ask_gpt_architect output safely.

License

ISC