Install, connect and authorize

#1. Enable External Connections

1. Open RooQi on your Mac and go to Settings › External Connections.
2. Click Enable Connection.
3. If macOS asks, allow RooQi’s background connection service in System Settings › Login Items & Extensions, then click Refresh Status.

Close Connection stops new requests. Operations already accepted may still finish — closing is not the same as undoing them; RooQi lists them under the connection status.

#2. Find the bridge

The command-line bridge ships inside the app bundle:

/Applications/RooQi.app/Contents/Helpers/RooQiBridge.app/Contents/MacOS/rooqi

Optionally add a shell alias:

alias rooqi="/Applications/RooQi.app/Contents/Helpers/RooQiBridge.app/Contents/MacOS/rooqi"
rooqi status

rooqi status prints one JSON line and exits with 0 when RooQi is ready.

#3. Configure an MCP client

Run the bridge with the mcp argument as a stdio server. A typical configuration:

{
  "mcpServers": {
    "rooqi": {
      "command": "/Applications/RooQi.app/Contents/Helpers/RooQiBridge.app/Contents/MacOS/rooqi",
      "args": ["mcp"]
    }
  }
}

Where this goes depends on your client. The server identifies itself as RooQi version 0.1.0 and exposes tools only (no resources or prompts).

#4. Approve access

Access is granted per connection, in RooQi:

1. The client calls a rooqi_request_*_access tool. The first call returns approvalRequired and RooQi shows a native window.
2. In that window, choose one project and approve.
3. The client calls the same tool again; it now returns ready.

Every grant is valid for 15 minutes and only for this connection. When it expires or the connection closes, requests that haven’t started writing are refused; saved results stay.

#Troubleshooting