Home / Docs / MCP Server

MCP Server

Overview #

The thurbox-mcp binary exposes Thurbox configuration over the Model Context Protocol . It shares the same SQLite database as the TUI — changes appear immediately via PRAGMA data_version polling.

Transports #

stdio (default)

bash 
$ thurbox-mcp

Streamable HTTP

bash 
$ thurbox-mcp --transport streamable-http              # HTTP on 127.0.0.1:8080
$ thurbox-mcp --transport streamable-http --port 9090  # Custom port

Available Tools #

Role management

Tool Description
list_roles List all global roles
set_roles Atomically replace all global roles

Atomic replacement: set_roles deletes all existing roles and replaces them in a single transaction. To add a role, include all existing roles plus the new one.

MCP server configuration

Tool Description
list_mcp_servers List all global MCP servers
set_mcp_servers Set global MCP servers

Session management

Tool Description
list_sessions List sessions, optionally filtered by project
get_session Get a session by UUID
delete_session Soft-delete a session (TUI cleans up tmux/worktree)
restart_session Queue a session restart (TUI processes the command)
restore_session Restore a soft-deleted session

Orchestrator mode

The Admin session can spawn, drive, and read back other sessions to act as a multi-agent coordinator. Typical loop: create_session → poll get_session until idle → send_prompt → poll again → capture_session_output → react.

Tool Description
create_session Spawn a new local-tmux session. Supports role, optional git worktree on a fresh branch, per-session MCP servers and skills. Returns a UUID immediately; the TUI processes the queued spawn on its next tick.
send_prompt Send text to a session's terminal immediately (tmux send-keys ), followed by Enter after a short delay.
capture_session_output Return the rendered contents of a session's pane (tmux capture-pane ). Defaults to 200 lines of scrollback, capped at 10 000.

Scheduled commands

Tool Description
schedule_command Schedule text to be sent to a session at a future time
list_scheduled_commands List pending scheduled commands, optionally by session
get_scheduled_command Get a scheduled command by ID
cancel_scheduled_command Cancel a pending scheduled command
get_editor_command Get the editor command used by Ctrl+O
set_editor_command Set the editor command used by Ctrl+O

VM management

Tool Description
list_vms List active VMs, optionally filtered by project
get_vm Get a VM by UUID

Containerfile templates

Tool Description
list_containerfile_templates List template names + files in each
get_containerfile_template Read a template's Containerfile content and list support files
set_containerfile_template Create/update a template (Containerfile + optional support files)
delete_containerfile_template Delete a template (refuses to delete "default")

VM image management

Tool Description
list_vm_images List downloaded VM images with file sizes
download_vm_image Download a VM image from an HTTPS URL
delete_vm_image Delete a cached VM image

Admin Session #

The TUI includes a built-in Admin session that auto-configures thurbox-mcp as an MCP server. Claude Code discovers the config automatically, enabling conversational management inside the TUI.

How it works

  1. On startup, Thurbox creates an admin directory at ~/.local/share/thurbox/admin/
  2. A .mcp.json is written pointing to the thurbox-mcp binary
  3. An "Admin" project is pinned at index 0 with a yellow ⚙ prefix
  4. A single admin session spawns with all MCP tools pre-allowed

Restrictions

  • Cannot be edited ( Ctrl+E shows an error)
  • Cannot be deleted ( Ctrl+D shows an error)
  • Cannot have additional sessions created
  • The admin session cannot be closed ( Ctrl+C shows an error)

Example usage

In the Admin session, use natural language:

Admin session 
"Set up developer and reviewer roles for the my-app project.
Developer should have acceptEdits mode with git auto-approved.
Reviewer should be plan-only with read access."

CLI Integration #

Configure thurbox-mcp in your Claude Code .mcp.json :

.mcp.json 
{
  "mcpServers": {
    "thurbox": {
      "command": "thurbox-mcp",
      "args": []
    }
  }
}