MCP bridge
Agents talk to the window over the Model Context Protocol, through a Unix socket and a small sidecar. There is no network port, no account and no cloud relay.
Chain
agent client ──stdio JSON-RPC──► spark-mcp (sidecar)
│ Unix socket
▼
Spark window (attachMcp)
│
▼
runtime / registry / workspacesrc-tauri/src/bin/spark-mcp.rsis declared as an external binary and shipped inside the bundle.- The Rust server creates
run/mcp.sockin the app configuration directory, mode0600. attachMcpforwards each line to the window and returns the reply.- When Spark is closed, the bridge answers
spark_not_runningand serves the last cached tool list, so a client does not have to restart.
Tools
| Tool | Job |
|---|---|
spark_brief | Short summary of the active or targeted tab. |
spark_tabs | Tabs and their layout mode. |
spark_tiles | Compact catalogue of tile types, actions and availability; detail: "full" adds descriptions and schemas. |
spark_tab_open | Creates a tab in the background. |
spark_tab_close | Closes a tab; refused when an unsaved document objects. |
spark_tab_focus | Activates a tab. |
spark_tile_open | Opens a tile and returns its reference. |
spark_tile_read | Reads a tile's surface, data and available actions. |
spark_tile_call | Runs a declared action. |
spark_tile_close | Closes a tile. |
spark_tile_move | Places a tile next to another one, or as a tab in its group. |
spark_tile_resize | Gives a tile a width or height as a fraction of the tab. |
spark_undo | Undoes a layout operation. |
spark_redo | Redoes a layout operation. |
spark_events_since | Resumes the journal from a sequence number. |
The list is deliberately stable: a client caches it and refreshes it badly. What varies is theactions, discovered per tile with spark_tiles andspark_tile_read.
Contracts
- Bounded results. An action returning more than 16,000 characters is refused; it must return an identifier or a summary.
- Surfaces.
api.tiles.publishis a volatile 2,000-character summary, never persisted. - Guides. A tile type's guide is at most 1,200 characters and is delivered once per agent session, at the first catalogue or the first read.
- Services. An action declaring
requiresis hidden when that service is absent, and refused when called. - Mutations. An action flagged
mutatesis announced as such and executed; asking for confirmation belongs to the calling client. - Attribution. Every action called through
spark_tile_callis journaled withsource: "agent". - Focus. Tabs opened by an agent stay in the background and show a discreet dot in the bar until opened.
- Content. No MCP action reads or writes a terminal's content, and no action returns a document.
Connect a client
{
"mcpServers": {
"spark": {
"command": "/Applications/Spark.app/Contents/MacOS/spark-mcp"
}
}
}The absolute path is the one shown by the gear menu at the bottom of the rail, underConnect an agent…, with a copy button. Spark also detects a known agent command in a terminal and offers to write the client's configuration in one click; the running session sees the server on its next start.
Lifecycle
registry.subscribeToolsemitsnotifications/tools/list_changedwhen an extension is activated, disabled or imported.spark_tilesis recomputed on every call, so a new extension appears without restarting the client.- The sidecar caches the tool list for closed-window replies. A new core tool still needs a new session on the client side.