Was this page helpful?
Run npx -y zephex setup --opencode — the wizard writes type local + npx -y zephex (same as writeOpenCodeConfig in setup.ts). Remote HTTP is optional only if you will pass github: paths for repo tools.
Official OpenCode MCP documentation: OpenCode 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.
OpenCode local type spawns npx -y zephex with ZEPHEX_API_KEY — remote-only HTTP cannot read your project tree.
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 --opencodeSkip browser OAuth — paste a key from zephex.dev/dashboard/keys. Must start with mcp_prod_, mcp_dev_, or mcp_sk_.
npx -y zephex setup --opencode --api-key mcp_prod_your-key-heretype local + environment.ZEPHEX_API_KEY: Transport: stdio (see ~/.config/opencode/opencode.json or <project>/opencode.json).
{ "$schema": "https://opencode.ai/config.json", "mcp": { "zephex": { "type": "local", "command": ["npx", "-y", "zephex"], "enabled": true, "environment": { "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
OpenCode distinguishes local (command) vs remote (url) in opencode.json. Zephex is always remote — one mcp.zephex block with type remote.
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.
type: "local", command npx, environment.ZEPHEX_API_KEY — matches setup.ts.
{ "$schema": "https://opencode.ai/config.json", "mcp": { "zephex": { "type": "local", "command": ["npx", "-y", "zephex"], "enabled": true, "environment": { "ZEPHEX_API_KEY": "mcp_sk_your_key_here" } } }}type: "remote" + url — no local FS; use github:owner/repo in prompts for repo tools.
{ "$schema": "https://opencode.ai/config.json", "mcp": { "zephex": { "type": "remote", "url": "https://zephex.dev/mcp", "headers": { "Authorization": "Bearer mcp_sk_your_key_here" }, "enabled": true } }}Tip
Delete the entire old local zephex block when migrating — partial merges leave type: local active.
Note
Do not keep local and remote zephex entries at once.
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:
“OpenCode session: get_project_context on the repo containing opencode.json.”
Remote mcp type confirms stack before OpenCode autonomous edits.
“find_code CLI argument parsing in cmd/*.”
Go/Rust/TS CLI repos — search finds the right entry files.
“check_package on a theme plugin before we add it to the project.”
Install guard for OpenCode-driven package changes.
“scope_task: add shell completion for our CLI subcommands.”
Scoped generators and cmd files.
“audit_package for our oclif major version bump.”
CLI framework migration risks spelled out.
“audit_headers on our CLI's documented API base URL.”
Validates the endpoint customers call.
OpenCode terminal sessions use the cwd when you launch opencode from a repo root. Remote mcp type needs no npx on PATH.
These situations usually mean the setup cannot work until you fix the underlying issue:
No MCP
Top-level mcp key with type remote, not local.
0 tools
url + headers; enabled: true.
Still runs npx
Delete local/command zephex block.
Schema error
Keep valid JSON; $schema line optional.
Wrong cwd
Launch opencode from repo root for get_project_context.
OpenCode remote mcp entry — ten tools for terminal sessions:
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.