MCP tools

Spaces ships an MCP server so a coding agent can inspect and drive your projects, workspaces, and terminals as tools.

What it is

spaces mcp starts a Model Context Protocol server: an MCP client (a coding agent such as Claude Code, Codex, opencode, GitHub Copilot CLI, pi, or Amp) launches it as a subprocess and calls its tools directly, over standard input and output. Every call runs against the same Spaces service on this machine that the app and the CLI use, so an agent sees the same projects, workspaces, and terminals you do.

Setup

Settings → MCP → "MCP Client Setup" shows a ready-to-paste snippet per agent, including the resolved path to the spaces binary. The examples below use spaces on your PATH; substitute the absolute path from Settings if the CLI is not on it.

Claude Code

claude mcp add spaces -s user -- spaces mcp

Codex CLI

Installing Codex's hooks from Settings → Coding Agents adds this entry for you. To add it by hand, put an mcp_servers table in ~/.codex/config.toml. Codex passes a server only the environment variables listed in env_vars, and these two are how the server knows which terminal is calling.

[mcp_servers.spaces]
command = "spaces"
args = ["mcp"]
env_vars = ["SPACES_TERMINAL_TRACKING_ID", "SPACES_AUTOMATION_RUN_ID"]

opencode

Add a spaces entry to the mcp block in ~/.config/opencode/opencode.json.

{
  "mcp": {
    "spaces": {
      "type": "local",
      "command": ["spaces", "mcp"],
      "enabled": true
    }
  }
}

GitHub Copilot CLI

Run once in your terminal.

copilot mcp add spaces -- spaces mcp

Run once in your terminal.

pi mcp add spaces -- spaces mcp

Amp

Run once in your terminal.

amp mcp add spaces -- spaces mcp

Tools

The server exposes project, workspace, terminal, paired-device, and coding-agent tools. There is no stop tool for a workspace and no signal tool: an agent reports its own lifecycle only through the CLI hook spaces agent signal, which is intentionally left off the tool surface, so an agent can read another agent's status but never forge it.

Tool	What it does
`spaces_project_list`	List projects on this or a paired device.
`spaces_project_create`	Add a project from a folder (an absolute or ~ path) or a Git URL, with an optional device. Imports any spaces.yaml and returns the project and its default workspace, not started.
`spaces_workspace_list`	List workspaces, optionally filtered by project.
`spaces_workspace_create`	Create a workspace: project and branch required, plus a base branch or existingBranch to reuse a branch, and an optional device. Not started automatically.
`spaces_workspace_start`	Ensure a workspace is running.
`spaces_workspace_restart`	Relaunch a workspace's configured processes.
`spaces_terminal_list`	List available terminal sessions.
`spaces_terminal_tail`	Read a session's recent output, defaulting to the last 20 lines.
`spaces_terminal_send`	Send text or raw bytes to a terminal session, optionally submitting it as a paste plus a separate Enter keystroke.
`spaces_agent_list`	List coding-agent sessions, optionally filtered by workspace.
`spaces_agent_status`	Read one agent session's status, brief summary, and context.
`spaces_agent_spawn`	Start a supported agent (claude, codex, opencode, copilot, pi, or amp) in a workspace and wait until it is ready for input.
`spaces_agent_kill`	End a coding-agent session and its terminal.
`spaces_agent_subscribe`	Watch an agent from this terminal; get told when it goes blocked, done, or exits.
`spaces_agent_unsubscribe`	Stop watching an agent.
`spaces_agent_brief_write`	Replace an agent's brief, the short status page Spaces shows beside its terminal. An empty string clears it.
`spaces_agent_brief_read`	Read an agent's brief in full, with when it was last updated.
`spaces_agent_brief_clear`	Remove an agent's brief.
`spaces_device_list`	List the paired devices this machine can reach.

The brief tools act on the calling terminal's own agent unless given a session, so an agent connected to this server keeps its own brief with no extra setup. See agent briefs for what a brief is and where it shows, and briefs for the matching CLI commands. The rest of the agent tools are covered in full at Orchestrate agents.