> ## Documentation Index
> Fetch the complete documentation index at: https://ngquct-fix-ux-datagrid-editor-filters.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> Stability policy for the URL scheme, MCP tools, and resource catalog

# 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](https://modelcontextprotocol.io): `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

* `tools/call` results now include `structuredContent` next to `content[]`. Older clients keep reading the text content. Newer clients can read the typed object directly. Tools that return data use both: `list_*`, `describe_table`, `get_table_ddl`, `get_connection_status`, `list_recent_tabs`, `search_query_history`, `execute_query`, `confirm_destructive_operation`.
* `tools/list` returns annotations per tool. `readOnlyHint` and `idempotentHint` mark read tools. `destructiveHint` marks `confirm_destructive_operation`. `openWorldHint` marks `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.

When a breaking change ships:

* The next previous version emits a deprecation warning in the activity log on every use of the affected surface.
* The release notes call it out under the `BREAKING` heading in CHANGELOG.
* The deprecated surface continues to work for at least one minor version after the warning is introduced.

## Deprecation lifecycle

1. **Announce.** A `Deprecated` note is added to the docs. CHANGELOG mentions the affected surface.
2. **Warn.** The next version logs a deprecation warning to the activity log when the surface is used. The warning names the replacement.
3. **Remove.** A later version removes the surface. CHANGELOG marks it `BREAKING`.

The warn-to-remove gap is at least one minor version.

## 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](https://github.com/TableProApp/TablePro/issues). Include the TablePro version, the URL or MCP call, expected and actual behavior, and a snippet of the activity log row if relevant.