DeepBlue Dynamics / Docs / Hyperia / MCP Tools

MCP Tools

Full reference for Hyperia's Model Context Protocol tool surface.

Overview

Hyperia exposes its terminal, window management, sticky notes, and telemetry surface as MCP tools via the Rust sidecar. Any MCP-capable client — the Ghost agent, Claude Code, or any external agent — can connect and control Hyperia directly.

The MCP server runs inside hyperia-sidecar as a persistent SSE endpoint on port 9800. Claude Code connects via --sse http://localhost:9800/mcp and auto-reconnects across restarts. The sidecar proxies tool calls directly to the running Hyperia window.

Connecting Claude Code

Hyperia exposes its full MCP tool surface as a persistent SSE endpoint. Claude Code connects once and stays connected — no manual /mcp needed after restarts.

Setup

With Hyperia running, add the MCP server in one command:

claude mcp add --transport http hyperia http://localhost:9800/mcp

Then verify inside Claude Code:

/mcp

You should see hyperia listed as connected with the full tool set visible.

Auto-reconnect

The SSE transport means Claude Code reconnects to Hyperia automatically whenever you start a new conversation or restart Claude Code — as long as Hyperia is open. This is a significant improvement over the previous stdio transport, which required running /mcp manually after every Claude Code restart.

Hyperia must be running for tools to work. If Hyperia isn't open when Claude Code starts, it will keep retrying and connect once Hyperia launches.

Switching from the old stdio config

If you previously added Hyperia as a stdio MCP server, remove it first:

claude mcp remove hyperia
claude mcp add --transport http hyperia http://localhost:9800/mcp

Custom port

If you've changed sidecarPort in your Hyperia config, update the URL to match:

claude mcp add hyperia --sse http://localhost:9810/mcp

Legacy stdio (older Claude Code versions)

The stdio transport is still supported for older clients:

macOS / Linux

claude mcp add hyperia \
  /Applications/Hyperia.app/Contents/Resources/sidecar/hyperia-sidecar \
  -- --mcp

Windows

claude mcp add hyperia ^
  "%LOCALAPPDATA%\Programs\Hyperia\resources\sidecar\hyperia-sidecar.exe" ^
  -- --mcp

Pane addressing

Most tools accept optional window, tab, and pane parameters to target a specific location in the Hyperia layout:

Parameter	Type	Description
window	integer	Window ID — the `id` field from `terminal_status` (not 0-based; first window is typically 1). Omit for the focused window.
tab	string	Tab name (e.g. `"Capybara"`). Omit for the active tab. Also accepts the pane UID prefix.
pane	string	Split pane label (`"a"`, `"b"`, `"c"`…). Omit for the first pane in the tab.

Call terminal_status first to discover the current layout before targeting specific panes.

Terminal tools

terminal_status

Returns the full window → tab → pane hierarchy. Lists all open tabs, their names, pane labels, and current working directory.

# No parameters required
# Returns: JSON tree of all windows, tabs, and panes

terminal_screen

Captures the current visible content of a pane as plain text.

terminal_screen(window=0, tab="main", pane="a")
# Returns: text content of the visible screen buffer

terminal_run

Types a command into a pane and waits for output. Presses Enter automatically. Returns the screen content after the wait period.

terminal_run(
  command="ls -la",
  wait_ms=2000,   # ms to wait before capturing (default 2000)
  submit=true     # whether to press Enter (default true)
)

Set submit=false to pre-fill a command for the human to review and submit manually.

terminal_keys

Types arbitrary keystrokes into a pane. Use \n for Enter, \t for Tab, \x03 for Ctrl+C, \x1b for Escape.

terminal_keys(keys=":wq\n")        # save and quit vim
terminal_keys(keys="\x03")         # interrupt running process
terminal_keys(keys="yes\n")        # confirm a prompt

terminal_split

Splits the active pane horizontally or vertically.

terminal_split(direction="vertical")    # side-by-side
terminal_split(direction="horizontal")  # stacked

terminal_new_tab

Opens a new terminal tab, optionally with a named shell profile.

terminal_new_tab(profile="Nemesis8")

terminal_new_window

Opens a new Hyperia window.

terminal_focus

Moves the human's visible focus to a specific pane. Use this only when you want to direct the user's attention — not as a prerequisite for typing, since terminal_run and terminal_keys address panes directly.

terminal_close

Closes the active tab or a specified tab.

terminal_rename

Sets the display name of a tab.

terminal_rename(tab="current-uid", name="Build Server")

terminal_where_pane

Returns the window/tab/pane coordinates of the currently focused pane. Useful for confirming you're targeting the right place.

tab_snapshot

Returns the full text content of all panes in the active tab in a single call.

shell_state

Returns the current shell state for a pane: running process, working directory, and whether it's idle or busy.

shell_confirm

Prompts the human for a yes/no confirmation before proceeding. Use before any destructive operation.

Web pane tools

open_web_pane

Opens a URL as a browser tab alongside the terminals.

open_web_pane(url="https://docs.example.com")

Sticky note tools

Sticky notes are floating windows that sit on top of the terminal surface. Agents can create and manage them as scratchpads, code snippets, or persistent reminders.

sticky_note_list

Returns all open sticky notes with their IDs and content.

sticky_note_create

Creates a new sticky note with text content.

sticky_note_create(content="Remember: deploy before 5pm")

sticky_note_create_code

Creates a sticky note with syntax-highlighted code. The content is rendered with a monospace font and code styling.

sticky_note_create_code(
  content="SELECT * FROM users WHERE active = 1",
  language="sql"
)

sticky_note_update

Replaces the content of an existing sticky note by ID.

sticky_note_close

Hides a sticky note without deleting it.

sticky_note_delete

Permanently removes a sticky note.

Agent tools

agent_status

Returns the current status of the Ghost agent — connected, working, idle, token counts for the session.

auto_describe

Automatically generates a short name for the active tab based on its current screen content. Called internally by Hyperia when a new tab's content is recognized.

Telemetry tools

telemetry_snapshot

Returns current token usage, tool call counts, and cost estimate for the active session.

telemetry_record

Records a custom telemetry event.

telemetry_reset

Clears the telemetry counters for the current session.

telemetry_toggle

Enables or disables telemetry collection.

Sidecar tools

sidecar_logs

Returns recent log output from the sidecar process. Useful for debugging MCP connection issues or agent errors.

hyperia_version

Returns the running Hyperia version, sidecar version, and platform.