# Agent and terminal MCP tools

Agent and terminal tools create new Solo-managed processes, help MCP sessions identify the caller, and manage the agent tools that agents launch from.

## Tools

- `list_agent_tools` — List enabled [configured agent runtimes](../agents/setting-up-tools.md). Use each returned `id` as `agent_tool_id` for `spawn_agent` or `spawn_process`.
- `spawn_agent` — Preferred tool for creating a new [Solo agent](../agents/what-are-agents.md). Requires `agent_tool_id` from `list_agent_tools`; returns `process_id`, `name`, and optional `agent_instructions`.
- `spawn_process` — Generic create-and-start tool. Use `kind: "terminal"` for an interactive shell or `kind: "agent"` with an `agent_tool_id`; prefer `spawn_agent` for agent-only calls.
- `identify_session` — Identify this MCP session to Solo. With no arguments, auto-detect and report the current identity.
- `whoami` — Show how Solo identified this caller's process, actor, and effective project scope.

## Spawning agents

Both spawn tools accept these agent options:

- `agent_tool_installation_id` — The environment-specific installation of the agent tool to launch. Preferred over `agent_tool_id` alone when project-scoped agent discovery returns installations.
- `name` — Custom name for the spawned process; omitted names are auto-generated.
- `extra_args` — Per-launch arguments appended to the resolved agent command without changing the saved agent tool defaults.
- `include_agent_instructions` — Include bootstrap instructions in the response. Defaults to true.

If you pass both `agent_tool_id` and `agent_tool_installation_id`, they must refer to the same agent tool; otherwise the call is rejected.

By default, spawning an agent includes `agent_instructions`: a Solo orchestration preamble with the new process ID, project, and MCP tool hints. Set `include_agent_instructions: false` to omit them. When included, prepend them to the agent's first prompt, then send that prompt with `send_input(process_id=..., input=...)`.

Spawning never changes the caller's own identity. Pass `project_id` to spawn into a different project without changing the session's default scope.

## Managing agent tools

These tools manage the global [agent tool configurations](../agents/setting-up-tools.md) shown in **Settings > Agents > Agent tools**:

- `list_agent_tool_configs` — List full agent tool configurations. Disabled tools are included unless you pass `includeDisabled: false`. Unlike `list_agent_tools`, which returns only enabled runtimes for spawning, this returns every editable field.
- `get_agent_tool` — Read one configuration by `id`.
- `create_agent_tool` — Add an agent tool from a required `name` and `command`. Optional fields are `defaultArgs` (default empty), `icon` (default `terminal`), `toolTypeMode` (`auto`, the default, detects the agent type; `manual` requires `manualToolType`), `headlessCmd`, `promptMode` (`stdin`, the default, or `arg`), and `enabled` (default `true`).
- `update_agent_tool` — Patch fields with `{"id": 42, "patch": {...}}`. Omitted fields are preserved, and `headlessCmd: null` clears the headless command. Changing the command or type clears the saved resume IDs of agents that use it.
- `delete_agent_tool` — Delete a configuration by `id`. It's idempotent, detaches processes that used it, and leaves those processes running.
- `set_agent_tool_enabled` — Enable or disable an agent tool by `id`. This affects future launches only; running agents keep going.
- `list_agent_tool_installations` — List detected installations of each agent tool with their cached health.
- `refresh_agent_tool_installation_health` — Re-check installations and refresh their health, like **Refresh health** in Settings.

The same operations are available through the [HTTP API](../integrations/http-api.md#agent-tools) and the [`solo agents` CLI commands](../cli/projects-and-processes.md#agent-tools).

## Session identity

Solo-managed agents are normally identified automatically. Use `whoami` to check the current identity, and call `identify_session` only if `whoami` cannot identify the session. `identify_session` has three modes:

- **Auto-detect** — Call with no arguments to detect and report the current identity. An optional `pid` (the caller's host OS PID) helps detection when nothing else matches.
- **Self-assertion** — Pass `solo_process_id` with this client's own value from the `SOLO_PROCESS_ID` environment variable, only when auto-identification failed. This is a Solo-managed process ID, not a host OS PID.
- **External registration** — Pass `external` with a display `name` (plus optional `agent_id` and `metadata`) when the caller runs outside Solo but needs an actor identity for coordination features like [locks](./coordination.md), [todos](./todos.md), and [scratchpads](./scratchpads.md).

Never use `identify_session` to target another process. Use `project_id` parameters for project scope and `delivery_process_id` for [timer delivery](./timers.md).

## Notes

Use `spawn_agent` or `spawn_process` for new work. Use `start_process` or `restart_process` from [Process tools](/docs/mcp-tools/process) for existing Solo process entries, and `close_process` to remove stored terminals and agents.

Identification lets Solo associate timers, locks, todos, scratchpad activity, and process cleanup with the correct Solo process. Use `whoami` to confirm what Solo already knows about the session.

---

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