Skip to main content
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.

​
Connection IDs are UUIDs

Connection paths take the connection’s UUID, not its display name.
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

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

​
Run a query

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

Opens the approval sheet. The user picks scope, connections and expiry, and TablePro returns a one-time code to redirect. These parameters are a request, not a grant: the sheet lets the user raise or lower every one of them.
Pairing has the exchange step and the error codes.

​
Lazy-start the MCP server

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.

​
Import a connection

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.

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