URL Scheme

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. 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/<uuid>`	The saved connection, or fronts its window
`connect/<uuid>/table/…`	A table tab, optionally after switching database or schema
`connect/<uuid>/query?sql=…`	A query tab with the SQL prefilled, after a confirmation
`import?…`	A review sheet that saves a new connection
`integrations/pair?…`	The pairing approval sheet
`integrations/start-mcp`	Nothing. Starts the MCP server and returns
`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.

tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1

No UI action copies a connect link. To find a UUID, call the MCP list_connections tool or read the tablepro://connections 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

tablepro://connect/<connection-uuid>

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.

open "tablepro://connect/9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1"

Open a table

tablepro://connect/<connection-uuid>/table/<table-name>
tablepro://connect/<connection-uuid>/database/<db>/table/<table-name>
tablepro://connect/<connection-uuid>/database/<db>/schema/<schema>/table/<table-name>

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.

# 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

tablepro://connect/<connection-uuid>/query?sql=<percent-encoded-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.

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 tool. This link hands SQL to the GUI and stops there.

Start pairing

tablepro://integrations/pair?client=<name>&challenge=<base64url>&redirect=<url>&response_mode=<mode>&state=<state>&scopes=<scope>&connection-ids=<csv>

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.
`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.
`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.

# 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 has the exchange step and the error codes.

Lazy-start the MCP server

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.

open "tablepro://integrations/start-mcp"

Import a connection

tablepro://import?name=<n>&host=<h>&type=<t>&…

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. Passwords are never accepted in a link.

open "tablepro://import?name=Staging&host=db.example.com&port=5432&type=postgresql&username=admin&database=mydb"

Open a settings pane

tablepro://settings
tablepro://settings/<pane>

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.

open "tablepro://settings/mcp"

On iPhone and iPad

The iOS app answers two of these paths: connect/<uuid> opens the connection, and connect/<uuid>/table/<table-name> 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.

Overview

API reference

Connection IDs are UUIDs

Open a connection

Open a table

Run a query

Start pairing

Lazy-start the MCP server

Import a connection

Open a settings pane

On iPhone and iPad

Errors

​Connection IDs are UUIDs

​Open a connection

​Open a table

​Run a query

​Start pairing

​Lazy-start the MCP server

​Import a connection

​Open a settings pane

​On iPhone and iPad

​Errors

Connection IDs are UUIDs

Open a connection

Open a table

Run a query

Start pairing

Lazy-start the MCP server

Import a connection

Open a settings pane

On iPhone and iPad

Errors