Agent tools

mocante offers an agent a set of MCP tools that act on the session the agent runs in. With them, the agent can find out where it is and what you are looking at, rename or close its session when the work is done, show you a file, check its dev servers and drive the session’s built-in browser. “We are finished, clean up after yourself” becomes one instruction to the agent instead of a trip back to the dashboard.

Install the tools

1. Open the command palette with ⌘⇧P (Ctrl+Shift+P on Linux) and run Install agent MCP server….
2. Pick the agent and the host. The list shows each agent with an MCP client on each connected host: Claude Code, Codex and opencode. pi has no MCP client, so it is not listed.
3. Restart the agent. None of them load new MCP servers while they run.
4. Check the install: in Claude Code or Codex, /mcp lists mocante.

Install once per agent on each host where you run it. On a remote host nothing else is needed: the tools reach your device through the connection mocante already has.

For Claude Code, the tools come in the same mocante plugin as its hooks, so Install agent MCP server… and Install agent hooks… do the same thing for Claude Code. In Claude Code the tools are named mcp__plugin_mocante_mocante__<tool>. If you wrote permission rules for the older mcp__mocante__<tool> names, update them.

If the agent is not found on the host, the install fails and shows the command to run by hand.

Codex installed with an older mocante

If the tools in Codex report “This process runs outside a multiplexer pane” while Codex runs in a mocante terminal, run Install agent MCP server… again for Codex and restart it.

What the tools do

No tool takes a session name. Each call acts on the session the calling agent runs in, so an agent cannot touch another session.

Tool	What it lets the agent do
session_info	Read its session: name, host, project, workspace, branch, worktree path, tabs, and what is on your screen.
session_rename	Rename the session, for example after the task it turned out to be.
session_close	Close the session, remove its worktree and delete its branch.
session_share	Show you a file: a screenshot, a recording, a report. See files.
server_list	List the session’s dev servers: state, ports and address of each.
server_logs	Read the recent output of one dev server.
server_restart	Restart a dev server, or start a stopped one.
browser_*	Open, read, click, type in, screenshot and close the session’s built-in browser.

What is on your screen

session_info tells the agent which panes of its session you have open, the file in the code view, the page in the browser pane, and which pane has the keyboard. So you can say “look at the file I have open” or “what is wrong with this page” without a path or a URL.

Closing a session from inside it

session_close ends the agent that calls it, together with every tab of the session. The agent gives you its summary first, then calls the tool.

Before it removes anything, the tool checks for work that would be lost: uncommitted changes, or commits that no remote branch has. If it finds any, it refuses and tells the agent how many. The agent can then commit and push, or close anyway if you tell it to. The agent can also close the session and keep the worktree for later. A session in the main checkout has no worktree, so closing it only ends the session.

Approve a tool call

The first call in a session that changes the session, drives its browser or runs JavaScript in a page waits for your approval. mocante asks once per session for each of these:

mocante asks to	Tools
control this session	session_rename, session_close, server_restart
drive the built-in browser	every browser_* tool except browser_evaluate
run JavaScript in the page	browser_evaluate

The request shows as a bar at the top of the session, for example “Claude Code asks to control this session”, with the details of the call (the new name, the URL, the script). Click Approve or Deny. When the session is not on screen, a desktop notification tells you. The command palette also has Approve permission and Deny permission.

• session_info, session_share, server_list and server_logs never ask. They only read, or only move a file into your own window.
• An approval holds until the session is removed. After mocante restarts, it asks again.
• A denied call fails, and the agent sees that you denied it.
• A request that nobody answers in 100 seconds fails, and tells the agent to ask you to approve it in mocante and call again.
• With no mocante window open, there is nobody to ask, and the call fails with that reason.

Things to ask the agent

• “Rename this session to something that describes the bug.”
• “We are done. Commit, push, and close this session.”
• “Look at the file I have open and explain the function under the cursor.”
• “Open the app in the browser, log in, and tell me what the console shows.”
• “Take a screenshot of the settings page and share it with me.”
• “The dev server looks stuck. Check its logs and restart it.”

Remove the tools

• Claude Code: the tools are part of the mocante plugin, so Uninstall agent hooks… in the command palette removes them together with the hooks.
• Codex: run codex mcp remove mocante.
• opencode: delete mcp.mocante from ~/.config/opencode/opencode.json.

Then restart the agent.