MCP Tools

If a dedicated tool covers the job, it beats hand-written SQL. It quotes identifiers for the engine in front of it, applies the user’s row limits, and runs on connections where raw execution is refused. All 46 publish a JSON Schema for input and output, so a client can validate both sides without reading this page. For the wire format, headers and error codes see MCP Protocol.

​

How to read this page

In the tables below, required arguments come first and optional ones follow in parentheses. Unless a row says otherwise:

• connection_id is a connection UUID from list_connections.
• database and schema default to whatever the connection is currently browsing. 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.

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

​

Tool index

​

Scopes and gates

Fourteen tools need tools:write: connect, disconnect, switch_database, switch_schema, insert_rows, confirm_destructive_operation, transaction_control, create_database, drop_database_object, run_maintenance, stop_server_session, focus_query_tab, open_connection_window, open_table_tab. The other 32 need tools:read, execute_query among them until the statement writes. Past the scope, a call clears three more gates:

1. Connection allowlist. A token limited to named connections gets -33007 for anything else.
2. Connection policy. External Clients set to Blocked hides the connection: list_connections omits it and any tool that names it is refused. An AI policy of Never does the same. Ask Each Time shows an approval dialog on the first call that touches the connection, and the answer is remembered for that token until it is revoked.
3. Safe Mode. A write goes through the connection’s Safe Mode, which may ask the user to confirm it or to authenticate. See Approvals.

confirm_destructive_operation needs admin as well, so it takes a Full Access token, and Read Only refuses it outright whatever the token carries. No token skips the user’s approval. Statements that read or write files, or that run server-side code, are refused on every tool. So is more than one statement in a single call.

​

Connections

list_connections omits connections blocked for external clients, connections whose AI policy is Never, and connections outside the token’s allowlist. Its database is the session’s browsed database when connected, the saved default otherwise. The two switch_ tools move what the user sees in TablePro. To run one statement elsewhere, pass database or schema to that tool instead.

​

Schema discovery

describe_table is the one call to make before writing SQL against an unfamiliar table. A column always carries name, data_type, is_nullable and is_primary_key, and picks up is_generated, default_value, extra, comment and allowed_values where the engine reports them; indexes and foreign keys work the same way. include_row_counts defaults to false. Counts come from engine statistics rather than COUNT(*), and are fetched one table at a time, so list_tables skips them when the schema holds more than 200 objects. search_schema locates a column without describing every table; its limit runs 1 to 500, default 50. list_routines takes kind as procedure or function, omitted for both.

​

Reading data

​

browse_table

A filter is { column, operator, value, second_value, case_sensitive }. column and operator are required, second_value is the upper bound for BETWEEN, and case_sensitive defaults to whatever the operator normally does. logic is and (default) or or. The operator list is TablePro’s own filter vocabulary, published in the tool’s input schema as an enum; read it from tools/list rather than hardcoding it. Raw SQL filters are not available over MCP. A sort entry is { column, direction }, direction being ascending (default) or descending, and entries apply in the order given. offset defaults to 0.

​

count_rows

Without filters this returns the engine’s fast estimate unless exact is set. With filters it always counts for real, because an estimate cannot answer a filtered question.

​

execute_query

One statement, 100 KB at most. DROP and TRUNCATE are refused here; use confirm_destructive_operation. When the request carries a progressToken, the tool emits progress at 0.0 (resolving), 0.3 (executing) and 1.0 (done).

​

explain_query

Pass the query with no EXPLAIN prefix, and with no variant to see what this engine offers in available_variants[]. analyze: true runs the statement for real, so an analyzed write needs tools:write and Safe Mode approval.

​

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.

​

Writing data

insert_rows binds parameters, so values are never spliced into SQL text. Each row is an array with one value per column, and a call carries at most 1,000 rows. confirm_destructive_operation runs one DROP, TRUNCATE or ALTER … DROP. Anything that is not destructive is rejected; use execute_query for those. The user approves it first, through your elicitation prompt if your client supports elicitation, otherwise through TablePro’s own dialog on their Mac. transaction_control takes action as begin, commit or rollback. The transaction stays open across calls until it is committed or rolled back, and it runs on the same session as the user’s own tabs. Leave nothing open.

​

Databases and objects

create_database takes options as a flat object of string values drawn from describe_create_database_options, and asks the user before it runs. drop_database_object takes kind as database or schema, deletes everything inside, cannot be undone, and is approved first. run_maintenance takes an operation name from list_maintenance_operations (VACUUM, ANALYZE, OPTIMIZE and whatever else the engine supports) and omits table for the whole database. TablePro generates the statements and runs them in order, asking for approval before each one.

​

Server administration

get_server_dashboard reads the live panels TablePro shows, and runs on PostgreSQL, MySQL, SQL Server, ClickHouse, DuckDB and SQLite. Name the panels in panels[] or omit it for all three. A session carries id (the process id stop_server_session takes), user, database, state, duration_seconds, query, can_kill and can_cancel; a metric carries id, label, value, unit; a slow query carries duration, query, user, database. stop_server_session takes mode as cancel (default) to stop the running query or kill to end the session. The user always approves this one, whatever Safe Mode says. list_session_contexts reports session-level contexts the engine exposes, such as a Snowflake warehouse or role, with the value the session currently holds.

​

The user’s workspace

These read and drive the TablePro app itself, and none of them bypasses the connection allowlist or a blocked connection. 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, usersRoles. 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. 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.

​

Annotations

Every tool ships MCP annotations so a client can decide what to auto-run:

• readOnlyHint: true on the 29 tools that only read. execute_query is not one of them.
• destructiveHint: true on confirm_destructive_operation, drop_database_object and stop_server_session.
• idempotentHint: true where repeating the call is safe.
• openWorldHint: true on the 14 that can reach the database server: every write except switch_database, switch_schema and focus_query_tab, plus execute_query, explain_query and export_data.

​

Errors

A tool that fails returns a successful JSON-RPC result with isError: true and a text body starting with a code: invalid_argument, not_connected, not_found, denied, timeout, unsupported, query_failed, user_cancelled, internal_failure. Protocol errors, with a JSON-RPC error envelope, are reserved for the request itself: a missing scope, an unknown tool, a bad header. The full table is in MCP Protocol.