Connect Zephex to Claude Code with claude mcp add (HTTP), npx -y zephex setup --claude, or ~/.claude.json. Hosted endpoint https://zephex.dev/mcp — stdio via npx is only a fallback when HTTP fails.
Official Claude Code MCP documentation: Claude Code 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: ~/.claude.json or <project>/.mcp.json
Claude Code supports HTTP MCP; the wizard runs claude mcp add --transport http when the CLI is installed.
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 --claudeSkip browser OAuth — paste a key from zephex.dev/dashboard/keys. Must start with mcp_prod_, mcp_dev_, or mcp_sk_.
npx -y zephex setup --claude --api-key mcp_prod_your-key-heresetup.ts runs this when the claude binary is on PATH; otherwise it writes ~/.claude.json HTTP JSON.
claude mcp add --scope user --transport http zephex \ https://zephex.dev/mcp \ --header "Authorization: Bearer mcp_sk_your_key_here"Paste if you are not using the CLI: Transport: http (see ~/.claude.json or <project>/.mcp.json).
{ "mcpServers": { "zephex": { "type": "http", "url": "https://zephex.dev/mcp", "headers": { "Authorization": "Bearer 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
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.
Recommended — Claude Code calls https://zephex.dev/mcp directly. Matches Anthropic’s HTTP MCP docs.
{ "mcpServers": { "zephex": { "type": "http", "url": "https://zephex.dev/mcp", "headers": { "Authorization": "Bearer mcp_sk_your_key_here" } } }}Use only if HTTP is blocked. Claude spawns npx -y zephex; key goes in env.ZEPHEX_API_KEY, not Bearer headers.
{ "mcpServers": { "zephex": { "command": "npx", "args": ["-y", "zephex"], "env": { "ZEPHEX_API_KEY": "mcp_sk_your_key_here" } } }}Note
Claude Desktop uses a different config path than Claude Code. This page is for the CLI only. HTTP URL must be exactly https://zephex.dev/mcp.
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 Code does not show Zephex tools — indexed for docs search.
Claude Code MCP config location
~/.claude.json (user) or .mcp.json in project root. Not the same file as Claude Desktop.
You do not call tools yourself — ask your agent in plain language. Try these once Zephex is connected:
“claude mcp session: check_package task=upgrade on boto3 version pin in our Lambda repo.”
HTTP transport from ~/.claude.json — tools in CLI sessions.
“get_project_context on . — then find_code IAM policy builders.”
AWS-heavy repos: map stack then search security code.
“check_test: add SQS dead-letter handling to workers.”
Infrastructure code scoped before Claude Code edits.
“read_code the handler for processPayment in src/handlers.”
Single-function focus for code review style prompts.
“check_package on an internal npm scope package.”
Typosquat check for private-looking names.
“Zephex_dev_info for Lambda idempotency + DynamoDB — apply to our handler.”
Patterns then local read_code.
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:
Tools listed but every call fails auth
HTTP: Bearer in headers. stdio: ZEPHEX_API_KEY in env only — do not mix both on one server entry.
npx: command not found inside Claude Code
Install Node 18+ or switch to hosted HTTP (no npx required).
Claude Code HTTP MCP — ten tools via claude mcp or ~/.claude.json:
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.