Was this page helpful?
npx -y zephex setup --gemini writes stdio (command/args/env) to settings.json — same as writeGeminiConfig in setup.ts. httpUrl HTTP is optional.
Official Gemini CLI MCP documentation: Gemini CLI MCP docs
HTTP and stdio setups both need a key from your Zephex dashboard. OAuth-only flows (ChatGPT, Claude.ai web) sign you in in the browser instead — skip this section for those.
Gemini CLI stdio lets the local zephex bridge read project files; httpUrl-only skips local FS.
Runs the same code as mcp-proxy/src/commands/setup.ts — OAuth in browser, creates a CLI key, writes your editor config, verifies tools.
npx -y zephex setup --geminiSkip browser OAuth — paste a key from zephex.dev/dashboard/keys. Must start with mcp_prod_, mcp_dev_, or mcp_sk_.
npx -y zephex setup --gemini --api-key mcp_prod_your-key-herecommand/args/env in mcpServers: Transport: stdio (see ~/.gemini/settings.json or <project>/.gemini/settings.json).
{ "mcpServers": { "zephex": { "command": "npx", "args": ["-y", "zephex"], "env": { "ZEPHEX_API_KEY": "mcp_sk_your_key_here" } } }}After CLI install, fully restart the app if tools do not appear. Manual JSON/TOML blocks below are equivalent — use them when CLI commands are unavailable.
Full comparison: HTTP vs stdio · npx zephex reference
Run npx zephex setup --gemini first; manual edits go in mcpServers.
Replace mcp_sk_your_key_here with your key from Dashboard → API Keys. Copy the full key once at creation — paste into Authorization: Bearer … for HTTP configs, or into ZEPHEX_API_KEY for stdio/npx configs.
command npx, args [-y, zephex], env ZEPHEX_API_KEY.
{ "mcpServers": { "zephex": { "command": "npx", "args": ["-y", "zephex"], "env": { "ZEPHEX_API_KEY": "mcp_sk_your_key_here" } } }}Requires Accept header; repo tools need github: paths.
{ "mcpServers": { "zephex": { "httpUrl": "https://zephex.dev/mcp", "headers": { "Authorization": "Bearer mcp_sk_your_key_here", "Accept": "application/json, text/event-stream" } } }}Note
Project-local config: <repo>/.gemini/settings.json overrides global for sessions started in that directory (per Gemini docs).
After saving your config, confirm Zephex is connected before you rely on it in real work.
You do not call tools yourself — ask your agent in plain language. Try these once Zephex is connected:
“gemini chat: check_package on lodash-es before I bump the version in package.json.”
CLI session calls the hosted tool over httpUrl transport — no local MCP binary.
“get_project_context on the current directory, then scope_task for adding i18n.”
Terminal cwd often maps to the repo root when you launched Gemini from there.
“read_code function exportUserData in src/api/users.ts with compact output.”
AST slice for one handler instead of cat-ing the whole routes file.
“audit_package on axios 0.x → 1.x for our internal SDK repo.”
CVE and migration notes inline in the CLI transcript.
“audit_headers https://api.mycompany.com/health”
TLS and header report from a headless CLI workflow.
“find_code ENVIRONMENT variable definitions — show enclosing blocks.”
Faster than manual ripgrep when you do not know the config layout.
You do not pick tools from a menu — ask your agent in normal sentences. Half of the tools only need a package name or URL; the other half need to know which codebase you mean (your Mac/Windows project folder or a GitHub repo).
These situations usually mean the setup cannot work until you fix the underlying issue:
zephex missing from /mcp
Save settings.json before launch. Valid JSON under mcpServers. Restart CLI.
Connected but no tools
Valid mcpServers JSON; restart Gemini after setup.
npx not found
Install Node 18+; ensure PATH visible to Gemini when launched from Dock.
401 or auth errors
Bearer + key in headers. Both Authorization and Accept present.
Project tools empty
cd to repo root or specify github:owner/repo in the same message.
Global vs project settings conflict
If both ~/.gemini/settings.json and .gemini/settings.json exist, confirm which file you edited for this session.
Streamable HTTP errors on older CLI
Upgrade @google/gemini-cli; keep Accept: application/json, text/event-stream in headers.
Gemini CLI loads httpUrl MCP from settings.json — ten tools, no separate Zephex install:
get_project_context
Reads your project structure, dependencies, scripts, env vars, and framework markers in one call. Replaces manually opening package.json, tsconfig, and multiple config files at the start of every session.
read_code
AST-based code extraction: pass a symbol name and get the implementation without reading entire files. Supports symbol lookup, batched file reads, and structural outlines for large files.
find_code
Ranked search across the repo for definitions, usages, and patterns. Faster than blind grep when the agent does not know where a symbol lives.
check_package
Live registry lookup for npm, PyPI, Cargo, and Go modules. Surfaces typosquat risk, maintainer changes, and suspicious version jumps before you run install.
audit_package
Deep package intelligence: CVEs with severity, breaking changes between versions, migration notes, and peer-dependency conflicts.
explain_architecture
Generates Mermaid diagrams for auth flows, service boundaries, and module dependencies so the agent reasons about structure instead of guessing.
scope_task
Turns a task description into the smallest file set to read or edit, with risk ratings and caller impact notes.
audit_headers
Grades a deployed URL for CSP, HSTS, TLS, cookies, and redirects. Returns fix snippets for common hosts (Vercel, Cloudflare, Nginx).
keep_thinking
Structured multi-step debugging: tracks hypotheses and conclusions so long investigations do not loop.
Zephex_dev_info
Expert patterns for authentication, databases, frontend frameworks, deployment, and mobile stacks when the agent needs vetted guidance.