# Install, connect and authorize

> Enable External Connections in RooQi for Mac, configure an MCP client, and approve access.

- Source: https://rooqi.cn/docs/developers/connect/
- Platforms: Mac only (macOS 14 or later)
- Version: RooQi for Mac 1.0 test build · bridge protocol v1
- Status: Preview — not yet publicly released
- Last verified: 2026-10-26 against the RooQi Mac source and its English UI strings
- Known limitations: The bridge lives inside RooQi.app; its path changes if you move the app. After updating RooQi, close and re-enable the connection. Client configuration examples are not yet tested against every MCP client.

## 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:

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

Optionally add a shell alias:

```sh
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:

```json
{
  "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`.

| Permission | Requested by | What the approval says |
|---|---|---|
| Read | `rooqi_request_read_access` | Read the saved text of existing documents in the chosen project. Cannot change content. Excludes handwriting, images and PDF source text. |
| Create & append | `rooqi_request_write_access` | Create up to **10** new documents and read/append to existing documents in the project and those just created. Never replaces existing text. The model information is declared by the caller. |
| PDF annotation | `rooqi_request_pdf_annotation_access` | Read selected text and page geometry of PDFs in scope and add highlights, underlines or comments. Cannot modify the original PDF or delete/rewrite existing annotations. Does not include create/append. |

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

| Symptom | What to check |
|---|---|
| `appUnavailable` | Open RooQi on this Mac. |
| `transportUnavailable` | Enable the connection in Settings › External Connections and allow the background service in Login Items & Extensions. |
| `approvalRequired` repeating | Approve the window in RooQi, then call the tool again. The CLI waits up to 120 seconds. |
| `denied` | The request was declined in RooQi. Start a new connection to ask again. |
| After updating or moving RooQi | Click **Close Connection**, update or move the app, then **Enable Connection** again. |