Skip to main content

​
MCP Clients

Any MCP client that supports the stdio transport and can run a command on disk can connect to TablePro. The pattern is the same across every client:
The tablepro-mcp CLI ships inside the app bundle. It reads ~/Library/Application Support/TablePro/mcp-handshake.json for the local port and a bridge token, then forwards stdio JSON-RPC to the app’s HTTP MCP server. If the handshake file is missing or points at a dead process, the bridge launches TablePro itself (open -g tablepro://integrations/start-mcp) and polls up to 10 seconds for a fresh handshake. You do not need to start TablePro first. You never put a token in the client config. At every server start TablePro mints a full-access bridge token named __stdio_bridge__ and writes it to the handshake file; the bridge picks it up from there. Pairing and manually created tokens apply only to HTTP clients.
The bridge token is full access. To give an AI agent a narrower scope or a connection allowlist, use the HTTP transport with a token you mint yourself.
If TablePro is installed outside /Applications (Setapp, custom path), replace the command value with the absolute path to your bundle’s tablepro-mcp binary.

​
Clients using the standard shape

These clients take the exact JSON above; only the config file differs.

​
Claude Code

The double dash separates Claude Code’s flags from the command it runs. stdio is the default transport. Verify with claude mcp list.

​
VS Code

VS Code has native MCP support (1.99+). Run MCP: Open User Configuration from the Command Palette, or create .vscode/mcp.json in the workspace. The top-level key is servers, not mcpServers:
Open Copilot Chat in agent mode and confirm the TablePro tools appear in the tools picker.

​
Continue

Continue reads MCP configs from .continue/mcpServers/ in your workspace. Create .continue/mcpServers/tablepro.yaml:
Reload Continue’s config from the gear menu.

​
Zed

Zed keys MCP servers under context_servers (not mcpServers) in ~/.config/zed/settings.json:
Or use the Agent Panel: header menu > Settings > MCP Servers > + Add Custom Server > Local tab. That dialog requires an "args": [] field even though the settings-file form treats it as optional.

​
Goose

Run goose configure, choose Add Extension > Command-line Extension, name it tablepro, and enter the binary path as the command. Or add to ~/.config/goose/config.yaml by hand:
Run goose session and ask for the tool list to confirm.

​
Setup snippets in TablePro

Click Connect a Client… in Settings > Integrations. The sheet covers Claude Desktop, Claude Code, Cursor, and Zed, with numbered steps and copyable snippets that already contain the correct binary path for your install.

​
Generic or custom client

If you are building against the MCP specification, TablePro speaks two transports:
  • stdio: spawn the tablepro-mcp binary with no arguments. It handles the handshake and forwards JSON-RPC over stdin and stdout. No token, no environment variables, full access.
  • HTTP: http://127.0.0.1:<port>/mcp with the port from the handshake file and a bearer token from Pairing or the Settings UI. See Tokens for scope rules.
Use HTTP when the client runs on another machine, cannot spawn a local process, or needs a tighter scope than the bridge token. See MCP Server for remote setup.

​
HTTP transport

Mint a token in Settings > Integrations > Authentication and point the client at the server directly. Cursor’s form:
Replace 23508 with the port shown in Settings > Integrations. Other clients use the same url plus headers shape, sometimes under type: streamable-http. Check the client’s docs.

​
What the AI sees

AI clients see the full tool catalog. For an unfamiliar schema the AI is expected to call describe_table before generating SQL, and mutating SQL goes through the host’s tool-confirmation UI. The connection’s externalAccess setting and the token scope still apply: a read-only connection rejects writes regardless of what the AI tries.

​
Verify the connection

Ask the client to list TablePro tools or call list_connections. Success looks like:
  • The client lists tools such as list_connections, list_tables, describe_table, and execute_query.
  • A list_connections call returns the connections you have saved in TablePro.
If the call fails, the response tells you which layer rejected it:
  • stdio process exits immediately: the bridge could not launch TablePro or got no handshake within 10 seconds. Open TablePro manually and check that Settings > Integrations shows the server running.
  • 401 Unauthorized: the bridge token is stale. The stdio bridge re-reads the handshake and retries on its own; you only see this if the retry also fails, which means TablePro is not running.
  • 403 Forbidden: the connection’s externalAccess is blocked or readOnly, or the token’s allowlist excludes it. Adjust External Access in TablePro’s connection editor.
  • 404 Session not found (JSON-RPC code -32001): the session hit the 15-minute idle timeout or the server restarted. The stdio bridge starts a new session on its own and replays the call, so you should never see this through the bridge. If you speak HTTP to the server directly, drop the cached Mcp-Session-Id and send a new initialize request yourself. Most HTTP clients do not do this for you.
  • 429 Too Many Requests: 5 failed auth attempts within 60 seconds against the same (client_address, principal) pair triggered a 5-minute lockout. Wait it out or restart TablePro.

​
Troubleshooting

Handshake timeout. TablePro launched but did not respond to tablepro://integrations/start-mcp within 10 seconds. Open Settings > Integrations, toggle Enable MCP Server off and on, then re-launch the client. Stale handshake file. The bridge detects a handshake from a dead process and relaunches TablePro on its own. If connections still fail, delete ~/Library/Application Support/TablePro/mcp-handshake.json and reopen TablePro; the app rewrites it. Setapp or non-default install path. Replace /Applications/TablePro.app in the command with your install path. For Setapp the bundle lives under ~/Applications/Setapp/TablePro.app. Port conflict. If the configured port (default 23508) is taken, TablePro falls back to a free port in the 51000-52000 range and rewrites the handshake file. A bridge that is already running re-reads the file the next time a call fails against the old port, so it picks up the new one without a restart. Sessions recover on their own. The MCP server drops a session after 15 minutes with no client attached, and restarting the server from Settings retires every session and rotates the bridge token. In both cases the stdio bridge starts a fresh session and replays the call that triggered it. You do not need to restart your agent or toggle the server. While an agent is attached, the bridge pings every 5 minutes, so an idle session stays alive rather than being recreated. Tool calls return 403 Connection is read-only for external clients. The connection’s external access is readOnly and the SQL is a write. Change external access in TablePro, or run the query in TablePro’s editor.