Nine tools for the session lifecycle.
MCP AIC gives your agent nine tools that follow the life of a helper session: find out what is possible, open a session, talk to it and follow it, then close it.
Every tool uses a strict schema, so an argument it does not define fails the call instead of being ignored. The tables group the tools by the task you want to perform.
See what is possible and what is running.
| Tool | Use it to | Parameters |
|---|---|---|
aic_capabilities | See which helper programs are available: each one's installed version, whether it can fork a session and which tool-access settings it honours, plus the modes and limits of this server. It reports capability observations; provider probes can be skipped, but mode-availability checks are separate and a result does not reserve later availability. | provider, fields, probe (default true), refresh (default false), all optional |
aic_session_list | List your sessions, newest first, filtered by provider, state or tag, to find one to continue or close. It only reads, and it can also add short summaries of orphaned sessions you could reclaim. | provider, state, tags, include_orphaned, limit (1 to 100, default 20), fields |
aic_session_get | See one session in detail: its state, turns, tokens, tool calls by name and status, and errors. Use it to check how a session is doing; it only reads. | session_id (required), fields |
Why: read first. The capabilities answer says whether native_tools: none is verified for the installed release, so the open does not fail on a surprise.
Open a session and close it.
| Tool | Use it to | Parameters |
|---|---|---|
aic_session_open | Start a new helper session in a folder, or resume an earlier one. Opening counts against your session limit and prepares a provider runtime, so read the built-in guide first. When resuming, explicitly choose the original execution mode; stored model, name, tags and thinking-storage choice remain in effect. | provider and workspace (required), mode (host or nested, default host), native_tools (none or all, default none), model, resume_session, resume_provider_session, fork, name, tags, store_thinking, idle_timeout_secs (60 to 1800, default 1800), allow_unverified |
aic_session_close | Stop sessions' provider programs, one, several or all of yours. This is destructive: you can also delete the stored events, or release ownership and leave the sessions running. Name sessions or ask for all, not both. | session_ids (up to 100), all, detach, purge |
Why: the workspace must be inside a folder the operator allowed. mode: nested works only with a Docker image you prepare yourself; MCP AIC does not supply one (see Safety and limits).
Send work, read progress, stop a turn.
| Tool | Use it to | Parameters |
|---|---|---|
aic_message_send | Send a message to a session; the agent may run tools and change files in its folder. It returns at once with a turn to follow, unless you ask it to wait briefly for a quick answer. | session_id and text (required, at most 32 KiB), steer, await_ms (the server caps it at 5000), timeout_ms (1 to 3,600,000, default 900,000) |
aic_turn_cancel | Request a stop for the running turn, then read its final state and retained partial record. Earlier project changes are not undone; a forced stop can end the provider session. | session_id (required), turn_id |
aic_session_read | Page through a session's stored events in order to follow what the agent did, optionally waiting for new ones. It only reads, and the output of tools is never returned. | session_id (required), since, before, limit (1 to 200, default 50), kinds, turn_id, await_ms |
aic_session_watch | Choose which notifications you receive for a session, such as tool use, messages or the end of a turn. Delivery is best effort, so keep reading the session's events as the dependable way to follow it. | session_id (required), on (tool, thinking, stats, end, message; default end), off |
Why: read until the turn reaches a final state; a short wait can reduce empty reads. A read uses a 16 KiB target page budget and up to 2 KiB of text per event; a large individual event can exceed that page budget, and the page can contain fewer events than limit. since and before cannot be combined, and before cannot wait.
A manual the agent can fetch.
aic_manual is a prompt, not a tool. Fetch it with prompts/get. It returns one message with the workflow, the limits and the warnings about stored data and shared access. It teaches the agent; it adds no enforcement.
What to expect when a call fails.
An application failure comes back as a tool error with one line, ERROR <code>: <message>, and a Suggestion: line to act on. An argument the schema does not accept is refused with the standard invalid-parameters error before the requested tool action runs.
| Limit | Value |
|---|---|
| Live sessions | 16 per server, a quarter of that (four) per client |
| Rates | 10 opens, 30 sends and 240 other calls per minute, shared by every client |
| Message | 32 KiB; 20 tags of up to 64 characters |
| Turn deadline | 15 minutes by default, 60 minutes at most |
| Idle detached session | Thirty-minute default cleanup window, requestable from one to thirty minutes; actual cleanup can occur later |
| Code | Meaning |
|---|---|
not_found | The session does not exist or is not yours; both read the same |
turn_in_progress | A turn is already running in the session |
cap_reached | The session limit is reached |
workspace_denied, invalid_argument | The folder or an argument is not acceptable |
provider_unavailable | The provider is not installed or not one the server opens |
policy_unsupported | The provider cannot honour the native_tools value for the installed provider release |
host_not_isolated | host mode is refused outside a container unless the operator accepted full host access |
nested_unavailable | nested needs Docker and the image the message names |
fork_unsupported, steer_unavailable, steer_failed | The provider cannot fork or steer; no provider offers steering |
persist_failed, data_dir_unavailable, data_dir_in_use | The stored record cannot be written or the data folder is taken |
See Troubleshooting for fixes.