MCP Tools

JSON-RPC tool catalog with input schemas, output schemas, scope requirements, and examples

The MCP server exposes tools and resources over JSON-RPC. The tools are grouped by category below. Every tool is scope-gated: a request must come with a token whose scope and connection allowlist permit the call.

Transports

The same tool catalog is available over two transports:

• HTTP: MCP Streamable HTTP at http://127.0.0.1:<port>/mcp (port from the handshake file). POST for JSON-RPC requests, GET for the SSE stream that carries server-initiated notifications. Bearer token in Authorization header.
• stdio: bundled tablepro-mcp CLI bridges stdio JSON-RPC to localhost HTTP. No token needed because the bridge reuses the in-app handshake.

The server accepts 2025-03-26, 2025-06-18, and 2025-11-25. On initialize it echoes whichever version the client requested. If the client asks for something else, the server returns 2025-11-25. See Versioning.

Scopes and access

Each tool entry below lists its minimum token scope. The effective permission is MIN(token.scope, connection.externalAccess); see Tokens for the full scope table.

Two per-connection settings gate every call on top of the token:

• External access. blocked hides the connection entirely: list_connections omits it, list_recent_tabs filters its tabs, and any tool that targets it returns 403 forbidden. readOnly blocks write SQL: execute_query with a write statement and any confirm_destructive_operation call return 403, even with a readWrite token. The session-state tools disconnect, switch_database, and switch_schema are gated by token scope only.
• AI policy askEachTime. The first tool call per session that targets the connection shows an in-app approval dialog. TablePro waits up to 30 seconds. Deny returns 403 forbidden with message “User denied MCP access to this connection”; no answer fails the call with a timeout error. An approval covers that connection for the rest of the session.

list_tables, list_schemas, describe_table, get_table_ddl, and execute_query query exactly the database and schema you pass them and leave the app alone: the sidebar’s selected database and every open tab stay where they are, and a tab keeps querying the database and schema it was opened on. switch_database and switch_schema are the only tools that move the app’s selection, which is what they are for.

Connection tools

list_connections

List saved connections. Connections with externalAccess: blocked are silently omitted.

Input: none.

Output:

{
  "connections": [
    {
      "id": "9f1f0c3e-2e3d-4b14-9c3a-1d2f4ad1f6f1",
      "name": "Production",
      "type": "PostgreSQL",
      "host": "db.example.com",
      "port": 5432,
      "database": "app",
      "username": "app",
      "is_connected": false,
      "ai_policy": "askEachTime",
      "safe_mode": "silent"
    }
  ]
}

Scope: readOnly.

connect

Open a database connection.

Input:

{ "connection_id": "9f1f0c3e-..." }

Output:

{
  "status": "connected",
  "current_database": "app",
  "current_schema": "public",
  "server_version": "PostgreSQL 16.2"
}

current_schema and server_version are present when known.

Scope: readOnly.

disconnect

Close a connection.

Input: { "connection_id": "..." }

Output: { "status": "disconnected" } on success.

Scope: readWrite.

get_connection_status

Return status, active database, server version, connect time, and last-active time for a connection.

Input: { "connection_id": "..." }

Output:

{
  "status": "connected",
  "current_database": "app",
  "current_schema": "public",
  "server_version": "PostgreSQL 16.2",
  "connected_at": "2026-04-26T10:14:22Z",
  "last_active_at": "2026-04-26T10:14:22Z"
}

status is one of connected, connecting, disconnected, error. When error, an error object with a message field is included.

Scope: readOnly.

Schema tools

list_databases

Input: { "connection_id": "..." }

Output: { "databases": ["app", "analytics"] } (array of database names)

Scope: readOnly.

list_schemas

Input: { "connection_id": "...", "database": "app" } (database optional)

Output: { "schemas": ["public", "reporting"] } (array of schema names)

Scope: readOnly.

list_tables

Input:

{
  "connection_id": "...",
  "database": "app",
  "schema": "public",
  "include_row_counts": false
}

Output:

{
  "tables": [
    { "name": "users", "type": "TABLE" },
    { "name": "orders_view", "type": "VIEW" }
  ]
}

type is one of TABLE, VIEW, MATERIALIZED VIEW, FOREIGN TABLE, or SYSTEM TABLE. When include_row_counts is true and the driver supports it, each entry also includes row_count.

Scope: readOnly.

describe_table

Columns, indexes, foreign keys, primary key, DDL.

Input:

{
  "connection_id": "...",
  "table": "users",
  "database": "app",
  "schema": "public"
}

database and schema are optional. The connection’s current database and schema are used when omitted.

Output:

{
  "columns": [
    {
      "name": "id",
      "data_type": "uuid",
      "is_nullable": false,
      "is_primary_key": true
    },
    {
      "name": "email",
      "data_type": "text",
      "is_nullable": false,
      "is_primary_key": false
    }
  ],
  "indexes": [
    {
      "name": "users_email_idx",
      "columns": ["email"],
      "is_unique": true,
      "is_primary": false,
      "type": "btree"
    }
  ],
  "foreign_keys": [],
  "ddl": "CREATE TABLE users (...)",
  "approximate_row_count": 12345
}

default_value, extra, and comment are present on a column when set. ddl and approximate_row_count are present when the driver supports them.

Scope: readOnly.

get_table_ddl

Just the CREATE TABLE statement.

Input: same as describe_table (connection_id, table, database, schema).

Output: { "ddl": "CREATE TABLE ..." }

Scope: readOnly.

Query tools

execute_query

Execute a SQL query. All queries are subject to the connection’s safe mode policy. DROP, TRUNCATE, and ALTER…DROP must use confirm_destructive_operation.

Input:

{
  "connection_id": "...",
  "query": "SELECT id, email FROM users WHERE active = true LIMIT 100",
  "max_rows": 500,
  "timeout_seconds": 30,
  "database": "app",
  "schema": "public"
}

Defaults for max_rows and timeout_seconds come from Settings > Integrations > Server Configuration (default row limit, query timeout). max_rows is clamped to the configured maximum (default 10,000). timeout_seconds is clamped to 1-300. Single-statement queries only. Query size cap is 100 KB. database and schema are optional; when present, the query runs against them. It never changes what’s selected in the app, and omitting them runs against the connection’s currently selected database.

Output:

{
  "columns": ["id", "email"],
  "rows": [["9f1f...", "[e-mail]"]],
  "row_count": 1,
  "rows_affected": 0,
  "execution_time_ms": 14,
  "is_truncated": false
}

columns is an array of column-name strings. rows is an array of rows, where each row is an array of strings (or null) aligned to the columns order. status_message is added when the driver returns one.

Scope:

• readOnly for SELECT, SHOW, EXPLAIN.
• readWrite for INSERT, UPDATE, DELETE.
• DROP, TRUNCATE, ALTER…DROP are rejected. Use confirm_destructive_operation.

Safe Mode rules apply on top. A connection in Safe Mode readOnly returns 403 for any write SQL.

Streaming progress: pass _meta.progressToken in the request and the server sends notifications/progress events on the SSE channel as the query moves through “Connecting”, “Executing”, “Formatting result”, and “Done”. Clients that don’t include a token get the final response only.

confirm_destructive_operation

Run a DROP, TRUNCATE, or ALTER…DROP after a typed confirmation.

Input:

{
  "connection_id": "...",
  "query": "DROP TABLE legacy_events",
  "confirmation_phrase": "I understand this is irreversible"
}

The confirmation phrase is fixed: I understand this is irreversible. Anything else returns JSON-RPC -32602 over HTTP 200 with message Invalid params: confirmation_phrase must be exactly: I understand this is irreversible.

Output: same shape as execute_query.

Scope: readWrite or fullAccess (both grant the tools:write MCP scope). The connection’s external access must also permit writes; a readOnly connection rejects destructive operations even with a matching token.

export_data

Export query or table data as CSV, JSON, or SQL.

Input:

{
  "connection_id": "...",
  "format": "csv",
  "tables": ["users", "orders"],
  "max_rows": 5000
}

format is one of csv, json, sql. Defaults for max_rows and the query timeout come from Settings > Integrations > Server Configuration, the same as execute_query: omitting max_rows uses the default row limit (500), and any value you pass is clamped to the maximum row limit (default 10,000). Raise those settings to export more rows. Provide either tables or query. Table names accept letters, digits, underscore, and . for schema-qualified names. Pass output_path to write to disk instead of returning data inline; the path must resolve inside the user’s ~/Downloads directory. Anything else fails with JSON-RPC -32602 over HTTP 200 and message Invalid params: output_path must be inside the Downloads directory (/Users/you/Downloads).

Output: when output_path is set, returns { "path": "...", "rows_exported": N, "is_truncated": false }. Otherwise returns the export inline. A single export returns { "label": "...", "format": "csv", "row_count": N, "is_truncated": false, "data": "..." }. Multiple exports (multi-table requests) return { "exports": [ { "label": "...", "format": "csv", "row_count": N, "is_truncated": false, "data": "..." }, ... ] }. is_truncated is true when the row limit clipped the result.

Scope: readOnly.

switch_database / switch_schema

Input: { "connection_id": "...", "database": "analytics" } or { "connection_id": "...", "schema": "reporting" }

Output: { "status": "switched", "current_database": "analytics" } or { "status": "switched", "current_schema": "reporting" }

Scope: readWrite (moves the connection’s selected database or schema, which the sidebar follows).

Navigation tools

These open or focus tabs and windows in the running TablePro app. They require readOnly scope and respect the connection allowlist; tabs from externalAccess: blocked connections are filtered out.

open_connection_window

Open a connection in TablePro and bring its window to front. If the connection is already open, the existing window is focused.

Input: { "connection_id": "..." }

Output:

{
  "status": "opened",
  "connection_id": "9f1f...",
  "window_id": "..."
}

Scope: readOnly.

open_table_tab

Open a table tab.

Input:

{
  "connection_id": "...",
  "table_name": "users",
  "database_name": "app",
  "schema_name": "public"
}

database_name and schema_name are optional. If omitted, the connection’s current database/schema is used.

Output:

{
  "status": "opened",
  "connection_id": "9f1f...",
  "table_name": "users",
  "window_id": "..."
}

Scope: readOnly.

focus_query_tab

Bring an existing tab to front. The tab_id comes from list_recent_tabs.

Input: { "tab_id": "..." }

Output:

{
  "status": "focused",
  "tab_id": "...",
  "window_id": "...",
  "connection_id": "9f1f..."
}

If the tab is no longer open, the call returns -32602 invalid params with detail tab not found.

Scope: readOnly.

list_recent_tabs

Read the cross-window tab registry. Tabs from connections with externalAccess: blocked are filtered out.

Input: { "limit": 20 } (optional, 1-500, default 20).

Output:

{
  "tabs": [
    {
      "tab_id": "...",
      "connection_id": "9f1f...",
      "connection_name": "Production",
      "tab_type": "query",
      "display_title": "users by signup date",
      "is_active": true,
      "table_name": "users",
      "database_name": "app",
      "schema_name": "public",
      "window_id": "..."
    }
  ]
}

tab_type is one of query, table, createTable, erDiagram, serverDashboard, usersRoles. table_name, database_name, schema_name, and window_id are present when known.

Scope: readOnly.

History tools

search_query_history

Full-text search over the query history database.

Input:

{
  "query": "users active",
  "connection_id": "9f1f...",
  "limit": 50,
  "since": 1745577262,
  "until": 1745663662
}

connection_id is optional. limit is 1-500, default 50. since and until are optional Unix epoch seconds; both bounds are inclusive. Either may be set on its own. Pass an empty query ("") to skip the full-text filter and only narrow by date or connection.

Output:

{
  "entries": [
    {
      "id": "...",
      "connection_id": "9f1f...",
      "database_name": "app",
      "query": "SELECT * FROM users WHERE active = true",
      "executed_at": 1745663662.0,
      "execution_time_ms": 18,
      "row_count": 142,
      "was_successful": true
    }
  ]
}

executed_at is a Unix timestamp in seconds. error_message is included when was_successful is false.

Scope: readOnly.

Errors

Tool failures come back as JSON-RPC error envelopes. Codes follow the JSON-RPC spec plus TablePro’s reserved range:

JSON-RPC code	HTTP status	Meaning
-32700	400	Parse error (malformed JSON body)
-32600	400	Invalid request (bad envelope, missing Mcp-Session-Id)
-32601	200 / 404	Method or resource URI not found
-32602	200	Invalid params (bad input, unknown tab id, unknown connection, wrong confirmation phrase)
-32603	500	Internal error
-32001	404	Session not found
-32002	200	Request cancelled
-32003	200	Request timeout (e.g. query timeout)
-32004	404	Resource not found
-32005	413	Payload too large
-32006	-	Server disabled (reserved, not currently returned)
-32007	403 / 401	Forbidden (token scope, allowlist, or externalAccess rejects); 401 when the token is unknown or revoked
-32008	401	Token expired
-32009	401	Unauthenticated (missing bearer token)
-32000	429 / 503	Server error (rate limited, service unavailable)

Error responses include a message. Example:

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32007,
    "message": "Forbidden: Connection is read only for external clients"
  }
}

A 404 from GET/POST/DELETE /mcp with a stale Mcp-Session-Id returns the JSON-RPC envelope with code: -32001, message: "Session not found". Per the MCP spec, clients MUST treat that response as a signal to start a new initialize handshake before retrying.

401 responses carry a WWW-Authenticate challenge. A missing token returns Bearer realm="TablePro". An unknown or revoked token returns Bearer error="invalid_token". An expired token returns Bearer error="invalid_token", error_description="token expired".