Skip to main content
Ask the server which protocol versions it takes, never this page: server/discover returns them in supportedVersions, and an unsupported one is rejected with -32022 whose data.supported carries the same list. A client that hardcodes the list breaks on the release that adds one. The other number, TablePro’s own, follows semver and governs every surface in the contract.

​
What the contract covers

​
Which era gets new work

The newest protocol version is the only one that gets new features. It is stateless, it carries two methods no older version can reach, and it is what a new client should be built against. Older versions keep working through initialize and Mcp-Session-Id so a shipped client does not break on an app update, and they see a reduced feature set. One stays accepted for as long as the specification lists it as current or recent. Dropping one is a Removed entry in the CHANGELOG, never a silent change. MCP Protocol has the version list and the per-era differences. For stdio clients this is somebody else’s problem: the bundled tablepro-mcp bridge answers the client’s initialize locally and speaks the newest version upstream. See MCP Clients.

​
Stability rules

Within a major TablePro version every covered surface is additive only. Per surface, that means:
  • A tablepro:// path or parameter is never removed and never changes meaning.
  • A settings pane id is never removed and keeps opening the same pane, whatever the pane is called.
  • On iPhone and iPad, connect/<uuid> and connect/<uuid>/table/<name> keep working. Any other path under a connection opens the connection alone.
  • A scheme on Connection URLs keeps opening the same database type, and a documented query parameter keeps its meaning.
  • A database URL’s parameter names match in any case. An unknown one is ignored, except on MongoDB, where it is passed to the driver. tablepro:// parameter names are case-sensitive.

​
AppleScript

  • A class, property, command, parameter or enumerator is never removed or renamed, and its four-character code never changes.
  • A record a command returns keeps its fields. New fields can appear.

​
MCP and pairing

  • New tools, resources, prompts and error codes can appear.
  • A new tool input field can appear when it is optional and has a default.
  • A new tool output field can appear.
  • A new pairing parameter can appear when it is optional.
  • A token scope keeps its name and what it grants. connections:display only ever widens what list_connections returns for purpose: "display", never what any tool can run.
And within a major version, none of these happen:
  • A tool or prompt is removed or renamed.
  • A required input field is added to an existing tool.
  • An output field is removed or changes type.
  • A resource is removed.
  • /mcp or /v1/integrations/exchange moves.
  • A pairing parameter is removed, or the redirect changes how it delivers the code.
  • A scope is removed or renamed, or the exchange response drops scope.
  • The default port changes from 23508.
Error codes are the one place this already moved. TablePro’s own codes left the -32000 block, which the specification froze, for -33000 and above; a client that matched on the old numbers needs updating once. The current table is in MCP Protocol. The default port is not the port on every Mac. The user can set another under Settings > MCP, and when 23508 is taken at start the server binds a free port instead. Treat the port as a setting that defaults to 23508; the pane’s Status row shows the one in use.

​
The tablepro command and the app’s identity

  • tablepro, once installed from Settings > General, stays at /usr/local/bin/tablepro and hands each argument to the app the way open -b com.TablePro does: database URLs, tablepro:// links, .sql files and database files. With no argument it opens the app.
  • The bundle ID stays com.TablePro.
  • The MCP bridge stays at Contents/MacOS/tablepro-mcp inside the app bundle.
  • Where the bundle sits is up to the user. Find the app by bundle ID.

​
Breaking changes before 1.0

The app is on 0.x, so the minor version is the release boundary. A break can land between 0.67 and 0.68, but never silently. Once 1.0 ships, breaks move to major bumps. Anything deprecated is deprecated in the docs first, with the replacement named and a CHANGELOG entry to match. It then keeps working for at least one more minor version. A later release removes it, marked BREAKING in the CHANGELOG. Deprecated now:
  • Pairing links without response_mode. Send response_mode=query, or response_mode=context for a host that takes one context launch parameter. See Response modes.

​
What is not under the contract

These can change in any release, without notice:
  • Transport framing, internal message routing, and any HTTP path other than /mcp and /v1/integrations/exchange.
  • The handshake file at ~/Library/Application Support/TablePro/mcp-handshake.json. Use the bundled tablepro-mcp bridge, which finds the server on its own, or connect over HTTP to the port on the Status row in Settings > MCP, 23508 by default.
  • The connections file at ~/Library/Application Support/TablePro/connections.json. List connections with list_connections or AppleScript instead.
  • The preferences in ~/Library/Preferences/com.TablePro.plist, including the connection groups and tags kept there.
  • Keychain items the app writes, such as connection passwords and token hashes.
  • The app’s SQLite databases. Read query history with search_query_history, and the audit log at mcp-audit.db in the MCP Activity window.
  • Token storage. Tokens are managed in Settings > MCP.
  • Where the app is installed.

​
Reporting a contradiction

File an issue at github.com/TableProApp/TablePro with the TablePro version, the call, expected and actual behavior, and the matching activity log row if there is one.