Fastest: npx -y zephex setup --hermes (or hermes mcp install zephex from the catalog). Get your key at /connect/hermes. Then /reload-mcp in Hermes.
Official Hermes MCP documentation: Hermes Agent 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: ~/.hermes/config.yaml + ~/.hermes/.env
Hermes stdio via npx -y zephex (local file tools); also writes ZEPHEX_API_KEY to ~/.hermes/.env. Run /reload-mcp after setup.
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 --hermesSkip browser OAuth — paste a key from zephex.dev/dashboard/keys. Must start with mcp_prod_, mcp_dev_, or mcp_sk_.
npx -y zephex setup --hermes --api-key mcp_prod_your-key-heremcp_servers.zephex — then run /reload-mcp in Hermes: Transport: stdio (see ~/.hermes/config.yaml + ~/.hermes/.env).
mcp_servers: 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
Recommended: Hermes MCP catalog (stdio via npx). Manual HTTP YAML is optional. Project repos are selected in chat via paths.
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.
npx zephex setup --hermes writes stdio config plus ~/.hermes/.env — same transport as the Hermes catalog.
npx -y zephex setup --hermesnpx -y zephex setup --hermes --api-key mcp_prod_your-key-heremcp_servers.zephex under ~/.hermes/config.yaml
mcp_servers: zephex: command: npx args: - "-y" - "zephex" env: ZEPHEX_API_KEY: "mcp_sk_your_key_here"After you have a key from /connect/hermes, Hermes catalog install uses the same stdio transport.
hermes mcp install zephexhermes mcp test zephexHosted MCP with Bearer auth. Use only when you cannot run npx stdio locally.
mcp_servers: zephex: url: "https://zephex.dev/mcp" headers: Authorization: "Bearer mcp_sk_your_key_here"Tip
YAML is sensitive to indentation — zephex must line up under mcp_servers with two spaces per level.
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 Hermes does not show Zephex tools — indexed for docs search.
Hermes ZEPHEX_API_KEY required
Re-run npx -y zephex setup --hermes or hermes mcp install zephex. Confirm ~/.hermes/.env.
You do not call tools yourself — ask your agent in plain language. Try these once Zephex is connected:
“Hermes agent: get_project_context on github:anthropics/claude-code — scripts and deps.”
YAML mcp_servers remote session — no Hermes-local Zephex binary.
“find_code tool dispatch table in our agent repo.”
Locate extension points before patching Hermes workflows.
“check_package on PyPI package proposed in a skill file.”
Supply-chain gate for autonomous Hermes runs.
“keep_thinking across a multi-step refactor — record what we already ruled out.”
Persistent reasoning for long Hermes jobs.
“explain_architecture for our plugin host and MCP client boundary.”
Clear diagram for contributors.
“check_package task=upgrade bump for httpx in our pyproject.toml.”
Version delta risks before poetry lock refresh.
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_API_KEY is required (npx)
Re-run hermes mcp install zephex or confirm ~/.hermes/.env contains ZEPHEX_API_KEY=your_key.
YAML parse error on launch
Use spaces not tabs. Quote url and Authorization. Validate with a YAML linter.
401 from Zephex (HTTP YAML)
Authorization value must be Bearer mcp_sk_... inside double quotes.
Works on Mac path, not Windows
Use C:\Users\you\project or github: URL — Hermes does not translate ~ across platforms in tool args.
explain_architecture empty
Pass github:owner/repo or absolute path to repo root in the same request.
Hermes mcp_servers YAML connects to the same ten-tool hosted endpoint:
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.