Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion connections/connection-form.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ Encryption sits below the transport. [SSL/TLS](/connections/ssl) covers the mode
| **Post-Disconnect Script** | Shell script run once the session ends, after a pre-connect script ran. See [Connection scripts](#connection-scripts) |
| **Safe Mode** | Confirms, authenticates or refuses queries before they run. See [Safe Mode](/features/safe-mode) |
| **Manual Commit** | Off by default. On, the first change opens a transaction and nothing is saved until you commit it. **Database > Manual Commit** is the same setting. Dimmed on engines that commit schema changes on their own. See [Manual Commit](/features/sql-editor#manual-commit) |
| **AI Policy** | Per-connection override for the in-app AI agents. **Never** also refuses external clients. Shown while **Enable AI Features** is on |
| **AI Policy** | Per-connection override for the in-app AI agents. **Never** also refuses external clients. Under it, each tool you gave **Always Allow** on an [assistant tool card](/features/ai-assistant#tool-calling) is listed by name as **Always allowed**, with **Forget**. After **Save**, a forgotten tool asks again on its next call. Shown while **Enable AI Features** is on |
| **External Clients** | **Blocked**, **Read Only** (the default), or **Read & Write** for MCP clients such as Raycast, Cursor, and Claude Desktop, and for [AppleScript](/developers/applescript) and [Shortcuts](/integrations/shortcuts). A token's own scope cannot raise it. See the [integration security model](/developers#security-model) |
| **AI Rules** | Guidance the AI reads on every chat turn for this connection: table conventions, columns to avoid, join hints. Shown while **Enable AI Features** is on. See [AI Assistant](/features/ai-assistant) |
| **Local only** | Keeps this connection and its passwords off iCloud. Saving an existing synced connection as Local only removes its passwords from iCloud Keychain, so your other devices ask for them again. Shown while **Sync this Mac with iCloud** is on. See [iCloud Sync](/features/icloud-sync#keeping-a-connection-off-icloud) |
Expand Down
4 changes: 2 additions & 2 deletions developers/mcp-protocol.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -241,7 +241,7 @@ Send `notifications/cancelled` with the `requestId` of a request that is still r
{ "jsonrpc": "2.0", "method": "notifications/cancelled", "params": { "requestId": 7, "reason": "user aborted" } }
```

The notification is answered with `202` whether or not anything matched. The cancelled request finishes with `-33002`.
The notification is answered with `202` whether or not anything matched. The cancelled request finishes with `-33002`. A write the database had already started is not stopped: it runs to the end, and the `-33002` carries `data: { "outcome": "unknown" }`. It may have been applied, so check before sending it again.

Cancellation is per principal: a token can only cancel its own requests. Revoking a token cancels everything it has in flight.

Expand Down Expand Up @@ -359,7 +359,7 @@ Per-caller request rates, auth lockouts and pairing lockouts are counted separat
A request with no `io.modelcontextprotocol/protocolVersion` in `_meta` is treated as legacy, and legacy still works the old way:

1. `POST /mcp` with `initialize` and a `protocolVersion` of `2025-11-25` or `2025-06-18`. Any other value is `-32022`.
2. The response carries `protocolVersion`, `capabilities`, `serverInfo` and `instructions`.
2. The response carries `protocolVersion`, `capabilities`, `serverInfo` and `instructions`. `capabilities` follows the token: `tools` needs `tools:read`, and `resources`, `prompts` and `completions` need `resources:read`.
3. Every later request carries `Mcp-Session-Id`. A session belongs to the token that created it; presenting it under another token is `-33001`.
4. A session lives until the server stops. The store holds at most 16 and evicts the least recently used past that. A session the server does not recognize is `-33001`, and the client has to `initialize` again.

Expand Down
5 changes: 3 additions & 2 deletions developers/mcp-resources.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -136,11 +136,12 @@ This is the only subscribable resource. See [Subscriptions](/developers/mcp-subs
"row_count": 142,
"was_successful": true
}
]
],
"is_truncated": false
}
```

`executed_at` is ISO 8601. `schema_name` appears when the entry has one, and `error_message` when `was_successful` is false, redacted. On a connection with masking rules, `query` and `error_message` can hold a fixed sentence and `search` skips some entries: see [Masking rules](/developers/mcp-tools#masking-rules).
`is_truncated` is true when the [size limit](/developers/mcp-tools#answer-size) left out matching entries. `executed_at` is ISO 8601. `schema_name` appears when the entry has one, and `error_message` when `was_successful` is false, redacted. On a connection with masking rules, `query` and `error_message` can hold a fixed sentence and `search` skips some entries: see [Masking rules](/developers/mcp-tools#masking-rules).

## Errors

Expand Down
35 changes: 26 additions & 9 deletions developers/mcp-tools.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,11 @@ In the tables below, required arguments come first and optional ones follow in p
- `database` and `schema` default to whatever the connection is currently browsing, except that `search_schema` without `schema` looks in every schema. Passing them targets somewhere else **without moving the app's selection**.
- An unknown argument is rejected with `-32602`. There is no silent ignoring.
- The result comes back twice: as JSON text in `content[0]`, and as a typed object in `structuredContent`. Read `structuredContent`.
- Timestamps are ISO 8601, error text is redacted, and "a result set" means `columns[]`, `rows[][]`, `row_count`, `rows_affected`, `execution_time_ms`, `is_truncated`, plus `status_message`, `database` and `schema` when they apply.
- Timestamps are ISO 8601, error text is redacted, and "a result set" means `columns[]`, `rows[][]`, `row_count`, `rows_affected`, `execution_time_ms`, `is_truncated`, plus `status_message`, `notes`, `database` and `schema` when they apply.

A column a [masking rule](/features/data-masking) matches comes back masked in every tool that returns rows, `browse_table`, `execute_query` and `export_data` included. The mask replaces the value in `rows[][]`; `columns[]` and `row_count` are unchanged. A filter or sort in the request still runs on the stored values. A connection with rules also changes errors, plans and some text fields: see [Masking rules](#masking-rules).

Row limits default to the server's **Default row limit** setting (500) and are capped by **Maximum row limit** (10,000). Timeouts default to **Query timeout** (30 seconds) and are capped at 300. Both live in **Settings > MCP**.
Row limits default to the server's **Default row limit** setting (500) and are capped by **Maximum row limit** (10,000). Timeouts default to **Query timeout** (30 seconds) and are capped at 300. Both live in **Settings > MCP**. Whatever the row limit, rows also stop at the [answer size limit](#answer-size).

## Tool index

Expand Down Expand Up @@ -65,6 +65,17 @@ The rules also withhold text that can repeat a stored value:

The withheld-message sentence reads `The statement failed with error 1146, SQLSTATE 42S02. Its message is withheld because this connection has masking rules, and the message can repeat a masked value.`, without the codes when there are none. The withheld-statement sentence reads `The statement text is withheld because this connection has masking rules, and it can repeat a masked value.`

## Answer size

One answer holds at most 4 MB, measured after masking. The limit covers `browse_table`, `execute_query`, `confirm_destructive_operation`, `explain_query`, `export_data`, `stop_server_session`, `search_query_history` and the [history resource](/developers/mcp-resources#tablepro%3A%2F%2Fconnections%2F%7Bid%7D%2Fhistory%7B%3Flimit%2Csearch%2Cdate_filter%7D). `run_maintenance` applies it to each statement's result on its own.

- A value longer than 64 KB keeps its first 64 KB and ends in ` [TablePro cut this value: N bytes in all]`, where N is its full size in bytes. A binary value counts its base64 length and keeps the base64 of its first 48 KB. `export_data` never cuts a value.
- Rows keep their order. The first row that does not fit is left out, and so is every row after it.
- `is_truncated` is true when the row limit or the size limit left rows out.
- A result set, `explain_query` and `export_data` carry `notes`, an array of sentences saying why rows were left out or values cut. It is absent when neither happened.

To read a value that was cut, select part of it with a narrower query. To get more rows, ask for fewer columns.

## Connections

| Tool | Arguments | Returns |
Expand Down Expand Up @@ -155,8 +166,8 @@ A lost connection, or a database where no schema could be read, fails the call i
| `browse_table` | `connection_id`, `table` (`columns`, `filters`, `logic`, `sort`, `limit`, `offset`, `timeout_seconds`, `database`, `schema`) | A result set |
| `count_rows` | `connection_id`, `table` (`exact`, `filters`, `logic`, `database`, `schema`) | `table`, `row_count`, `is_approximate`, `filter_count` |
| `execute_query` | `connection_id`, `query` (`max_rows`, `timeout_seconds`, `database`, `schema`, `read_only`) | A result set, plus `result_sets[]` when a SQL Server script returns more than one |
| `explain_query` | `connection_id`, `query` (`analyze`, `variant`, `timeout_seconds`, `database`, `schema`) | `statement` as actually sent, `execution_time_ms`, `columns[]`, `rows[][]`, and where available `plan_text`, `plan` and `available_variants[]` (`id`, `label`, `sql_prefix`, `runs_statement`). On Oracle and SQL Server the driver builds the plan from several statements, so `statement` is the query alone and `sql_prefix` is empty |
| `export_data` | `connection_id`, `format` (`query` **or** `tables`, `sql_table`, `output_path`, `max_rows`, `database`, `schema`) | `format`, `rows_exported`, `is_truncated`, `path` when a file was written, and `exports[]` (`label`, `row_count`, `is_truncated`, `data`) |
| `explain_query` | `connection_id`, `query` (`analyze`, `variant`, `timeout_seconds`, `database`, `schema`) | `statement` as actually sent, `execution_time_ms`, `columns[]`, `rows[][]`, and where available `plan_text`, `plan` and `available_variants[]` (`id`, `label`, `sql_prefix`, `runs_statement`), plus `is_truncated` and `notes` when the [size limit](#answer-size) applied. On Oracle and SQL Server the driver builds the plan from several statements, so `statement` is the query alone and `sql_prefix` is empty |
| `export_data` | `connection_id`, `format` (`query` **or** `tables`, `sql_table`, `output_path`, `max_rows`, `database`, `schema`) | `format`, `rows_exported`, `is_truncated`, `path` when a file was written, `exports[]` (`label`, `row_count`, `is_truncated`, `data`), and `notes` when the size limit left rows out |
| `quote_identifiers` | `connection_id` and at least one of `identifiers`, `literals` (`database`, `schema`) | `identifiers[]` as `{ input, quoted }` and `literals[]` as `{ input, escaped }`, in the order supplied |

### `browse_table`
Expand All @@ -179,7 +190,7 @@ One statement, 100 KB at most. Destructive statements are refused here; use [`co

On SQL Server, send the whole script instead. A variable exists only in the batch that declares it, so a `DECLARE` and the `SELECT`s that read it belong in one call. The script is cut into batches at its `GO` lines, as the query editor cuts it, and `GO 5` runs a batch five times. The gates judge the script by its worst statement: one write anywhere needs `tools:write` and Safe Mode, and any destructive statement refuses the call. `DECLARE` and `EXEC` of a procedure count as writes, `sp_help` included. `EXEC` of a string and `sp_executesql` run server-side code and are refused.

The top-level fields describe the first result set, with `rows_affected` counting the whole script. When the script returns more than one result set, `result_sets[]` lists every one in order, each with `columns`, `rows`, `row_count` and `is_truncated`. `max_rows` caps each result set on its own. `status_message` says when the script left a transaction open.
The top-level fields describe the first result set, with `rows_affected` counting the whole script. When the script returns more than one result set, `result_sets[]` lists every one in order, each with `columns`, `rows`, `row_count` and `is_truncated`. `max_rows` caps each result set on its own, while the [size limit](#answer-size) covers them all together. Once it is spent, the later batches still run, and their result sets come back with no rows and `is_truncated` set. `status_message` says when the script left a transaction open.

A statement runs on the user's own session, inside any transaction it holds. `execute_query`, `confirm_destructive_operation` and [`insert_rows`](#writing-data) follow these rules about it:

Expand All @@ -194,12 +205,16 @@ A batch that raises an error fails the call with the server's message and line n

### `explain_query`

Pass the query with no `EXPLAIN` prefix. Without `variant` the engine's first variant runs, and every result lists them in `available_variants[]`. `analyze: true` picks the variant that runs the statement, so an analyzed write needs `tools:write` and Safe Mode approval, and it is refused when the engine has no such variant or the `variant` you pass only estimates. An engine missing from the [support table](/features/explain-visualization#database-support) is refused.
Pass the query with no `EXPLAIN` prefix. Without `variant` the engine's first variant runs, and every result lists them in `available_variants[]`. `analyze: true` picks the variant that runs the statement, so an analyzed write needs `tools:write` and Safe Mode approval, and it is refused when the engine has no such variant or the `variant` you pass only estimates. An analyzed write goes into query history the way an `execute_query` write does. An engine missing from the [support table](/features/explain-visualization#database-support) is refused.

`plan_text` and the plan rows share one answer, `plan_text` first. `is_truncated` appears, set to true, only when the [size limit](#answer-size) left plan rows out.

### `export_data`

Formats are `csv`, `json` and `sql`; pass exactly one of `query` or `tables[]`. Without `output_path` the text comes back inline in each export entry. With it, the file lands in the user's Downloads folder and never overwrites, so a name that is taken gets `-1`, `-2` and so on; the path must stay inside Downloads, end in the format's extension, and not name a hidden file. SQL output uses the connection's own quoting and literal rules, so exporting a query needs `sql_table` to name the target table.

Every table in one call shares one 4 MB [answer](#answer-size), with or without `output_path`, and each table gets what the ones before it left. Values stay whole: a row that does not fit is left out with every row after it, so a later table can come back with no rows. Export fewer tables, columns or rows per call when `is_truncated` is set.

## Writing data

| Tool | Arguments | Returns |
Expand Down Expand Up @@ -267,13 +282,15 @@ These read and drive the TablePro app itself, and none of them bypasses the conn
| `focus_query_tab` | `tab_id` | `status` (`focused`), `tab_id`, `connection_id`, `window_id` |
| `open_connection_window` | `connection_id` | `status` (`opened`), `connection_id`, `tab_id`, `window_id`, `is_connected` |
| `open_table_tab` | `connection_id`, `table_name` (`database_name`, `schema_name`) | `status` (`opened`), `connection_id`, `table_name`, `tab_id`, `window_id` |
| `search_query_history` | `query` (`connection_id`, `limit`, `since`, `until`) | `entries[]` carrying `id`, `query`, the connection and database it ran on, `source`, `statement_type`, `executed_at`, `execution_time_ms`, `row_count`, `was_successful` and `error_message`, newest first |
| `search_query_history` | `query` (`connection_id`, `limit`, `since`, `until`) | `entries[]` carrying `id`, `query`, the connection and database it ran on, `source`, `statement_type`, `executed_at`, `execution_time_ms`, `row_count`, `was_successful` and `error_message`, newest first, and `is_truncated` |

`list_recent_tabs` and `search_query_history` without `connection_id` never ask the user. They cover only the connections this client reaches without a question, which depends on the [Approval](/features/mcp#connection-access) setting. With `connection_id`, the user is asked about that connection once, as for any call that names one. `focus_query_tab` asks about the tab's connection before it raises the tab.

Starred tables are a good hint at what matters in a database. `list_recent_tabs` covers every readable connection when `connection_id` is omitted, its `limit` runs 1 to 500, default 20, and `tab_type` is one of `query`, `table`, `createTable`, `erDiagram`, `serverDashboard`, `insights`, `tableHealth`, `usersRoles`, `objectSource`, `versionHistory`, `tableListing`.
Starred tables are a good hint at what matters in a database. `list_recent_tabs` takes `limit` from 1 to 500, default 20, and its `tab_type` is one of `query`, `table`, `createTable`, `erDiagram`, `serverDashboard`, `insights`, `tableHealth`, `usersRoles`, `objectSource`, `versionHistory`, `tableListing`.

`open_connection_window` and `open_table_tab` connect first if they have to, and return once the window has a tab or fail after 8 seconds. `open_table_tab` without `database_name` or `schema_name` means the ones the connection is on, and its `tab_id` is that table's tab, never a table of the same name elsewhere.

`search_query_history` searches the history TablePro keeps on this Mac. Pass `""` to match everything and filter by date alone; `since` and `until` are Unix epoch seconds, and `limit` runs 1 to 500, default 50. Results cover only connections this client may reach, with or without `connection_id`.
`search_query_history` searches the history TablePro keeps on this Mac. Pass `""` to match everything and filter by date alone; `since` and `until` are Unix epoch seconds, and `limit` runs 1 to 500, default 50. `is_truncated` is true when the [size limit](#answer-size) left out matching entries.

## Annotations

Expand Down
Loading
Loading