Terminay MCP
Terminay MCP lets an AI agent running inside one Terminay tab inspect and control the other terminal tabs in the same workspace. It can also manage automations and show interactive windows, within permissions you set. It is separate from the Agents sidebar and never installs agent hooks.
What It Does
The MCP server exposes terminal actions to tools such as Claude Code and Codex. An agent can list terminals, read and search recent output, run commands, type text, open or split a terminal, focus or rename a tab, close a tab, and wait for idle, command-complete, or attention events.
It also exposes automations: an agent can list them and their runs, create, edit, enable, disable, or delete one, start a run, and stop a run in progress.
And it exposes app windows: an agent can show its own HTML in a window inside the terminal it is running in, and use the tools and views of MCP servers you connect in Settings.
It drives workflows: an agent reads the checklist attached to its terminal, reports each step's progress, and can manage the server's workflow templates. And it can read and arrange the window it is talking from: list projects, folders, and tabs, move and split panes, and open or close workspace windows. It can also read and change the server's settings and shell profiles, and send notifications.
An agent in a project terminal reaches that project only: its sibling terminals, and renaming, re-icon, or recolouring its own project. Pixel and agents in Home terminals can drive the whole app. A terminal moved to another project keeps its MCP access, scoped to its new project.
Install For Agents
Open the Command Bar with Cmd/Ctrl+L, search for Install Terminay MCP, and open the installer. The modal shows supported agents, the config file Terminay will edit, and whether the terminay MCP server entry is already installed.
- Claude Code: Terminay adds or removes a
terminayentry undermcpServersin~/.claude.json. - Codex: Terminay adds or removes an
[mcp_servers.terminay]block in~/.codex/config.toml. - Cursor CLI: a
terminayentry undermcpServersin~/.cursor/mcp.json. - Gemini CLI: a
terminayentry undermcpServersin~/.gemini/settings.json. - Grok: an
[mcp_servers.terminay]block in~/.grok/config.toml, or$GROK_HOME/config.tomlwhen that is set. - OpenCode: a
terminaylocal server undermcpin its user configuration in~/.config/opencode/.
Install changes are local to your machine and add only the MCP server entry. Terminay does not install, modify, or depend on hooks. Restart the agent after installing if it does not pick up the new MCP server immediately.
If the existing Terminay entry has been changed outside Terminay, the installer marks it Changed — review config. It will not overwrite or remove that entry until you review the provider config yourself.
Independent From Agent Status
Installing MCP does not affect the Agents sidebar. Terminay detects Codex and Claude Code activity for the sidebar from their local journals and log files, not from hooks. You can install MCP for terminal control, use the sidebar without MCP, or use both independently.
Use From An Agent
Start the agent inside a Terminay terminal after the MCP server is installed. The agent can then call tools such as list_terminals, read_terminal, run_command, open_terminal, split_terminal, and wait_for_idle.
A useful pattern is to keep one tab for the agent and one or more tabs for app servers, tests, logs, or long-running tasks. The agent can start work in a sibling tab, watch output, and wait until the command is idle before continuing.
Permissions
Settings > AI > Terminay MCP lists eleven permission groups and one policy for window messages. Set each to Ask Permission, Always Allow, or Never Allow:
| Group | Covers | Default |
|---|---|---|
| Read Terminals | Listing, reading, searching, and waiting on terminals. | Always Allow |
| Full Terminal Management | Opening, splitting, closing, renaming, focusing, typing, and running commands. | Always Allow |
| Read Automations | Listing automations and their runs. | Always Allow |
| Full Automation Management | Creating, editing, enabling, deleting, running, and stopping automations. | Ask Permission |
| Projects & Windows | Listing, creating, renaming, moving, and closing projects, and opening, renaming, and closing workspace windows. A project terminal may only rename, re-icon, and recolour its own project. | Always Allow |
| Read Settings | Reading the server's settings and shell profiles. Credentials, Remote Access, recording, and the MCP settings are never readable. | Always Allow |
| Change Settings | Changing the server's settings and shell profiles, with the same exclusions. | Ask Permission |
| Workflow Templates | Saving, editing, and deleting the workflow templates in Settings → Workflows. Reading templates is part of Read Terminals. | Ask Permission |
| App Windows | Showing, closing, and listing app windows, and opening a view for a connected server's tool. | Always Allow |
| Notifications | Sending, updating, and dismissing notifications for the agent's terminal. | Always Allow |
| Connected Server Tools | Every tool of an MCP server you connected in Settings. | Always Allow |
| Window Messages | An app window typing a message into its terminal. | Always Allow |
The settings belong to the server and apply to every project and terminal on it. They are the same from the desktop app, a browser, and a phone.
When a group is set to Ask Permission, the request waits and a prompt appears inside the agent's terminal pane, above its output. It names the agent and terminal and shows exactly what would happen, including the full command and schedule of an automation. Choose Allow One Time, Allow This Session, or Decline. If the terminal is in the background, its tab is marked as needing attention.
- You can answer from any device connected to that server. The first answer wins and the prompt disappears everywhere.
- Allow This Session covers that permission group for that one terminal until the terminal exits or the server restarts. It never carries over to another terminal.
- A prompt does not time out. It ends when you answer, when the agent cancels, or when the terminal closes.
- An approval covers the exact request shown. If the automation changed while the prompt was open, the request fails instead of overwriting your edit.
- Never Allow refuses at once, without a prompt, and tells the agent which setting to ask you about.
Security Model
Terminay uses a local-only control socket and a per-terminal capability token. The token is injected into terminals that Terminay spawns and anchors the request to that terminal's workspace. When an MCP client does not forward the token environment, Terminay can still resolve scope from the client process ancestry.
Terminay's own tools are limited to terminals, automations, and the calling terminal's app windows. They do not expose files, settings, recordings, remote access, or cross-window control. Terminals launched by an automation are the one exception to project scope: a script running there can reach the terminals of every project on its own server, so a scheduled job can start agents where they are needed. It still cannot reach another server. You can disable the local control server with Settings > AI > Enable Terminay MCP server.
Troubleshooting
- Agent cannot see terminals: start the agent inside a Terminay terminal, then restart it after installing the MCP server.
- No tools appear: reopen the installer and confirm the agent shows as installed.
- Wrong workspace: the visible terminal set is based on the terminal where the agent is running, not the currently focused Terminay tab.
- permission_denied: the operation's group is set to Never Allow. Change it in Settings > AI > Terminay MCP.
- Agent seems stuck on a tool call: it may be waiting for approval. Open the terminal the agent is running in and answer the prompt.
- Control disabled: open Settings and make sure Enable Terminay MCP server is enabled.
- Changed — review config: Terminay found an MCP entry that differs from the one it installed. Review the entry in the listed provider config file before changing it.