> ## Documentation Index
> Fetch the complete documentation index at: https://ngquct-feat-ai-sql-walkthroughs.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

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

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