MCP tools

Every tool ahpc mcp and ahpc serve can serve, with its arguments. This page is built from the tool table in the client, so it matches the installed version.

core tools are always served. The others are served when --mcp-tools names their group. See Tool server.

core

Tool	What it does	Arguments
list_sessions core, read only	The sessions on the connected host, newest first. Start here: every other session tool takes a session URI from this list. Give a limit to read one page and take nextCursor from the answer.	archivedboolean Include archived sessions. Off by default. limitinteger Read at most this many sessions. A positive whole number. Omit to read the whole catalogue. cursorstring The nextCursor of the previous page. Omit to start from the newest session.
show_session core, read only	What the host says about one session: its title, what it is doing, and the directories it works in.	sessionstring, required A session URI from list_sessions.
list_agents core, read only	The harnesses this host serves and the models each offers. The provider name from here is what new_session takes.
new_session core	Create a session on the host and return its URI. The agent is not asked anything until send_turn.	providerstring A provider from list_agents. The first one the host serves, if omitted. workingDirectorystring An absolute path on the host for the agent to work in. configobject Configuration values, as a flat object of strings.
dispose_session core	Dispose of a session. The transcript is the host's to keep or drop; the agent behind it stops.	sessionstring, required
session_history core, read only	The turns in a session, oldest first, as text rather than as a tree of parts.	sessionstring, required allboolean Load the whole conversation rather than the window the host opened with.
send_turn core	Say something to a session and block until the agent has finished answering, then return what it said. A turn that stops to ask a person something is not finished: this keeps waiting, and wait_for_attention is how to find out what it wants.	sessionstring, required textstring, required What to say. modelstring A model id from list_agents. The session's own, if omitted. timeoutSecondsnumber How long to wait. 900 by default. busyqueue | steer Where a turn is already running: queue this behind it, or steer it into that turn. A running turn is refused without this.
queue_turn core	Queue a message to be said once the running turn finishes. Returns at once, unlike send_turn.	sessionstring, required textstring, required
cancel_turn core	Interrupt whatever the agent is doing. What it had already said stays in the transcript.	sessionstring, required
wait_for_attention core, read only	Block until the session needs an answer - a tool call to approve, a question to fill in - or until it goes quiet, and say which. This is what makes a session drivable from here: without it a caller has no way to see what send_turn is waiting on.	sessionstring, required untilstring input, the default, waits for something that wants a person; idle waits for the session to go quiet. timeoutSecondsnumber 300 by default.
confirm_tool_call core	Answer a tool call the agent is blocked on. The id comes from wait_for_attention.	sessionstring, required toolCallIdstring, required approvedboolean, required True to allow it, false to refuse. optionIdstring One of the options the request offered, where it offered any.
answer_question core	Fill in a question the agent put to a person. The request id and the fields come from wait_for_attention.	sessionstring, required requestIdstring, required answersobject The answers, keyed by question id. rejectboolean Decline to answer instead.
list_automations core, read only	What the host runs on a schedule, whether each is on, and when it next fires.

resources

Tool	What it does	Arguments
list_directory resources, read only	What is in a directory the host serves. Takes a file:// URI on the host.	pathstring, required A file:// URI of a directory on the host.
read_file resources, read only	The contents of a file the host serves. Text comes back as text; anything the host sends as bytes comes back base64 with the encoding said.	pathstring, required A file:// URI on the host.
write_file resources	Write a file on the host, refusing if it changed since it was read. Pass force to write over whatever is there now. A host that has not granted write access to that directory refuses this, and only a person at the host can grant it.	pathstring, required A file:// URI on the host. contentstring, required The whole new contents. This replaces the file. createOnlyboolean Refuse if the file already exists. forceboolean Write even if the file changed since it was last read.
make_directory resources	Create a directory on the host.	pathstring, required
delete_path resources	Remove something on the host. A directory needs recursive.	pathstring, required recursiveboolean Needed to remove a directory that is not empty.
move_path resources	Move something on the host, which is also how it is renamed.	fromstring, required tostring, required failIfExistsboolean Refuse rather than write over something already at the destination.
copy_path resources	Copy something on the host.	fromstring, required tostring, required failIfExistsboolean Refuse rather than write over something already at the destination.

terminals

Tool	What it does	Arguments
list_terminals terminals, read only	The terminals the host is running, with the URI each other terminal tool takes.
new_terminal terminals	Start a terminal on the host and return its URI.	workingDirectorystring An absolute path on the host. namestring
send_to_terminal terminals	Send a line to a terminal. A newline is added unless newline is false, because a shell runs lines rather than strings.	terminalstring, required A terminal URI from list_terminals or new_terminal. textstring, required newlineboolean Whether to end it with a newline. True unless said otherwise.
read_terminal terminals, read only	What a terminal has written so far. With waitSeconds it keeps reading until the process exits or that long passes, which is how a command that was just sent is waited on.	terminalstring, required waitSecondsnumber Wait this long for the process to exit before answering. Zero, the default, answers with what is there now.
dispose_terminal terminals	Close a terminal on the host.	terminalstring, required

automations

Tool	What it does	Arguments
run_automation automations	Fire an automation now, without waiting for its schedule. Answers once the host has taken it, not once it has finished.	automationstring, required An automation URI from list_automations.
set_automation_enabled automations	Stop an automation firing, or start it again. The definition stays either way.	automationstring, required enabledboolean, required
remove_automation automations	Delete an automation from the host. Use set_automation_enabled to stop one without losing it.	automationstring, required

changes

Tool	What it does	Arguments
list_changesets changes, read only	The changesets a session offers - what the conversation changed, what one turn changed, what the working tree has. Each is a URI show_changes takes.	sessionstring, required
show_changes changes, read only	The files in a changeset and how much each changed. The contents are not here: a changeset of two hundred files is a list worth having and megabytes that are not. Read one with read_file.	sessionstring, required changesetstring A changeset URI from list_changesets. The session's own, if omitted.