| 1 | # MCP servers |
| 2 | |
| 3 | ### Merge order |
| 4 | |
| 5 | `config.LoadForRoot` merges: |
| 6 | |
| 7 | 1. User/project TOML `[[plugins]]` (higher name wins vs later sources when already defined) |
| 8 | 2. Project `.mcp.json` servers not already in TOML |
| 9 | 3. Enabled **plugin packages** MCP (skipped if name already defined) |
| 10 | |
| 11 | Transports: `stdio` (default), `http` / streamable-http, `sse`. |
| 12 | |
| 13 | Enabled servers register cached tools and start on the first real tool call. |
| 14 | Persisted activation overrides take precedence over `auto_start`; without an |
| 15 | override, false means disabled and nil/true means enabled. `tier` is retained |
| 16 | for configuration compatibility and diagnostics; it does not control runtime |
| 17 | process start timing. Diagnose enablement and connection state separately. |
| 18 | |
| 19 | Env/header values may contain secrets — diagnostics list **keys only**. |
| 20 | |
| 21 | ### Checks |
| 22 | |
| 23 | | Mode | Behavior | |
| 24 | | --- | --- | |
| 25 | | Static doctor | Config validity, command path / URL shape, start intent — **no** subprocess | |
| 26 | | CLI `--live` | Isolated Host via `boot.PluginSpecsForRoot` + `plugin.Start`; auto-start only; concurrency 4; always Close | |
| 27 | | Desktop runtime | Read active tab Host only | |
| 28 | |
| 29 | ### Symptom → cause → fix |
| 30 | |
| 31 | | Symptom | Cause | Fix | |
| 32 | | --- | --- | --- | |
| 33 | | Not connected | Disabled, not yet called, or failed start | Check activation override and runtime state; fix command/URL if startup failed (`mcp.command_not_found`, `mcp.start_failed`) | |
| 34 | | No tools | Connected but empty tools/list | Server config or permissions (`mcp.no_tools`) | |
| 35 | | Wrong source | Shadowed by TOML vs `.mcp.json` vs package | Inspect report Source / package owner | |
| 36 | | Invalid transport | Bad `type` | Use stdio/http/sse (`mcp.invalid_transport`) | |
| 37 |