Handing the console to a model

It would have been trivial to expose one tool called run_command and be done. The MCP server instead exposes thirty-three named operations whose parameters are typed, whose device references are resolved before anything executes, and whose failures come back as structured blockers with suggested next actions. The design assumption is that an agent works better when the surface tells it what it is allowed to want.

The server is a single Python file built on mcp.server.fastmcp. It imports the same ConnectorControlClient the CLI uses, and holds two instances of it: one bound to the resolved default socket, one bound explicitly to the desktop app's socket. Everything interesting follows from that pair.

"Use Connector semantic tools first. Select device {device_id}, inspect the device state, connect, then capture a screenshot to verify the UI state."

This is the most consequential twenty lines in the file. The daemon is the default because it is always there. But a stream launched by connectord is invisible to the desktop app's menubar and local session controls — so anything visual has to prefer the app when the app is open. The routing is explicit, and it is commented in the source with exactly that reasoning.

Resources

Eleven read-only connector:// URIs, all of which serialise through the same routing. Two are static files; the rest are live RPC reads.

Of the thirty-three tools, this one is the argument for the whole design. It does not return a device record. It returns a judgement, assembled from the four independent readiness signals, together with the specific next tool call that would move the situation forward.

{
  "query": "zflow",
  "resolved_device": {
    "id": "n5XYmDgJcq11CNTRL",
    "name": "zflow",
    "ip": "100.64.0.13",
    "online": true,
    "host_reachable": false,
    "ssh_ready": true,
    "ssh_mode": "tailscale",
    "trusted": false
  },
  "summary": "Online and SSH ready; remote desktop still needs host runtime/trust.",
  "can_ssh": true,
  "ssh_target": "[email protected]",
  "can_start_remote_desktop": false,
  "blockers": [
    "Connector host runtime is not reachable."
  ],
  "next_actions": [
    "Run connector_start_host_runtime to start Connector/Sunshine over SSH, then re-test.",
    "Use connector_ssh_exec for remote repair commands."
  ],
  "resolution": {
    "device_id": "n5XYmDgJcq11CNTRL",
    "match": { "score": 1035, "reason": "exact match on zflow" }
  }
}

The score of 1035 is not decorative: 1000 for the exact name match, +25 for sshReady, +10 for online, no bonus for hostReachable because it is false. An agent reading this can see both what matched and how confident the match was.

The recommended deployment, straight from CONNECTOR_MCP_CONTEXT.md, is a trusted home control node: a machine that stays on the tailnet, runs the daemon, and publishes the MCP surface on loopback for a local agent runtime to consume. The three deploy files encode exactly that ordering.

$ systemctl --user enable --now connectord.service connector-mcp-http.service

$ systemctl --user list-dependencies connector-mcp-http.service
connector-mcp-http.service
● └─connectord.service

$ scripts/wait-for-port.py 127.0.0.1 8876 30
$ echo $?
0

# the drop-in that makes a consuming service wait for the bridge
$ cat deploy/ian-brain-connector-order.conf
[Unit]
Wants=connector-mcp-http.service
After=connector-mcp-http.service

[Service]
ExecStartPre=%h/Desktop/realconnector/scripts/wait-for-port.py 127.0.0.1 8876 30