MCP Manager
MCP (Model Context Protocol) lets an agent call external tools — read files, query a database, search the web, hit GitHub. The MCP Manager adds those servers to your coding agents in one place: you pick a server, choose which agents get it, and Mastery HQ writes each agent’s native config so the tools appear inside the real CLI.
Open it from the toolbar Tools (wrench) → MCP, or say “open the MCP Manager.”
Choose which agents get it
Section titled “Choose which agents get it”Six CLIs read MCP servers, each from its own file:
| Agent | Config file (project → global) |
|---|---|
| Claude Code | <project>/.mcp.json → ~/.claude.json |
| Cursor | <project>/.cursor/mcp.json → ~/.cursor/mcp.json |
| Gemini CLI | <project>/.gemini/settings.json → ~/.gemini/settings.json |
| Codex | <project>/.codex/config.toml → ~/.codex/config.toml |
| OpenCode | <project>/opencode.json → ~/.config/opencode/opencode.json |
| GitHub Copilot CLI | <project>/.copilot/mcp-config.json → ~/.copilot/mcp-config.json |
Tick the agents to apply to under Apply to (installed ones are pre-selected, shown with a green dot). Mastery HQ writes only the mcpServers (or Codex [mcp_servers]) section — the rest of each file is preserved.
Project vs. global scope
Section titled “Project vs. global scope”Leave Project directory blank to write each agent’s user-global config (the server is available everywhere). Enter a project path to scope the server to that repo instead — handy for a database or filesystem server that only makes sense inside one project. Project-scoped files can be committed, so avoid putting secrets in a shared repo (see below).
Add a server
Section titled “Add a server”From the registry. Pick a well-known server — Filesystem, Memory, Fetch (web), Git, GitHub, Brave Search, Slack, Postgres, Puppeteer — and click to expand it. Fill any required field (a filesystem path, a database URL) and any key it needs, then Add. Node servers run via npx (Mastery HQ manages the Node runtime — nothing to install); the ones marked uvx need uv / Python.
Custom. Use Add a custom server for anything else: a name, a command and args (e.g. npx -y @scope/server ./path), optional KEY=value env lines — or an HTTP/SSE URL for a remote server.
Keys stay out of the config
Section titled “Keys stay out of the config”When a server needs a secret (a GitHub token, a Brave key), Mastery HQ saves it to its own .env and passes it to the agent — it is not written into the config file. The agent forwards it to the server it launches. After adding a key, open a fresh agent window so it picks up the new .env.
See and remove servers
Section titled “See and remove servers”Configured lists the servers each selected agent currently has, read straight from its config. Click the trash icon on a chip to remove that server from every selected agent. Refresh re-reads the files.
Troubleshooting
Section titled “Troubleshooting”- A server doesn’t appear in the agent — restart the agent window (CLIs read their MCP config at startup).
- The
uvxservers fail — install uv, or use annpxserver instead. - Nothing under Configured — pick at least one agent, and set the project directory if you added the server project-scoped.
Frequently asked questions
Where does it write the config?
Each CLI's own file — Claude Code's .mcp.json, Cursor's .cursor/mcp.json, Gemini's ~/.gemini/settings.json, Codex's ~/.codex/config.toml. Mastery HQ only touches the mcpServers section and leaves the rest of your config untouched.
Do my API keys get written into the config?
No. Keys you enter for a server are saved to Mastery HQ's .env and passed to the agent, which passes them to the server — they aren't inlined into the config file. Open a fresh agent window after adding a key so it's picked up.