Hive Intelligence home
Hive Intelligence
GitHub

Install in Your AI Client

Connect Hive to Codex CLI

Written by , Product docsLast updated

Connect Codex CLI to Hive with two commands and browser authorization. Codex registers the hosted MCP URL, discovers Hive's OAuth server, and stores the resulting credential outside your project. No Hive API key is required for the recommended path.

View MarkdownAsk ClaudeAsk ChatGPT

Before you start

  1. Install Codex CLI with npm install -g @openai/codex (or bun install -g @openai/codex). Verify with codex --version.
  2. Run codex mcp add --help and confirm it lists --url. If it does not, run codex update; if self-update is unavailable, update Codex through the package manager you originally used.

Codex stores MCP definitions in ~/.codex/config.toml and shares them with the Codex IDE extension and ChatGPT desktop app on the same host.

Run both commands:

bash
codex mcp add hive --url https://mcp.hiveintelligence.xyz/mcp
codex mcp login hive

The second command opens Hive's authorization page in your browser. Sign in, approve the requested MCP scopes, and return to the terminal. Codex stores the OAuth credential and refreshes it when needed; the MCP definition contains only Hive's public URL.

Check the result:

bash
codex mcp list

Live readiness gate

Hive enables this flow only after the production OAuth metadata, callback canaries, runtime health, and release identity agree. If /setup reports that OAuth is not live, use the API-key fallback below until the backend release passes that gate.

Option 2: API-key fallback

Use this for headless automation or an environment where a browser OAuth flow is unavailable. Create a key in /dashboard/keys, store it in your shell or secret manager, then register the same remote endpoint with a bearer-token environment variable:

bash
export HIVE_API_KEY="your_hive_api_key"
codex mcp add hive \
  --url https://mcp.hiveintelligence.xyz/mcp \
  --bearer-token-env-var HIVE_API_KEY

If hive already exists, remove it with codex mcp remove hive before changing authentication modes. Never put the plaintext key in a repository or a shared config.toml.

Option 3: Local stdio server

Use this when Codex needs a subprocess transport or when you want to supply upstream provider credentials directly. The 1.3.0 release candidate requires Node 22.12+.

toml
[mcp_servers.hive]
command = "npx"
args = ["-y", "-p", "hive-intelligence@latest", "hive"]

This starts a self-hosted MCP server. It does not use a hosted HIVE_API_KEY; add provider-specific entries to env only for the local integrations you want to enable.

Verify it worked

Start a new Codex session:

bash
codex

Then ask:

"What is the current price of BTC, ETH, and SOL?"

Codex should call Hive's get_price tool and surface the result inline. If you don't see a tool call, run /mcp inside Codex to confirm hive is listed and healthy.

Version note

OpenAI's current Codex MCP guide documents Streamable HTTP, bearer-token authentication, OAuth, and codex mcp login. The CLI reference documents --url, --bearer-token-env-var, and codex update. Older Codex builds may support local stdio while rejecting these newer remote flags.

What to ask in Codex

Codex shines at multi-step coding work that needs live data. Try:

  • "Generate a TypeScript client that calls Hive's wallet-balances tool and types the response strictly, with no any."
  • "Scan the top 20 DeFi pools on Base by APY, then write a Node script that emails me when a new pool enters the top 5."
  • "Run a honeypot check on this token before I hardcode the address in src/contracts.ts: 0x6B175474E89094C44Da98b954EedeAC495271d0F."
  • "Pull funding rates for BTC perpetuals across Binance, Bybit, and OKX, then commit a Markdown summary to docs/funding.md."

Codex chains tool calls and file edits in the same turn, so you don't need to name specific Hive tools.

Troubleshooting

codex: command not found. The global install didn't land on your PATH. Try npm root -g and confirm that directory's bin is on PATH, or reinstall with bun install -g @openai/codex.

unexpected argument '--url'. Your Codex build predates remote HTTP setup. Run codex update. If that command is unavailable, update through npm, Bun, Homebrew, or the installer you originally used, then confirm codex mcp add --help lists --url.

The OAuth browser does not open. Run codex mcp login hive explicitly. If /setup says the live OAuth contract is not ready, use the API-key fallback and retry OAuth after the backend release.

401 Unauthorized with the API-key fallback. --bearer-token-env-var takes an environment-variable name, not the key itself. Make sure HIVE_API_KEY is available in the same shell that launches Codex, then re-add the server if you changed authentication modes.

hive doesn't appear in /mcp. Run codex mcp list, remove a stale entry with codex mcp remove hive, and repeat the two recommended commands. Restart the Codex session after changing MCP configuration.

stdio transport, "npx: command not found". Install Node 22.12 or newer from nodejs.org, then restart Codex.

Other clients

Next steps

Previous
Grok / xAI
Next
Gemini CLI