Skip to content

docs(codex-plugin): document type='http' workaround for plugin-add bug#231

Closed
Aryamanz29 wants to merge 1 commit into
mainfrom
aryaman/codex-plugin-type-workaround
Closed

docs(codex-plugin): document type='http' workaround for plugin-add bug#231
Aryamanz29 wants to merge 1 commit into
mainfrom
aryaman/codex-plugin-type-workaround

Conversation

@Aryamanz29
Copy link
Copy Markdown
Member

Summary

Documents a known issue with Codex CLI's codex plugin add command — it drops the type field from the bundled .mcp.json when writing into ~/.codex/config.toml. Without type = \"http\" Codex tries to launch the URL as a subprocess and tool discovery silently returns 0 tools.

Why this matters

Empirically reproduced on a fresh install:

  1. codex plugin marketplace add https://github.com/atlanhq/agent-toolkit
  2. codex plugin add atlan@atlan ✅ (plugin installed)
  3. ~/.codex/config.toml ends up with:
    [mcp_servers.atlan]
    url = \"https://mcp.atlan.com/mcp\"
    enabled = true
    # ↑ note: missing `type = \"http\"`
  4. Codex session opens → user prompts "Find tables..." → agent says "I don't see an Atlan callable surfaced through tool discovery yet" and falls back to spawning codex exec child processes as a workaround.

What this PR changes

Adds a callout in codex-plugin/README.md right after the codex plugin add instructions explaining:

  • The exact symptom (zero tools loaded, codex exec workarounds)
  • What [mcp_servers.atlan] should look like
  • That Codex must be fully quit and relaunched after editing config.toml (mid-session edits don't take effect)

What this PR is NOT

  • The plugin's own codex-plugin/.mcp.json is already correct — it specifies \"type\": \"http\". This is a Codex CLI bug, not a plugin source issue.
  • No code changes. README-only.

Follow-up

File an upstream issue against openai/codex so the workaround can eventually be removed. Until then, this README note saves the next user 30+ minutes of debugging.

🤖 Generated with Claude Code

`codex plugin add` does not preserve the `type` field from the plugin's
bundled `.mcp.json` when writing into `~/.codex/config.toml`. Without
`type = "http"`, Codex tries to spawn the URL as a subprocess instead
of opening an HTTPS/OAuth connection — tool discovery silently returns
zero tools and the agent falls back to weird `codex exec` shell-out
workarounds.

Empirically reproduced on Codex CLI: a fresh `codex plugin add atlan@atlan`
yielded a config section missing the `type` line. Adding it manually
and restarting Codex fixes tool discovery and the OAuth flow.

The plugin's own `codex-plugin/.mcp.json` already specifies
`"type": "http"` correctly — this is a Codex CLI bug. Documenting the
post-install workaround until OpenAI fixes the installer.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@Aryamanz29 Aryamanz29 requested review from Hk669 and firecast as code owners June 3, 2026 16:20
@Aryamanz29
Copy link
Copy Markdown
Member Author

Closing — wrong place for the fix. The plugin's .mcp.json is already correct; the bug is in Codex CLI's codex plugin add command. Documenting a manual edit-your-config step in our plugin README is misleading. Right answer is an upstream issue at openai/codex (and meanwhile, point users at the install path that works).

@Aryamanz29 Aryamanz29 closed this Jun 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant