Connect Zephex with npx -y zephex setup --cursor (fastest), Cursor Settings → MCP, or .cursor/mcp.json url + Bearer. Hosted https://zephex.dev/mcp is recommended; stdio npx is documented as fallback.
Official Cursor MCP documentation: Cursor 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: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
Cursor supports remote url + Bearer; the wizard writes hosted HTTP to https://zephex.dev/mcp.
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 --cursorSkip browser OAuth — paste a key from zephex.dev/dashboard/keys. Must start with mcp_prod_, mcp_dev_, or mcp_sk_.
npx -y zephex setup --cursor --api-key mcp_prod_your-key-hereurl + Bearer — no npx child process: Transport: http (see .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)).
{ "mcpServers": { "zephex": { "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
Fastest: npx setup --cursor (top). Or paste JSON / use Settings → MCP — all should use url https://zephex.dev/mcp for hosted HTTP.
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.
url + headers — recommended for Cursor 1.0+.
{ "mcpServers": { "zephex": { "url": "https://zephex.dev/mcp", "headers": { "Authorization": "Bearer mcp_sk_your_key_here" } } }}command/args/env — use only if HTTP fails; remove url block if you switch.
{ "mcpServers": { "zephex": { "command": "npx", "args": ["-y", "zephex"], "env": { "ZEPHEX_API_KEY": "mcp_sk_your_key_here" } } }}Tip
Project .cursor/mcp.json overrides or merges with global ~/.cursor/mcp.json depending on Cursor version — if tools vanish, check which file you edited.
Note
Project .cursor/mcp.json vs global ~/.cursor/mcp.json — know which file you edited. See /docs/npx-zephex for all setup flags.
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 Cursor does not show Zephex tools — indexed for docs search.
Where is Cursor MCP config?
~/.cursor/mcp.json (global) or .cursor/mcp.json in the opened project. list shows both.
Cursor shows 0 Zephex tools
Confirm url https://zephex.dev/mcp + Authorization Bearer. Remove any command/npx stdio block. Quit Cursor completely.
You do not call tools yourself — ask your agent in plain language. Try these once Zephex is connected:
“In Cursor Agent, run check_package on @scope/new-package before I add it to package.json.”
Registry signals surface in-chat so Composer does not blindly install a suspicious npm name.
“Map this monorepo: get_project_context on the workspace root, then explain_architecture for the API layer.”
One snapshot plus a Mermaid diagram beats opening six config files by hand.
“find_code where RateLimiter is defined and read_code that class body only.”
Search then AST read keeps the Agent context small on large TypeScript trees.
“check_test: migrate our auth middleware to JWT — list files and caller risks.”
check_test narrows edits before Cursor rewrites half the repo.
“audit_headers on https://staging.myapp.com — CSP and HSTS gaps only.”
No local path needed; works from any Cursor chat with the URL in scope.
“This flaky CI test — use keep_thinking to track hypotheses, then Zephex_dev_info for Vitest + Next.js patterns.”
Structured debugging plus vetted stack guidance in one Agent thread.
In Cursor Agent, name the workspace folder or github: URL when a tool needs a repo. Cloud tools (check_package, audit_headers) never need a path.
These situations usually mean the setup cannot work until you fix the underlying issue:
zephex shows 0 tools
Quit Cursor completely, reopen, new chat. Confirm url + headers, not command.
Connection failed
Bearer + space + full key. URL exactly https://zephex.dev/mcp.
JSON error
Top-level mcpServers. No trailing commas. Valid JSON only.
Wrong config file
Must be inside the opened project root, not a parent monorepo folder unless that is your workspace.
Works in terminal npx, not Cursor
You may still have stdio config — switch to remote url block on this page.
Once Cursor lists zephex under Tools & MCP, the same ten hosted capabilities are available in every Agent chat:
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.