Add this to your Claude Desktop MCP configuration file (claude_desktop_config.json). Zephex uses a small local npx bridge plus your API key to reach the hosted server — you do not need the Claude.ai web OAuth connector for this setup.
Official Claude Desktop MCP documentation: Claude Desktop MCP docs
Without MCP, your agent guesses project layout and misses supply-chain risk. Zephex connects one hosted endpoint so every session gets the same ten tools — no per-machine npm installs, no version drift across the team.
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.
Matches the published CLI (mcp-proxy/src/commands/setup.ts). One command signs you in, writes the correct transport, and verifies 10 tools.
Account teardown: logout vs disconnect · Connect MCP walkthrough
Search docs for “where is my MCP file” — the answer is always: run list first, then open the path it prints.
Documented paths: Run npx -y zephex@latest list
Full comparison: HTTP vs stdio · npx zephex reference
Claude Desktop only reloads MCP when you fully quit the app — saving the file is not enough while Claude stays open.
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.
Claude Desktop runs npx -y zephex locally. The bridge uses your API key to call the same hosted tools as other editors.
{ "mcpServers": { "zephex": { "command": "npx", "args": ["-y", "zephex"], "env": { "ZEPHEX_API_KEY": "mcp_sk_your_key_here" } } }}Tip
If Claude was launched from the Dock on Mac and npx is missing, launch Terminal once, run `which npx`, then open Claude from that same user session or use full paths to node/npx in the command field.
Note
Claude.ai in the browser uses a different flow (Settings → Connectors → OAuth, no API key in a file). See /docs/claude-ai. Claude Code uses ~/.claude.json — not this path.
Run these in a terminal when the editor UI is unclear — catches stale npm, wrong transport, and project shadows.
npx -y zephex@latest listnpx -y zephex@latest doctornpx -y zephex@latest repair# Fully quit the editor (Cmd+Q / Alt+F4), reopen, start a new agent sessionAfter saving your config, confirm Zephex is connected before you rely on it in real work.
Questions people ask when Claude Desktop does not show Zephex tools — indexed for docs search.
How do I connect Zephex to claude-desktop?
Fastest: npx -y zephex setup (browser sign-in, writes config, verifies 10 tools). Or paste manual config on this page, save, fully quit the app, reopen.
Where did setup save my claude-desktop MCP config?
Run npx -y zephex@latest list — it prints every config path on this machine that references Zephex.
claude-desktop works in terminal but not in the editor
GUI apps often lack nvm/fnm PATH. Run npx -y zephex@latest repair, ensure Node is on system PATH, fully quit the editor.
How do I disconnect Zephex from claude-desktop?
mcpcli disconnect --all or remove the zephex block manually from your config file.
You do not call tools yourself — ask your agent in plain language. Try these once Zephex is connected:
“Claude Desktop: after stdio connect, run check_package on a crate name from crates.io.”
Cargo registry check from the desktop app’s MCP tool list.
“get_project_context on /Users/me/Projects/saas-app — I'm on Mac and gave the full path.”
Absolute path disambiguates when multiple repos exist on the machine.
“find_code SessionStore in this repo and summarize call sites.”
Search tool reduces wrong-file edits in Desktop chat.
“read_code the React root layout component — outline first if over 300 lines.”
Outline-then-symbol pattern for large UI files.
“keep_thinking while debugging a memory leak — don't lose earlier conclusions.”
Long Desktop sessions stay structured.
“check_package task=upgrade for django 4.2 → 5.0 in our requirements.txt project.”
Migration and CVE notes before Claude suggests bulk edits.
Claude Desktop stdio passes ZEPHEX_API_KEY via env. Repo tools need an absolute Mac/Windows path in the message.
These situations usually mean the setup cannot work until you fix the underlying issue:
zephex never appears in MCP list
Validate JSON at jsonlint.com. Confirm file path (Mac Library path vs Windows AppData). Fully quit Claude, not reload window.
Works in Terminal, not in Claude Desktop
Dock-launched apps often miss nvm/fnm PATH. Use absolute paths to node and npx in command/args, or launch Claude from a shell where `which npx` succeeds.
Works in Claude Code, not Desktop
Claude Code uses ~/.claude.json. Desktop uses only claude_desktop_config.json — copy the zephex block to the Desktop file.
Tools fail with auth errors
Update ZEPHEX_API_KEY in env — no Bearer header in this stdio setup. Regenerate key if revoked.
Agent says it cannot access my files
Give absolute path: Mac /Users/yourname/... or Windows C:\Users\yourname\... or use github:owner/repo for remote repos.
Claude Desktop spawns stdio to Zephex — ten tools appear in the connector list after restart:
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.
explain_architecture
Generates Mermaid diagrams for auth flows, service boundaries, and module dependencies so the agent reasons about structure instead of guessing.
check_test
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.
project_memory
Persists decisions, gotchas, and conventions per project in ~/.zephex/memory (SQLite FTS5). recall before unfamiliar areas; remember after discoveries. Local stdio only on npx zephex.