> ## Documentation Index > Fetch the complete documentation index at: https://docs.tablepro.app/llms.txt > Use this file to discover all available pages before exploring further. # URL Scheme > Every tablepro:// deep link action with parameters and examples macOS hands the URL to TablePro, which parses it, confirms anything that could do damage, and opens something on screen. Nothing comes back over the scheme: to read rows, use [MCP](/developers/mcp-tools). Call it from a shell with `open`, from another app with `NSWorkspace.shared.open(url:)`, or from a Raycast extension with `open()` from `@raycast/api`. | Path after `tablepro://` | Opens | | - | - | | [`connect/`](#open-a-connection) | The saved connection, or fronts its window | | [`connect//table/…`](#open-a-table) | A table tab, optionally after switching database or schema | | [`connect//query?sql=…`](#run-a-query) | A query tab with the SQL prefilled, after a confirmation | | [`import?…`](#import-a-connection) | A review sheet that saves a new connection | | [`integrations/pair?…`](#start-pairing) | The pairing approval sheet | | [`integrations/start-mcp`](#lazy-start-the-mcp-server) | Nothing. Starts the MCP server and returns | | [`settings/`](#open-a-settings-pane) | Settings on that pane, or on the last-used pane | ## Connection IDs are UUIDs Connection paths take the connection's UUID, not its display name. ```text theme={null} tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1 ``` No UI action copies a connect link. To find a UUID, call the MCP [`list_connections`](/developers/mcp-tools) tool or read the [`tablepro://connections`](/developers/mcp-resources) resource. The welcome window's **Copy TablePro Link** context menu item copies a `tablepro://import?…` link for sharing a connection definition, which is a different thing. ## Open a connection ```text theme={null} tablepro://connect/ ``` Opens the saved connection, or brings its window to front when it is already open. A UUID that matches no saved connection shows an error sheet. A connection with a pre-connect script shows the script text in a confirmation dialog first, and cancelling that dialog cancels the whole link. This applies to every `connect/…` form. ```bash theme={null} open "tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1" ``` ## Open a table ```text theme={null} tablepro://connect//table/ tablepro://connect//database//table/ tablepro://connect//database//schema//table/ ``` The first form uses the connection's current database and schema. The second switches database first. The third switches both, database before schema, which is the Postgres shape. On an engine with schemas and no database to switch between, such as Oracle, a lone `database` segment names the schema. A segment naming a dimension the engine does not have is dropped rather than applied to the other one. Percent-encode table and schema names that contain spaces or reserved characters. ```bash theme={null} # The current database open "tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1/table/users" # A named database open "tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1/database/analytics/table/events" # Database and schema open "tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1/database/app/schema/reporting/table/daily_events" ``` ## Run a query ```text theme={null} tablepro://connect//query?sql= ``` A dialog titled **Open Query from Link** appears first, previewing the first 300 characters of the SQL; **Open Query** opens the tab. Nothing executes, the user runs it from the editor. A tab already holding exactly this SQL comes to front instead of a second one opening. `sql` is required and caps at 51,200 UTF-16 units. Longer than that and the link is dropped. ```bash theme={null} open "tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1/query?sql=SELECT%20*%20FROM%20users%20LIMIT%2010" ``` To run SQL from a script and read rows back, use the MCP [`execute_query`](/developers/mcp-tools) tool. This link hands SQL to the GUI and stops there. ## Start pairing ```text theme={null} tablepro://integrations/pair?client=&challenge=&redirect=&response_mode=&state=&scopes=&connection-ids= ``` Opens the approval sheet. The user picks scope, connections and expiry, and TablePro returns a one-time code to `redirect`. | Parameter | Required | Description | | - | - | - | | `client` | yes | Display name shown in the approval sheet, such as `Raycast on macbook-pro`. | | `challenge` | yes | Base64url SHA-256 of the verifier: exactly 43 characters (PKCE). | | `redirect` | yes | Where the code is delivered. A loopback `http(s)` URL or a private-use scheme registered by an installed app; anything else is refused, including `tablepro://` and any scheme a web browser handles. | | `response_mode` | no | `query` for flat `code` and `state` parameters, `context` for one JSON `context` parameter. Any other value refuses the link. Leaving it out is deprecated: see [Response modes](/developers/pairing#response-modes). | | `state` | no | Opaque value of up to 1,024 UTF-8 bytes, returned unchanged with the code or the error. A longer one refuses the link. | | `scopes` | no | A permission level, `readWrite` or `fullAccess`, plus `connections:display` for a launcher, separated by spaces or commas. Matching is case-insensitive and takes `read_write`, `read-write`, `full_access`, `full-access` and `full`. Unknown entries are skipped; no level requests `readOnly`, and several start at the lowest. See [Scopes](/developers/pairing#scopes). | | `connection-ids` | no | Comma-separated UUIDs to preselect in the allowlist. Only omitting it means every connection: an empty value, or one entry that is not a UUID, refuses the link. | `scopes` and `connection-ids` are a request, not a grant: the sheet lets the user raise or lower both. ```bash theme={null} # The challenge for the RFC 7636 sample verifier, and a loopback listener on port 7391 open "tablepro://integrations/pair?client=My%20Launcher&challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&redirect=http%3A%2F%2F127.0.0.1%3A7391%2Fcallback&response_mode=query&state=af0ifjsldkj&scopes=readWrite" ``` [Pairing](/developers/pairing) has the exchange step and the error codes. ## Lazy-start the MCP server ```text theme={null} tablepro://integrations/start-mcp ``` Starts the MCP server if it is not running, then returns. MCP does not have to be enabled in Settings first. The bundled `tablepro-mcp` CLI uses this to bootstrap on a cold launch. The server takes the configured port (`23508` by default) and falls back to a kernel-assigned free port when that one is busy. The **Status** row in **Settings > MCP** shows the port it bound. A launch whose only reason is this URL stays in the background: no Dock icon, no app switcher entry, until it has a window to show. ```bash theme={null} open "tablepro://integrations/start-mcp" ``` ## Import a connection ```text theme={null} tablepro://import?name=&host=&type=&… ``` Shows a review sheet with the parsed connection, then saves it on **Add Connection**. `name`, `host` and `type` are required; the rest of the connection form maps to query parameters listed in [Connection Import](/developers/connection-import). Passwords are never accepted in a link. ```bash theme={null} open "tablepro://import?name=Staging&host=db.example.com&port=5432&type=postgresql&username=admin&database=mydb" ``` ## Open a settings pane ```text theme={null} tablepro://settings tablepro://settings/ ``` The bare link opens Settings on the last-used pane, the same as `Cmd+,`. With a pane id it opens that pane. The link only navigates and never changes a setting. | Pane | id | | - | - | | General | `general` | | Appearance | `appearance` | | Editor | `editor` | | Data | `data` | | Keyboard | `keyboard` | | Profiles | `profiles` | | Notifications | `notifications` | | AI | `ai` | | MCP | `mcp` | | Plugins | `plugins` | | Sync | `sync` | | License | `license` | Ids are lowercase and matched exactly, and they stay the same when a pane is renamed. An unknown id opens the last-used pane with no error, so a link to a pane added in a later version still opens Settings on an older one. Path segments and query items after the id are ignored. ```bash theme={null} open "tablepro://settings/mcp" ``` ## On iPhone and iPad The iOS app answers two of these paths: `connect/` opens the connection, and `connect//table/` opens it on that table. Any other path under a connection, such as `database/…` or `query`, opens the connection alone. `import`, `integrations` and `settings` links do nothing. ## Errors A URL that fails to parse is dropped with no UI at all: an invalid UUID, an unknown path, a missing required parameter, over-limit SQL. The reason goes to the system log under subsystem `com.TablePro`, so check Console.app when a link does nothing. A URL that parses and then fails shows an error sheet. A valid UUID with no matching connection gives `No saved connection with ID "…".` under the title **Connection Failed**. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.