# MCP server integration

Solo gives MCP clients a local stdio connection to the running app. Compatible clients launch Solo's bundled `mcp` helper, and Solo handles the private local transport behind the scenes.

## Setup

1. Open **Settings > Integrations > MCP**. The default Settings shortcut is `Cmd+,` on macOS and `Ctrl+,` on Windows and Linux; you can remap or disable it in **Settings > Hotkeys**.
2. Turn on **MCP server**.
3. Expand the setup section for your client and copy the generated command or JSON config.
4. For supported CLI clients, use **Run** to configure the client directly from Solo.

Solo shows setup snippets for:

- Enabled agent CLI targets that Solo has confirmed available or has not checked yet, including Claude Code, Codex CLI, Gemini CLI, Amp, OpenCode, Copilot CLI, Kimi CLI, Antigravity CLI, and Muse. Refresh CLI health to remove targets confirmed missing or broken.
- IDEs and apps: Cursor, Windsurf, Cline, and Claude Desktop.

For OpenCode, Antigravity CLI, and Muse, **Run** updates the client's own configuration file instead of running a CLI command: `~/.config/opencode/opencode.json` or `opencode.jsonc` for OpenCode, `~/.gemini/config/mcp_config.json` for Antigravity, and `$XDG_CONFIG_HOME/muse/settings.json` (by default `~/.config/muse/settings.json`) for Muse. Solo keeps your existing settings and comments, and refuses to write a file it can't parse safely or that changed while it was editing.

You can also connect agents from **Settings > Agents > Agent tools**. When MCP is on, a **Connect Solo to your agents** banner counts launchable agents that aren't connected yet, and each of those rows has a **Connect Solo** button that runs the same setup. See [Setting up agent tools](../agents/setting-up-tools.md).

The generated config uses stdio transport. There is no public MCP host or port to copy for normal clients. If Solo is using a non-default app data directory, the setup snippet passes that directory to the bundled helper so it connects to the same local app data and transport.

## Core tools

The MCP server exposes a focused core toolset for:

- Project selection, creation, rename, deletion, status, and stats.
- Workspace listing, creation, editing, deletion, reordering, and moving projects between workspaces.
- Local service and bound-port discovery.
- Process listing, status, selection, rename, start, stop, restart, close, and input.
- Bulk command start, stop, and restart.
- Rendered and raw output reads/searches, output clearing, and port discovery.
- Agent and terminal spawning, agent tool listing, session identification, and identity checks.
- Agent configuration management: create, edit, enable, disable, and delete agent tools, and refresh installation health.
- Project-scoped coordination locks.
- Local help and official documentation search, tool catalog summaries, a disposable smoke test, feedback drafting, and `AGENTS.md` or `CLAUDE.md` setup.

Solo's settings UI lists the exact tool names and descriptions from the generated MCP catalog. The same catalog is documented in the [MCP tools reference](/docs/mcp-tools/overview).

## Feature tool toggles

Additional MCP tools are turned on from each feature's own settings page. They augment the same MCP server; they do not start separate servers. **Settings > Integrations > MCP** lists each group with its tool count and whether it's on, plus an **Edit** button that opens the page where it's set.

| Tools | Switch |
| --- | --- |
| [Scratchpad tools](../mcp-tools/scratchpads.md): list, read, write, rename, tag, append, clear, delete, archive, transfer, save, and load project scratchpads | **Enabled in MCP** in **Settings > Features > Scratchpads** |
| [Todo tools](../mcp-tools/todos.md): create, list, read, update, tag, transfer, block/unblock, complete, lock/unlock, delete, and comment on project todos | **Enabled in MCP** in **Settings > Features > Todos** |
| [Prompt template tools](../mcp-tools/prompt-templates.md): list, read, create, update, delete, and export prompt templates | **Prompt template MCP tools** in **Settings > Features > Prompt templates** |
| [Timer tools](../mcp-tools/timers.md): one-shot, repeating, and idle-triggered timers, plus cancel, pause, resume, and list | **Timers** in **Settings > Agents > Timers** |
| [Key-value tools](../mcp-tools/key-value.md): project-scoped JSON key-value storage | **Key-value tools** in **Settings > Agents > Key-value** |

Scratchpads, todos, and timers inherit MCP server enablement until an explicit setting is saved. Key-value and prompt template tools default off until enabled.

Turning off the Todos, Scratchpads, or Prompt templates feature itself also removes its MCP tools, even when its MCP switch is on. See [Turned-off features](../mcp-tools/overview.md#turned-off-features).

The server also exposes built-in MCP prompts and readable scratchpad/todo resources; see [MCP prompts and resources](../mcp-tools/prompts-and-resources.md).

## Session resume across Solo restarts

The bundled `mcp` helper keeps agent sessions alive across Solo restarts and updates:

- If the connection to the Solo app drops, the helper reconnects automatically with backoff while the client remains connected and outage-buffered input stays within 4 MiB. Exceeding that limit ends the helper.
- Requests the client sends while Solo is unreachable are buffered up to that 4 MiB limit and replayed once the connection is back, so in-flight work within the limit resumes instead of failing.
- For Solo-launched agents, the helper persists a per-process session identity in Solo's app data. The same Solo process resumes that identity across helper restarts and Solo restarts. Solo also restores the selected project while the persisted session remains within its seven-day retention window. Other clients keep a stable session for the helper's lifetime, but not across helper restarts.

## Notes

- The local transport is owned by the running Solo app. Turning MCP off disables tool use, even though supporting local transport may still be available for the app.
- A **Restart** button appears when MCP is enabled.

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/integrations/mcp-server