gpt2agent

MCP server for your ChatGPT account: codex login → ChatGPT Plus/Pro inside any MCP client.

An MCP server that puts your ChatGPT Plus or Pro subscription — Chat models and the account-tier features below — inside Claude Code, Codex, Cursor, Windsurf, Zed, and any MCP client.

📖 Quickstart · Client setup · How it works · Troubleshooting · FAQ · Docs index · Account safety

TL;DR

pipx install gpt2agent        # 1. install
codex login                   # 2. authenticate (or: gpt2agent setup)
gpt2agent install             # 3. register with your MCP client(s), then restart it
gpt2agent doctor              # 4. verify — status table, never spends quota

Then ask your agent to call chat, deep_research, or account_status.

One thing to know up front — conversation tools have three lanes (below): REST needs the sentinel bridge (owner-supplied, not distributed); browser needs a one-time Chrome login; manual works with zero network. Read-only tools work out of the box.

What works right now

September 29 update: both checked accounts list gpt-6.1-sol-wm in the model catalog. This is a Work model; catalog presence does not establish support through the Chat conversation endpoint used here. The Chat default remains gpt-5-6. See the compatibility report for new announcements, measured coverage, and release boundaries.

gpt-6-pro can hand off its reply outside the initial stream. Temporary conversations may then return 404 on recovery. Choose temporary=False explicitly if you want a saved conversation; the client never changes that privacy choice automatically.

Latest research and read-only health verification: 2026-09-29, on two Pro accounts. Light and heavy research both completed; release evidence is in the preparation report. Other conversation-tool results below retain their September 23–24 dates. Re-check read-only health with gpt2agent doctor; its gate checks do not execute conversation tools.

Install

curl -fsSL https://raw.githubusercontent.com/robotlearning123/gpt2agent/main/install.sh | bash

That command: installs the package via pipx, reuses your codex login token if present, detects your MCP clients and writes the right config for each, and drops the Claude Code skills (deep-research + gpt2agent) into ~/.claude/skills/.

Prefer steps one at a time, a single client, the Claude Code plugin, HTTP transport, or manual config snippets? → Quickstart and Client setup.

Authenticate

codex login (token reused and reloaded on refresh), or gpt2agent setup to paste a session token once — details in Quickstart §3.

Multiple ChatGPT accounts

One server entry per account, selected by env.CODEX_HOME; both run side by side in one client with independent tokens, quotas, and rate budgets → Client setup § Multiple accounts.

The three lanes (every conversation tool)

Precedence: manual=True > browser=True > REST. On an upstream challenge, chat, agent, and deep_research fall back to the browser lane automatically when it is enabled. Other conversation tools do not share this automatic fallback.

The sentinel bridge (REST lane)

Upstream's Sentinel challenge demands a bytecode-VM Turnstile token the built-in solver cannot produce. The bridge — an owner-supplied solver directory at ~/.gpt2agent/sentinel-bridge/ with an ENABLED marker — mints the full header set per request. It is not part of this distribution; setup steps, deps, and env controls (GPT2AGENT_SENTINEL_BRIDGE, …_OFF=1) are documented in How it works and Configuration. Without the bridge: read-only tools work; conversation tools over REST fail at the legacy gate — use browser=True or manual=True.

Verify

gpt2agent doctor      # read-only probes: status table + one-line summary; zero quota
gpt2agent usage       # plan, per-feature quota remaining + reset times, rate window
gpt2agent ratelimit   # local pacing and cooldown state; no network request

Tools

tools/list enumerates everything, including usage_stats and the queue tools. Every conversation tool also takes manual and browser.

Chat & research

Quotas: light DR bills 1 per completed search turn from the account's monthly deep_research bucket (aborted turns cost 0); heavy DR draws an independent monthly cap; conversation posts are paced client-side (no fixed upstream window is reported for Pro). Live numbers: gpt2agent usage. Full measured model → FAQ.

Image, code & files

Account, memory & Codex introspection

account_status, list_models, list_conversations, get_conversation, list_tasks, list_apps, list_custom_gpts (all ✅) · memory_list, memory_search, custom_instructions_get (✅) · memory_create_via_chat (⚠ model-dependent) · custom_instructions_set (❓) · list_codex_envs, list_codex_tasks (✅) · codex_task_create (❓).

Architecture

Native Python, no proxy: curl_cffi (TLS impersonation) streams chatgpt.com /backend-api/* SSE with v1-delta parsing; one persistent simulated browser identity; per-call lane selection (bridge / Playwright Chrome / handoff). Details and diagram: How it works.

Citations: DR replies carry inline [N](url) anchors — citations.py rewrites the stream's citeturn… markers via content_references and appends a Sources section. Knowledge-only answers may have no Sources.

Configuration

Optional TOML, searched in order: ~/.gpt2agent/config.toml, ./config.toml, ~/.config/gpt2agent/config.toml — keys for [server], [models] (chat / agent / heavy_dr defaults), and [browser], plus environment variables (CODEX_HOME, GPT2AGENT_SENTINEL_BRIDGE*, GPT2AGENT_RAW_DUMP, …) → Configuration reference.

Account safety & risk — read before running

gpt2agent talks to ChatGPT's private backend the way the web app does — very likely against the OpenAI ToS; automated traffic can get an account rate-limited, challenged, suspended, or banned. Use an account you can afford to lose; keep volume human-scale; client-side pacing and challenge backoff are built in. Token stays local (read from $CODEX_HOME/auth.json / ~/.gpt2agent/token.json, sent only to chatgpt.com); PII redaction is limited. The HTTP transport is unauthenticated — use stdio. Full policy: Account safety; issues → SECURITY.md.

For agents (machine-facing facts)

• Status ground truth for this host+account: gpt2agent doctor (read-only, zero quota, per-tool table + N OK, M failed, … summary). The table above is the last verified date, not live state.
• Quota before spending: gpt2agent usage (or MCP usage_stats).
• Lane precedence is manual > browser > REST per tool call; on UpstreamChallengeError with browser enabled, chat, agent, and deep_research fall back to the browser lane automatically. Other conversation tools do not share this automatic fallback.
• Long calls: light DR typically takes tens of seconds. Heavy DR can use 1800 s for initial SSE plus another 1800 s polling; allow a tool timeout above 3600 s plus startup overhead (per-client notes: Client setup).
• Environment: CODEX_HOME (account selection), GPT2AGENT_SENTINEL_BRIDGE, GPT2AGENT_SENTINEL_BRIDGE_OFF=1, GPT2AGENT_RAW_DUMP (debug frames) — full table in Configuration.
• Claims in this README cite dates; treat anything older than a week as needing a re-probe. Evidence-trail paths live in the repo's CLAUDE.md.

Limitations

One line each; details and dates in the FAQ:

• gpt_chat g-p- store GPTs → 422 (payload reverse-engineered for g- only).
• Work-only slugs (gpt-6-sol, gpt-6-luna, …) silently resolve to gpt-5-6 on the Chat surface; deepest Chat model is gpt-6-pro.
• Light DR rides the chat model since the 2026-09-22 GPT-6 rollout retired the research lane upstream; occasional knowledge-only answers may lack Sources.
• deep_research_heavy needs the Deep Research connector (Settings → Connectors).
• Not yet supported: Sora video, Operator/CUA, voice sessions, Projects, Tasks (write), file upload. Requires an active Plus/Pro subscription.

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
bash .claude/verify.sh              # full offline suite + ruff, zero network

Testing

• Offline: the full unit/contract suite (live auto-skip via SKIP_LIVE)
• Parameter contracts: tests/test_param_matrix.py
• Live matrix: scripts/agent-user-journey.sh <worktree>
• Release gate: scripts/release-emulation-test.sh <worktree>

Release

1. Release PR: bump version in 4 files (pyproject.toml, gpt2agent/__init__.py, .claude-plugin/plugin.json, server.json) + dated CHANGELOG.md entry.
2. Verify: python scripts/verify_release.py
3. After merge, tag the merge SHA (annotated) and push — CI publishes to PyPI (trusted publishing) + GitHub Release. Full runbook incl. the owner publish gate: docs/release-validation.md.

After the release PR is merged, read its exact merge SHA, prove that commit is on origin/main, check out that reviewed tree, then create and push only the intended annotated tag:

set -euo pipefail
git fetch --no-tags origin main:refs/remotes/origin/main
read -r -p "Merged release PR number: " PR_NUMBER
RELEASE_SHA=$(gh pr view "$PR_NUMBER" --json mergeCommit,state   --jq 'select(.state == "MERGED") | .mergeCommit.oid')
test -n "$RELEASE_SHA"
git merge-base --is-ancestor "$RELEASE_SHA" origin/main
test -z "$(git status --porcelain)"
git switch --detach "$RELEASE_SHA"
trap 'git switch - >/dev/null || true' EXIT
test "$(git rev-parse HEAD)" = "$RELEASE_SHA"
VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
TAG="v$VERSION"
python scripts/verify_release.py --tag "$TAG"
REMOTE_TAG_SHA="$(git ls-remote --tags origin | awk -v ref="refs/tags/$TAG" '$2 == ref { print $1 }')"
if [ -n "$REMOTE_TAG_SHA" ]; then
  echo "Release tag already exists on origin: $TAG" >&2
  exit 1
fi
git tag -a "$TAG" "$RELEASE_SHA" -m "gpt2agent $VERSION"
git push origin "refs/tags/$TAG"
trap - EXIT
git switch -

If a publish or downstream release job fails, use GitHub Actions' Re-run failed jobs on that same run (artifact reuse). Do not re-run the whole workflow after any file reaches PyPI: sdists are not byte-reproducible and the hash guard rejects rebuilt bytes for an existing version.

License

MIT. Third-party attributions: NOTICES.

Acknowledgments

• lanqian528/chat2api — POW solver (MIT)
• Sentinel bridge technique studied from public reverse-engineering (2026); clean-room spec: docs/dev/specs/sentinel-vm.md
• basketikun/chatgpt2api — survey of ChatGPT backend API patterns