Skip to main content

​
Versioning

The External API follows TablePro’s semver. The contract is the URL scheme, the MCP tool catalog, the resource list, and the pairing flow. The MCP server accepts three versions from the MCP spec: 2025-03-26, 2025-06-18, and 2025-11-25. On initialize the server echoes the version the client asked for. If the client asks for something else, the server returns 2025-11-25 and the client decides whether to use it.

​
Capabilities

The server reports these capabilities. Anything not listed here is not supported.
  • tools.listChanged: false. The tool list does not change during a session.
  • resources.listChanged: false, resources.subscribe: false. Resources are static. Clients that need fresh data should call resources/read again.
  • prompts.listChanged: false. No prompts yet.
  • logging. Accepts logging/setLevel.
  • completions. Accepts completion/complete. Returns an empty list today.
There is no elicitation capability. The server does not ask clients for input.

​
What changed in 2025-11-25

2025-11-25 is the spec version that defines structuredContent and tool annotations. TablePro emits both regardless of the negotiated version; clients on older versions ignore the extra fields.
  • Every tools/call result includes structuredContent next to content[]. Clients on older versions keep reading the text content; newer clients read the typed object directly.
  • tools/list returns annotations per tool. readOnlyHint and idempotentHint mark read tools. destructiveHint marks confirm_destructive_operation. openWorldHint marks tools that reach a live database, such as execute_query and export_data.
  • serverInfo includes title: "TablePro".

​
Stability rules

Within a major version, the External API is additive only:
  • New URL scheme actions can be added.
  • New MCP tools can be added.
  • New tool input fields can be added if they are optional with a sensible default.
  • New tool output fields can be added.
  • New resources can be added.
  • New error codes can be added.
Within a major version, none of the following will happen:
  • A URL scheme path will not be removed or change meaning.
  • A tool will not be removed or renamed.
  • A required input field will not be added to an existing tool.
  • An output field will not be removed or change type.
  • A resource will not be removed.

​
Breaking changes

Breaking changes ship only at major TablePro version bumps (e.g. 1.x to 2.x). The 0.x series is pre-1.0; we treat minor versions as the release boundary, but only break with explicit notice.

​
Deprecation lifecycle

  1. Announce. The docs mark the surface deprecated and name the replacement. CHANGELOG mentions the affected surface.
  2. Grace. The deprecated surface keeps working for at least one minor version after the announcement.
  3. Remove. A later release removes the surface. CHANGELOG marks it BREAKING.

​
What is not under the contract

The following are not part of the External API contract and can change at any time without notice:
  • Internal MCP message routing details, transport framing, and HTTP path layout under /v1/internal/*.
  • The handshake file format at ~/Library/Application Support/TablePro/mcp-handshake.json. Use the bundled tablepro-mcp CLI rather than parsing it yourself.
  • The tokens file format at ~/Library/Application Support/TablePro/mcp-tokens.json. Tokens are managed via Settings, not the file.
  • Audit log file format at ~/Library/Application Support/TablePro/mcp-audit.db. Read via the activity log view.
  • The connections file format at ~/Library/Application Support/TablePro/connections.json. Treat as best-effort. Schema can shift between minor versions; integrations should fall back to MCP list_connections.

​
Reporting issues

If you find a behavior that contradicts these rules, file an issue at github.com/TableProApp/TablePro. Include the TablePro version, the URL or MCP call, expected and actual behavior, and a snippet of the activity log row if relevant.