Run npx -y zephex setup --vscode first — it writes stdio (type stdio, npx -y zephex, ZEPHEX_API_KEY) to .vscode/mcp.json so workspace tools work. Optional HTTP blocks below if you only need cloud tools and will pass github: paths.
Official VS Code MCP documentation: VS 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: .vscode/mcp.json (project) or VS Code user mcp.json (see setup.ts vscodeUserConfigPath)
VS Code needs a local npx zephex child process so get_project_context / check_test can read files in your workspace.
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 --vscodeSkip browser OAuth — paste a key from zephex.dev/dashboard/keys. Must start with mcp_prod_, mcp_dev_, or mcp_sk_.
npx -y zephex setup --vscode --api-key mcp_prod_your-key-hereservers.zephex with type stdio — required for workspace file tools: Transport: stdio (see .vscode/mcp.json (project) or VS Code user mcp.json (see setup.ts vscodeUserConfigPath)).
{ "servers": { "zephex": { "type": "stdio", "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
Fastest: npx -y zephex setup --vscode. VS Code uses top-level servers (not mcpServers). Match the shape exactly or MCP will not load.
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 stdio + command npx — required for get_project_context on the open workspace. Matches writeVscodeConfig in setup.ts.
{ "servers": { "zephex": { "type": "stdio", "command": "npx", "args": ["-y", "zephex"], "env": { "ZEPHEX_API_KEY": "mcp_sk_your_key_here" } } }}No local npx; repo tools need github:owner/repo in chat. Password prompt — do not commit real keys.
{ "inputs": [ { "type": "promptString", "id": "zephex-api-key", "description": "Zephex API Key", "password": true } ], "servers": { "zephex": { "type": "http", "url": "https://zephex.dev/mcp", "headers": { "Authorization": "Bearer ${input:zephex-api-key}" } } }}Add mcp.json to .gitignore if you paste a key.
{ "servers": { "zephex": { "type": "http", "url": "https://zephex.dev/mcp", "headers": { "Authorization": "Bearer mcp_sk_your_key_here" } } }}Tip
User-level MCP: Command Palette → MCP: Open User Configuration — same JSON shape, applies to all workspaces.
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 VS Code does not show Zephex tools — indexed for docs search.
VS Code npx not found for Zephex
GUI apps miss nvm/fnm PATH. Run npx -y zephex@latest repair, install Node via official pkg/brew, fully quit VS Code.
You do not call tools yourself — ask your agent in plain language. Try these once Zephex is connected:
“In Copilot Agent mode, use check_package task=upgrade from react 17 to react 19 and list breaking changes.”
Upgrade planning without pasting entire changelogs into the chat.
“get_project_context on this VS Code workspace, then find_code validateSession.”
Workspace root is usually enough when the correct folder is open in the explorer.
“read_code the Prisma schema models block in our backend service.”
Targeted symbol/file read instead of @-mentioning a 2,000-line schema file.
“Before pip install requests-oauthlib, check_package it for typosquat signals.”
Python registry check runs the same way as npm from VS Code MCP.
“check_test: add OpenTelemetry tracing to our Express routes.”
Returns a minimal file list with risk notes for Copilot edits.
“audit_headers on our production Vercel URL and suggest copy-paste header fixes.”
Security grade without cloning the deployment repo locally.
Copilot Agent mode must be on. Say “this workspace” for open-folder context; paste pwd from the integrated terminal if tools return empty.
These situations usually mean the setup cannot work until you fix the underlying issue:
zephex shows 0 tools
Reload Window; verify type "stdio" if using setup, or type "http" only if you chose HTTP blocks.
Connection failed / 401
Re-enter key at prompt. If using Bearer-in-file block, check Authorization: Bearer mcp_sk_....
JSON syntax error
No comments or trailing commas. Top-level keys: inputs (optional) and servers.
Project tools return empty
Open repo root as workspace. Terminal: pwd — use that path or github: URL in the prompt.
After Copilot connects to .vscode/mcp.json, these ten remote tools appear in Agent mode (not plain 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.