# Agent and terminal MCP tools

Agent and terminal tools create new Solo-managed processes and help MCP sessions identify the caller.

## 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.

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.

## 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