Official goose MCP documentation: goose extensions docs
MCP endpointhttps://zephex.dev/mcp
AuthenticationAuthorization: Bearer mcp_sk_... (in extension headers)
Config file~/.config/goose/config.yaml
Why Zephex
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.
Before you start
- goose CLI or Desktop installed.
- A Zephex API key from Dashboard → API Keys.
- Network access to https://zephex.dev/mcp.
Get and paste your API key
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.
- Sign in at zephex.dev → Dashboard → API Keys (or /dashboard/api-keys).
- Click Create API key, give it a name you will recognize (e.g. "Kilo — work laptop"), then create.
- Copy the key as soon as it appears — Zephex only shows the full secret once. It starts with mcp_sk_ or a newer mcp_prod_… format.
- Paste into your config: either only the key in an env field (ZEPHEX_API_KEY), or the full HTTP header value Authorization: Bearer YOUR_KEY — match what your editor’s form asks for.
- Do not wrap the key in extra quotes inside JSON unless the file already quotes other string values.
- Never commit API keys to git. Revoke and create a new key in the dashboard if one leaks.
Setup policy for goose
Matches the published CLI (mcp-proxy/src/commands/setup.ts). One command signs you in, writes the correct transport, and verifies 10 tools.
Recommended commandgoose configure # or add streamable_http in ~/.config/goose/config.yaml
Project-scopedgoose configure # or add streamable_http in ~/.config/goose/config.yaml --project
Transportstdio (npx -y zephex + ZEPHEX_API_KEY)
Config parent keyextensions
Global vs project config
- goose is not in the setup.ts editor picker — use goose configure or ~/.config/goose/config.yaml.
- Prefer streamable_http extension with url + Bearer; remove old stdio npx extensions when migrating.
After setup
- goose is configured via extensions UI/YAML — not in setup.ts picker; use streamable_http manually or stdio extension.
- Fully quit the editor after setup — reload window alone is often not enough.
- Start a new agent/chat session so MCP tools register.
Account teardown: logout vs disconnect · Connect MCP walkthrough
Find where setup wrote your config
Search docs for “where is my MCP file” — the answer is always: run list first, then open the path it prints.
- Run npx -y zephex@latest list — canonical path list for goose.
- Wizard writes to: ~/.config/goose/config.yaml
- macOS uses ~/ and ~/.config; Windows uses %USERPROFILE% and %APPDATA%; Linux uses ~/.config.
Documented paths: ~/.config/goose/config.yaml
Configure in goose
goose is not in the setup.ts editor switch yet — use goose configure → Remote Extension (HTTP) or stdio extension; see Configuration below.
goose configure (interactive)
Add Extension → Remote (Streamable HTTP) or stdio per goose docs.
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.
Hosted HTTP vs npx stdio
- Recommended: npx -y zephex setup — goose is configured via extensions UI/YAML — not in setup.ts picker; use streamable_http manually or stdio extension.
- Config path: ~/.config/goose/config.yaml
- Manual stdio shape: command "npx", args ["-y","zephex"], env ZEPHEX_API_KEY (parent key: extensions).
- Optional hosted HTTP (https://zephex.dev/mcp + Bearer) only if you do not need automatic workspace file access — pass github: URLs in prompts.
- Never keep two zephex entries (stdio + HTTP) in the same config — pick one transport.
- Cloud-only tools (check_package, project_memory, audit_headers, keep_thinking, Zephex_dev_info) work on both transports.
- Repo tools (get_project_context, read_code, find_code, explain_architecture, check_test) need either stdio/npx setup or an explicit github:owner/repo or absolute path on HTTP.
Full comparison: HTTP vs stdio · npx zephex reference
How to connect Zephex
Desktop: Extensions → Add custom extension → Remote (Streamable HTTP). CLI: goose configure → Add Extension → Remote Extension.
- Copy your Zephex API key from the dashboard.
- CLI: run goose configure → Add Extension → Remote Extension (Streamable HTTP).
- Enter URL https://zephex.dev/mcp and name Zephex.
- Or edit ~/.config/goose/config.yaml with the YAML below (replace Bearer).
- Enable the extension in goose Desktop or goose configure → Toggle Extensions.
- Start a session and approve the extension if prompted.
- Test: ask goose to use check_package.
Configuration
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.
config.yaml (persistent)
streamable_http extension with url and Authorization header — production setup.
extensions: zephex: name: Zephex type: streamable_http url: https://zephex.dev/mcp headers: Authorization: "Bearer mcp_sk_your_key_here" enabled: true timeout: 300
Tip
Remove any old stdio zephex extension (npx -y zephex) to prevent duplicate servers.
Note
For Bearer on CLI-only setups, prefer config.yaml headers or Desktop custom extension env/header fields.
Verify, repair, disconnect (CLI)
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 session
Repair policy
- npx -y zephex@latest repair pins stdio to zephex@latest, fixes OpenCode command-array shape, and adds PATH hints for GUI-launched apps.
- repair migrates legacy HTTP → stdio for filesystem editors — not for Cursor, Claude Code global HTTP, or Crush.
Disconnect & skills
- disconnect --<editor> removes Zephex from config files the CLI knows about and revokes the API key found in those files.
- There is no disconnect --project flag — disconnect checks both global and project paths (project paths use your current terminal cwd).
- Terminal-only sign-out: mcpcli logout (editors unchanged). Full teardown: mcpcli logout --all.
- mcpcli disconnect --all
- Fresh OAuth: mcpcli reconnect --cursor
- Add agent guidance: mcpcli setup <editor> --with-skill or mcpcli skills --<editor>.
- Remove skills from one editor: mcpcli reset <editor> (disconnect + skill files).
- Remove all skill copies: mcpcli skills --remove.
Check that it works
After saving your config, confirm Zephex is connected before you rely on it in real work.
- Extensions panel: Zephex enabled (not disabled).
- goose session lists Zephex tools after approval.
- check_package without repo path succeeds.
Common searches
Questions people ask when goose does not show Zephex tools — indexed for docs search.
goose Zephex streamable HTTP
Add custom extension → Remote (Streamable HTTP), url https://zephex.dev/mcp, Authorization Bearer header.
Example ways to use the tools
You do not call tools yourself — ask your agent in plain language. Try these once Zephex is connected:
“goose session: check_package on npm package before enabling a new extension dependency.”
streamable_http extension calls hosted tools.
“get_project_context on the repo goose is running in.”
Aligns autonomous goose with actual manifests.
“check_test: add retry logic to our data pipeline scripts.”
Scoped scripts and libs before goose edits.
“find_code Dockerfile stages that copy secrets incorrectly.”
Security-focused search prompt.
“keep_thinking on goose loop behavior — document ruled-out causes.”
Long autonomous runs stay debuggable.
“check_package task=upgrade for our pinned terraform provider version bump.”
Infra repo upgrade intelligence.
Which tools need your project path?
Enable the Zephex streamable_http extension before starting goose session. Repo tools use the process working directory.
Need a repo or folder path
- get_project_context — full stack snapshot for one repo
- read_code — read functions/classes by symbol name
- find_code — search definitions and usages
- explain_architecture — Mermaid diagrams for the repo
- check_test — minimal file list for a task you describe
Work without a local project
- check_package — npm/PyPI/Cargo/Go registry safety (no repo path)
- project_memory — Cross-session project memory: remember decisions, gotchas, goals, conventions across sessions via local SQLite (stdio only).
- audit_headers — security grade for any HTTPS URL you own or may test
- keep_thinking — structured debugging notes across steps
- Zephex_dev_info — vetted patterns (auth, DB, deploy, etc.)
How to tell the agent where the code lives
- GitHub (no clone required): say github:owner/repo — example: github:vercel/next.js
- Local folder: give the absolute path to the project root (the folder that contains package.json, pyproject.toml, or go.mod).
- If your editor already has the repo open, try “use get_project_context on this workspace” first; if the tool returns empty, repeat with the full path or github: URL in the same chat.
- For read_code / find_code, name the symbol or search term in the same message as the path (e.g. “find_code AuthService in github:myorg/api”).
macOS and Windows paths
- macOS example path: /Users/yourname/Developer/my-app
- Windows example path: C:\Users\yourname\projects\my-app
- Replace yourname with your Mac or Windows login — the agent cannot guess your home directory.
- Cloud-only tools (check_package, audit_headers) never need your username or project folder.
When Zephex will not connect
These situations usually mean the setup cannot work until you fix the underlying issue:
- No internet or a firewall blocks outbound HTTPS to zephex.dev (port 443).
- API key never created, revoked, or pasted incorrectly (missing Bearer , extra quotes, or truncated copy).
- Wrong MCP URL — must be exactly https://zephex.dev/mcp (not /docs, not /api, no wrong host).
- Mixed stdio + HTTP — two zephex entries (npx and url) confuse many clients; keep one transport.
- Corporate proxy strips Authorization headers or chunked transfer encoding.
- Monthly request limit reached on the Free plan (555 requests/month) — tools stop until next cycle, share for bonus requests, or upgrade.
- Editing the wrong config file — global vs project-level paths differ by editor and OS.
- App not fully quit after save — MCP often loads only on a cold start (especially IDEs).
- Tools connect but return “no project” — not a connection failure; add github:owner/repo or an absolute path (see tool usage section).
- Node.js or npx not on PATH when the desktop app launches (common on macOS Dock launches).
- Invalid JSON in the config file (comments, trailing commas, or wrong wrapper key).
- ZEPHEX_API_KEY missing, still set to the placeholder, or pasted in the wrong field (stdio uses env, not Bearer headers).
- You edited Claude Code’s config but opened Claude Desktop (different files).
- App was not fully quit after saving the config — MCP only reloads on a cold start.
- npx works in Terminal but not inside the app — use absolute paths to node/npx in the command block if needed.
- First npx -y zephex run can take 30–60s — increase startup_timeout_sec where the editor supports it.
- Still have an HTTP url block while testing stdio — remove the duplicate zephex server.
- stdio extension still enabled alongside streamable_http.
- Extension disabled in session or goose configure toggle off.
- Bearer only in URL session flag without config.yaml headers.
If something goes wrong
Extension blocked
Use official config paths; check goose security messages.
No tools
streamable_http + url in config.yaml.
Auth missing
Authorization Bearer under headers.
Duplicate servers
Disable stdio zephex extension.
Timeout
Raise extension timeout (e.g. 300s).