Was this page helpful?
npx -y zephex setup --droid writes stdio to ~/.factory/mcp.json or <repo>/.factory/mcp.json (command/args/env). HTTP type:http blocks are optional.
Official Factory AI (Droid) MCP documentation: Factory Droid 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.
Factory Droid wizard writes command/args/env (stdio), not type http — use HTTP manually only if you accept github: paths for repo tools.
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 --droidSkip browser OAuth — paste a key from zephex.dev/dashboard/keys. Must start with mcp_prod_, mcp_dev_, or mcp_sk_.
npx -y zephex setup --droid --api-key mcp_prod_your-key-hereNo type:http — command/args/env only: Transport: stdio (see ~/.factory/mcp.json or <project>/.factory/mcp.json).
{ "mcpServers": { "zephex": { "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
Run npx zephex setup --droid (add --project from repo root for .factory/mcp.json).
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.
No type:http — command/args/env per writeDroidConfig.
{ "mcpServers": { "zephex": { "command": "npx", "args": ["-y", "zephex"], "env": { "ZEPHEX_API_KEY": "mcp_sk_your_key_here" } } }}Best for API keys: ~/.factory/mcp.json is not committed to git. Matches Factory docs for type http + url + headers.
{ "mcpServers": { "zephex": { "type": "http", "url": "https://zephex.dev/mcp", "headers": { "Authorization": "Bearer mcp_sk_your_key_here" }, "disabled": false } }}Commit this to the repo without secrets. Export ZEPHEX_API_KEY=mcp_sk_... in your shell before droid starts.
{ "mcpServers": { "zephex": { "type": "http", "url": "https://zephex.dev/mcp", "headers": { "Authorization": "Bearer ${ZEPHEX_API_KEY}" }, "disabled": false } }}Tip
Type /mcp inside droid to enable/disable servers, view tools, and clear OAuth (not needed for Zephex Bearer auth).
Note
Factory layers user, folder, and project mcp.json — user wins over project for the same server name. Project-defined servers cannot be removed via CLI; edit the file directly.
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:
“Droid: audit_package comparing our pinned eslint-config version to latest stable.”
Breaking-change summary before Factory refactors lint rules across repos.
“get_project_context on this .factory/mcp.json project root.”
Stack snapshot aligns Droid with your actual package manifests.
“find_code usages of deprecated API keys in src/lib/billing.”
Search narrows a refactor blast radius.
“scope_task: add webhook signature verification to inbound routes.”
Risk-rated file list for autonomous Droid edits.
“check_package on a private-scope npm name we might vendor.”
Typosquat and maintainer signals pre-install.
“Zephex_dev_info for Stripe webhook idempotency in Node — then read_code our handler.”
Pattern guidance plus precise code slice.
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:
zephex does not appear in /mcp
Confirm .factory/mcp.json at project root (case-sensitive on Linux). Use type http + url. Check user ~/.factory for overrides.
401 / unauthorized
Bearer + full key in headers, or export ZEPHEX_API_KEY when using ${ZEPHEX_API_KEY} in JSON.
Connection fails immediately
URL must be https://zephex.dev/mcp. Not serverUrl (that is Windsurf) — Factory uses url.
npx not found (stdio leftover)
Remove stdio block — this guide is HTTP-only to the hosted endpoint.
Tools empty for code but packages work
Pass github:owner/repo or absolute path — Droid does not auto-detect monorepo subpackages.
Cannot remove server via CLI
Project-level entries: edit .factory/mcp.json or droid mcp remove only works for user-added servers.
Factory Droid shares one hosted toolset across user and project mcp.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.
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.