> ## Documentation Index > Fetch the complete documentation index at: https://ngquct-docs-fix-500-query-results.mintlify.site/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](/external-api/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 | ## 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`](/external-api/mcp-tools) tool or read the [`tablepro://connections`](/external-api/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`](/external-api/mcp-tools) tool. This link hands SQL to the GUI and stops there. ## Start pairing ```text theme={null} tablepro://integrations/pair?client=&challenge=&redirect=&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. | | `scopes` | no | One value: `readWrite` or `fullAccess`. Matching is case-insensitive and takes `read_write`, `read-write`, `full_access`, `full-access` and `full`. Any other value, or none, requests `readOnly`. | | `connection-ids` | no | Comma-separated UUIDs to preselect in the allowlist. Defaults to all. | These parameters are a request, not a grant: the sheet lets the user raise or lower every one of them. ```ts theme={null} import { open } from "@raycast/api"; const params = new URLSearchParams({ client: "Raycast on macbook-pro", challenge: challengeB64Url, redirect: "raycast://extensions/ngoquocdat/tablepro/pair-callback", scopes: "readWrite", }); await open(`tablepro://integrations/pair?${params}`); ``` [Pairing](/external-api/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. Either way it writes the port it actually bound to a handshake file at `~/Library/Application Support/TablePro/mcp-handshake.json`. 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](/external-api/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" ``` ## 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**.