> ## Documentation Index
> Fetch the complete documentation index at: https://ngquct-feat-721-compare-sync.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Clients

> Connect Claude Desktop, Claude Code, Cursor, VS Code, Cline, Continue, Zed, Windsurf, Antigravity, Goose, and custom clients to TablePro over stdio

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:

```json theme={null}
{
  "mcpServers": {
    "tablepro": {
      "command": "/Applications/TablePro.app/Contents/MacOS/tablepro-mcp"
    }
  }
}
```

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.

<Note>
  The bridge token is full access. To give an AI agent a narrower scope or a connection allowlist, use the [HTTP transport](#http-transport) with a token you mint yourself.
</Note>

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.

| Client         | Config file                                                       | How to open it                                                                                   |
| -------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | **Settings > Developer > Edit Config**, then restart Claude Desktop                              |
| Cursor         | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project)     | **Settings > MCP > + Add new global MCP server**, then restart Cursor                            |
| Cline          | `cline_mcp_settings.json`                                         | Cline panel > MCP Servers icon > **Configure MCP Servers**                                       |
| Windsurf       | `~/.codeium/windsurf/mcp_config.json`                             | MCP icon in the Cascade panel > **Configure**, then restart Cascade                              |
| Antigravity    | `~/.gemini/antigravity/mcp_config.json`                           | Chat panel `...` menu > **MCP Servers > Manage MCP Servers > View raw config**, then **Refresh** |

## Claude Code

```bash theme={null}
claude mcp add tablepro -- /Applications/TablePro.app/Contents/MacOS/tablepro-mcp
```

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`:

```json theme={null}
{
  "servers": {
    "tablepro": {
      "type": "stdio",
      "command": "/Applications/TablePro.app/Contents/MacOS/tablepro-mcp"
    }
  }
}
```

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`:

```yaml theme={null}
mcpServers:
  - name: tablepro
    type: stdio
    command: /Applications/TablePro.app/Contents/MacOS/tablepro-mcp
```

Reload Continue's config from the gear menu.

## Zed

Zed keys MCP servers under `context_servers` (not `mcpServers`) in `~/.config/zed/settings.json`:

```json theme={null}
{
  "context_servers": {
    "tablepro": {
      "command": "/Applications/TablePro.app/Contents/MacOS/tablepro-mcp"
    }
  }
}
```

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:

```yaml theme={null}
extensions:
  tablepro:
    type: stdio
    cmd: /Applications/TablePro.app/Contents/MacOS/tablepro-mcp
    enabled: true
    timeout: 300
```

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](https://modelcontextprotocol.io), 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](/external-api/pairing) or the Settings UI. See [Tokens](/external-api/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](/features/mcp#remote-access) for remote setup.

## HTTP transport

Mint a token in **Settings > Integrations > Authentication** and point the client at the server directly. Cursor's form:

```json theme={null}
{
  "mcpServers": {
    "tablepro": {
      "url": "http://127.0.0.1:23508/mcp",
      "headers": {
        "Authorization": "Bearer tp_your_token_here"
      }
    }
  }
}
```

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](/external-api/mcp-tools). 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.