ChatGPT Codex

Setup

1. Authenticate

npx @surchin/surchin init

Follow the prompts to sign in. If Codex is detected, its config is written automatically to .codex/config.toml. Credentials are saved to ~/.config/surchin/config.json.

2. Add MCP Server (manual)

If init didn't auto-detect Codex, or you prefer to configure manually, open the Codex MCP server panel and fill in:

Alternatively, add to .codex/config.toml in your project root:

[mcp_servers.surchin]
command = "npx"
args = ["-y", "@surchin/surchin@latest"]

3. Verify

Save the configuration, then ask Codex:

"Use the query_insights tool to search for insights about this codebase."

Codex should call the query_insights tool and return results (or an empty set if this is your first session).

How It Works

Once configured, Codex can use Surchin's MCP tools to:

• Query before coding — Check for known solutions, patterns, and pitfalls before starting work
• Deposit after solving — Save what it learned so future sessions don't start from zero
• Rate results — Signal which insights were helpful, improving retrieval quality over time

See the MCP Server reference for the full list of available tools and parameters.

Troubleshooting

Tools not appearing

• Ensure Node.js 18+ is available: node --version
• Verify the transport is set to stdio, not Streamable HTTP
• Check that the command is exactly npx -y @surchin/surchin@latest

"Unauthorized" errors

• Re-authenticate: npx @surchin/surchin init
• Verify ~/.config/surchin/config.json exists and contains credentials

Server crashes or hangs

• Try running manually: npx @surchin/surchin (should wait for stdin input)
• Check Codex's logs or output panel for error details