Model Context Protocol

Overview

spaces mcp runs a Model Context Protocol server over stdio: the MCP client launches it as a subprocess and exchanges JSON-RPC over standard input and output. Each tool call is forwarded to the running spacesd daemon, so the server uses the same orchestration path as the GUI and CLI.

The app shows ready-to-paste configuration under Settings → MCP, 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 your PATH. Any MCP client that launches a stdio server works; the same command and args apply.

Claude Code

Register the server once at user scope so the tools are available in every directory. Claude Code then spawns spaces mcp when it needs the tools.

claude mcp add spaces -s user -- spaces mcp

Codex CLI

Add an mcp_servers table to ~/.codex/config.toml.

[mcp_servers.spaces]
command = "spaces"
args = ["mcp"]

opencode

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

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

Tools

The server exposes project, workspace, and terminal tools.

• spaces_project_listList Spaces projects.
• spaces_workspace_listList workspaces, optionally filtered by project.
• spaces_workspace_createCreate a workspace on this device. Requires a project and branch; accepts a title, base branch, and existing-branch reuse.
• spaces_workspace_startEnsure a workspace is running.
• spaces_workspace_restartForce a full stop and relaunch for a workspace.
• spaces_terminal_listList available Spaces terminal sessions.
• spaces_terminal_tailRead recent rendered output, omitting inline suggestions only in identified coding-agent sessions. Defaults to the last 20 lines.
• spaces_terminal_sendSend UTF-8 text or explicit raw byte values to a terminal session, optionally submitting text as a paste followed by a separate Enter keystroke that every supported agent TUI (Claude Code, Codex, OpenCode) reads as a distinct submit rather than an unsubmitted paste.

Agent lifecycle signals are intentionally not MCP tools. Coding agents report state through the CLI hook spaces agent signal so those hooks stay out of the agent-callable tool surface.