Projects: per-repo MCP configs
Most MCP servers live in global config files — they're available in every project you open. But some servers are project-specific: a database MCP pointed at a particular connection string, a filesystem server scoped to a specific repo, or a custom tool only relevant to one codebase. The Projects tab is where you manage those.
What a project is
In MCPBolt's terms, a project is any folder that contains a project-scoped MCP config file. These files live inside the project's directory rather than in ~:
| Tool | Project config file |
|---|---|
| Claude Code | .mcp.json (project root) |
| Cursor | .cursor/mcp.json |
| VS Code | .vscode/mcp.json |
| Codex CLI | .codex/config.toml |
| Zed | .zed/settings.json |
| Gemini CLI | .gemini/settings.json |
| Roo Code | .roo/mcp.json |
When a tool opens a project, it merges both the global config and the project config. Project-scoped entries take precedence when there's a naming conflict.
Auto-discovery
MCPBoltBar automatically scans common development directories on your Mac for projects that contain Claude Code (.mcp.json) or Codex CLI (.codex/config.toml) project configs. Discovered projects appear in the Projects tab immediately — no setup required.
Scanned paths include:
~/Developer~/Projects~/Code~/repos~/src
If your projects live somewhere else, add the folder manually (see below).
Adding a folder manually
Click Add folder in the Projects tab. A standard macOS folder picker opens. Select the root of the repo (or any folder). MCPBolt immediately checks it for project-scoped config files and lists any it finds.
You can add as many folders as you like. The list persists across restarts.
Viewing and editing project-scoped servers
Clicking a project in the list expands it to show the servers defined in each project-scoped config file. The same toggle, edit, and remove actions available in the By App tab work here too — but writes go to the project file, not the global one.
To add a new server to a project, use the + Add server button inside the project view. You can paste a config snippet or pick a server you've already registered globally and MCPBolt will copy the entry into the project file.
Global vs. project-scoped: which wins?
Each tool handles the merge differently, but the general rule is:
- Both global and project servers are active when you open the project.
- If a server with the same name appears in both, the project-scoped entry wins.
- Disabling a server in the project scope does not affect the global config.
.mcp.json, .vscode/mcp.json, etc.) are regular files in your repository. If they contain secrets (tokens, API keys) in env values, do not commit them. Add them to .gitignore or use environment variable references instead of hardcoded values.