diff --git a/developers/mcp-protocol.mdx b/developers/mcp-protocol.mdx index fecc03c..92651da 100644 --- a/developers/mcp-protocol.mdx +++ b/developers/mcp-protocol.mdx @@ -5,7 +5,7 @@ description: "Wire contract for TablePro MCP server: protocol versions, required `2026-07-28` is the revision to write against, and two older ones still answer for clients that have not moved. This page is the wire contract; for the tools themselves see [MCP Tools](/developers/mcp-tools). -Most people never read it. The bundled `tablepro-mcp` stdio bridge speaks this for you, and every client in [MCP Clients](/integrations/mcp-clients) goes through the bridge. Read on if you are writing a client against the HTTP endpoint directly. +Most people never read it. The bundled `tablepro-mcp` stdio bridge speaks this for you, and every macOS client in [MCP Clients](/integrations/mcp-clients) goes through the bridge. Read on if you are writing a client against the HTTP endpoint directly. ## One round trip @@ -84,6 +84,18 @@ It then calls `server/discover` over that socket and checks `app.tablepro/instanceId` against the handshake. A mismatch refuses the connection. A restart or socket failure requires a fresh trusted handshake; the bridge does not fall back to TCP. +Every stdio client shares the bridge's token, so the bridge adds `app.tablepro/bridgeInstance` to the +`_meta` of each request it forwards: a random id, one per bridge process. Two sessions of the same +client send the same `clientInfo` and number their requests alike, and this id keeps a cancellation +from one session off the other's request. The server reads it only from requests on the bridge token. + +A TablePro the bridge launched that does not start the server writes `mcp-start-refused.json` beside +the handshake, with `pid`, `refusedAt` and `reason`: `turnedOff` when **Enable MCP Server** is off, +`failedToStart` when the server tried and failed. The bridge reads only a refusal written after its own +launch request, stops polling, and exits with the matching message. A refusal with no `reason` reads as +`turnedOff`, and one with a reason the bridge does not know reads as `failedToStart`. This file is +outside the stable contract too. + ## Protocol versions | Version | Era | Notes | @@ -102,7 +114,7 @@ There is no handshake in the modern era: no `initialize`, no `Mcp-Session-Id`, n - `io.modelcontextprotocol/protocolVersion` (**required**): a supported version string. Missing or empty is `-32602`; unsupported is `-32022`. - `io.modelcontextprotocol/clientCapabilities` (**required**): a JSON object. `{}` is valid and means you support nothing extra. A non-object is `-32602`. -- `io.modelcontextprotocol/clientInfo` (optional): `name`, `title`, `version`. It names your client in the activity log and in **Connected Clients**. +- `io.modelcontextprotocol/clientInfo` (optional): `name`, `title`, `version`. It names your client in the activity log, which keeps `title`, else `name`, and in **Connected Clients**, which shows the app's own name and logo when `name` matches a client TablePro knows. - `progressToken` (optional): string or integer. See [Progress](#progress). - `traceparent`, `tracestate`, `baggage` (optional): W3C trace context, carried through untouched. @@ -158,7 +170,7 @@ An unknown method answers HTTP `404` with JSON-RPC `-32601`. A method that exist ### `server/discover` -Replaces `initialize` for stateless clients. It takes no parameters beyond `_meta` and needs no scope, so it is the first call a client should make. +Replaces `initialize` for stateless clients. It takes no parameters beyond `_meta` and needs no scope, so it is the first call a client should make. It does not list the caller in **Connected Clients**; the first other request does. ```json { diff --git a/developers/pairing.mdx b/developers/pairing.mdx index 8c988e9..0a906a2 100644 --- a/developers/pairing.mdx +++ b/developers/pairing.mdx @@ -66,7 +66,8 @@ const params = new URLSearchParams({ }); await openUrl(`tablepro://integrations/pair?${params}`); // however your host opens a URL -// Step 3. Your callback receives ?code=&state=, or ?error=access_denied when the user says no. +// Step 3. Your callback receives ?code=&state=, ?error=access_denied when the user says no, +// or ?error=server_error when TablePro could not issue the token after the user approved. // 23508 is the default port. Make it a setting: if the port is taken, the server binds another one, // and the Status row in Settings > MCP shows the port in use. export async function exchange(callback: URL, port = 23508): Promise { @@ -114,6 +115,10 @@ passes an extension a single launch parameter named `context`, as Raycast does. | `context` | `?context={"code":"","state":""}` | `?context={"error":"access_denied","error_description":"user_denied","state":""}` | | absent (deprecated) | `?context={"code":""}` for `raycast://`, `?code=` for any other scheme | `error=denied` and `error_description=user_denied`, wrapped the same way | +When the user approves and TablePro then cannot issue the token, the redirect carries +`error=server_error` and `error_description=token_not_issued`, with `state`, in the same shape as a +deny for the request's mode. Treat it as a failure to retry, not as a refusal. + The `context` value is JSON with sorted keys, percent-encoded like any other query value. Any other `response_mode` drops the link: no sheet opens and nothing reaches `redirect`. Query items already on `redirect` stay as they were, with these appended after them. @@ -193,6 +198,12 @@ credential with `400 unsupported_token_type`. With **Enable MCP Server** off, the pair link stops before the approval sheet with an alert that names **Settings > MCP**. No redirect is opened, so the extension sees no answer. +Approving can still fail before the client gets a code, such as when the token cannot be saved to the +Keychain. TablePro shows **Pairing Failed** with the reason and opens the redirect with the +[`server_error` answer](#response-modes). Start a new pair request once the cause is fixed. The bundled +`tablepro pair` reports this as a failure and exits 1; see +[Status and pairing](/integrations/terminal#status-and-pairing). + A failed verification burns the code, so retrying with a guessed verifier is not an option: start a new pair request. diff --git a/developers/tokens.mdx b/developers/tokens.mdx index 8f9f41f..1577c44 100644 --- a/developers/tokens.mdx +++ b/developers/tokens.mdx @@ -63,7 +63,7 @@ The token list in **Settings > MCP > Authentication** shows prefix, name, permis Revoking cancels every request that token has in flight and clears the connection approvals the user had granted it, so a re-issued token has to ask again. The next call gets `-33009` with HTTP `401`. -**Disconnect** in the Connected Clients list revokes that client's token. It is not a soft disconnect: the client has to pair again or be given a new token. +**Disconnect** in the Connected Clients list revokes the token of a client that holds its own. It is not a soft disconnect: the client has to pair again or be given a new token. A client on the stdio bridge is the exception, under [The stdio bridge token](#the-stdio-bridge-token). For the bundled macOS command, follow [Status and pairing](/integrations/terminal#status-and-pairing) to replace or remove its token. Its [revocation route](/developers/pairing#revoking-a-token) is private. @@ -74,7 +74,7 @@ Every server start mints a token named `__stdio_bridge__` and writes it into the It expires after an hour and is rotated 15 minutes before that, deleted when the server stops, and any stale copy is removed the next time the store loads. It is hidden from the Settings token list, though its name can appear in the activity log. For a narrower scope, skip the bridge and connect over [HTTP with a token you mint](/integrations/mcp-clients#http-transport). -Renewing the token does not cancel work. The old token stops authenticating at once and the bridge picks up the new one, but a request the old token already started, such as a long query or one waiting on a Safe Mode prompt, keeps running until the old token's own expiry, 15 minutes after the renewal. **Disconnect** on a bridge row in Connected Clients revokes the current token and cancels the requests in flight on it and on every earlier one at once; the bridge keeps its connection approvals. +Renewing the token does not cancel work. The old token stops authenticating at once and the bridge picks up the new one, but a request the old token already started, such as a long query or one waiting on a Safe Mode prompt, keeps running until the old token's own expiry, 15 minutes after the renewal. Every stdio client shares this token, and Connected Clients lists each one by the name it sends, across renewals. **Disconnect** on one of them cancels that client's requests in flight and revokes nothing: the others keep working, and the disconnected one can send new requests at once. Remove TablePro from it in **Connect a Client…**, or turn off the server, to stop it. ## Stored fields @@ -98,6 +98,7 @@ Every authentication, tool call, resource read, and query is recorded in `~/Libr | Field | Values | |-------|--------| | Timestamp | when the call happened | +| Client | the name the client sent in `clientInfo`, its `title` when it has one; empty for rows no client caused | | Token | the token behind the call, by name and id | | Category | `auth`, `access`, `admin`, `query`, `tool`, `resource` | | Action | `auth.success`, `auth.failure`, `auth.rateLimited`, `pairing.exchange`, `pairing.redirectRejected`, `token.created`, `token.revoked`, `server.started`, `server.stopped`, `query.executed`, `tool.`, `resource.read` | diff --git a/features/mcp.mdx b/features/mcp.mdx index 3552e76..bd4fd46 100644 --- a/features/mcp.mdx +++ b/features/mcp.mdx @@ -16,9 +16,9 @@ This page covers the **Settings > MCP** pane. The protocol itself, the tool cata Open **Settings > MCP** and turn on **Enable MCP Server**. The **Status** row underneath is how you check it before touching a client config: it reads **Running on port 23508**, or **Stopped**, or **Couldn't start** with the reason below it. **Try Again** beside a failure starts the server again. -With the toggle off, nothing starts the server. A client that launches the bundled `tablepro-mcp` bridge gets "The TablePro MCP server is turned off" within a second instead of a timeout, and pairing an extension stops at the same message with **Open MCP Settings**. +With the toggle off, nothing starts the server. A client that launches the bundled `tablepro-mcp` bridge gets "The TablePro MCP server is turned off" within a second instead of a timeout, and pairing an extension stops at the same message with **Open MCP Settings**. With the toggle on and a server that fails to start, the bridge reports that failure instead of a timeout. -While it is only answering a client, TablePro stays out of the Dock and the app switcher. It appears in both, with its menu bar, once it has a window on screen, including one a client asked it to open. A TablePro the bridge launched while the toggle is off quits again. +While it is only answering a client, TablePro stays out of the Dock and the app switcher. It appears in both, with its menu bar, once it has a window on screen, including one a client asked it to open. A TablePro the bridge launched quits again when the toggle is off or the server fails to start. The default HTTP port is **23508**. If it is taken, the server binds a free port, shown in **Status**. The bridge uses the socket recorded in the [handshake file](/developers/mcp-protocol#local-socket-and-handshake), so its config needs no port. @@ -26,19 +26,21 @@ The default HTTP port is **23508**. If it is taken, the server binds a free port | Setting | Default | Range | |---------|---------|-------| -| Port | 23508 | | +| Port | 23508 | 1,024 to 65,535 | | Default row limit | 500 | 1 to 500,000 | | Maximum row limit | 10,000 | 1 to 500,000 | | Query timeout | 30 seconds | 1 to 300 seconds | | Log MCP queries in history | on | | -A tool can ask for fewer rows or a shorter timeout, never for more than the maximum. Rows also stop at the [answer size limit](/developers/mcp-tools#answer-size), whatever the row limit. +A tool can ask for fewer rows or a shorter timeout, never for more than the maximum. Rows also stop at the [answer size limit](/developers/mcp-tools#answer-size), whatever the row limit. A port outside its range is not saved, and the section names the range. ## Connecting a client -Click **Connect a Client…** and pick **Claude Code**, **Claude Desktop**, **Cursor**, or **Zed**. Each shows numbered steps and a copyable snippet pointing at the bundled bridge. Paste it into the client's own config; TablePro does not write to other apps' files. +Click **Connect a Client…**, then **Install** on the client's row. Depending on the client, TablePro opens it to confirm, runs its own command, such as `claude mcp add`, or adds an entry to its settings file. Every entry starts the bundled bridge, so no token is written anywhere. The row reads **Connected** once the client calls in. -For VS Code, Cline, Continue, Windsurf, Antigravity, Goose, the HTTP transport, and a client that connects but lists no tools, see [MCP Clients](/integrations/mcp-clients). +Install edits other apps' settings files, and only TablePro's entry in them. The file as it was stays beside it as `.tablepro-backup` until the next write replaces it. **Remove…** takes the entry out the same way, and **Copy** gives you the command or the configuration to add by hand instead. + +[MCP Clients](/integrations/mcp-clients) lists every client with the file it uses and what each status means, plus the HTTP transport and what to do when a client lists no tools. ## Connection access @@ -95,8 +97,15 @@ Every request needs a token, including one from your own Mac. The server supplie **View Activity…** opens the **MCP Activity** window, also on **TablePro > MCP Activity…**. It has two sections: -- **Activity Log**: every authentication, tool call, resource read and query, with the token behind it, the category, the connection, and the outcome. Filter by time, category or token, search, and export the filtered view to CSV. Retained for 90 days. Statements are recorded as a SHA-256 digest, not as text. -- **Connected Clients**: clients that have called in the last five minutes, with the client name, the token, and when they were first and last seen. **Disconnect** revokes that client's token, so the client has to pair again. +- **Activity Log**: every authentication, tool call, resource read and query, with the client and token behind it, the category, the connection, and the outcome. **Client** is the name the client reports for itself; authentication and server rows have none. Filter by time, category, client or token, search, and export the filtered view to CSV. Retained for 90 days. Statements are recorded as a SHA-256 digest, not as text. +- **Connected Clients**: clients that have called in the last five minutes, by their app's name and logo where TablePro knows the client, with the token and when they were first and last seen. **Connect a Client…** on its toolbar opens the setup sheet. + +**Disconnect** in Connected Clients depends on how the client reaches the server: + +| Client | Disconnect | +|---|---| +| Holds its own token, from **Generate Token** or pairing | Revokes the token and cancels the requests it has in flight. The client has to pair again or be given a new token | +| Runs the bundled bridge | Cancels the requests it has in flight and revokes nothing, so it can send new ones at once. To stop it, remove TablePro from it in **Connect a Client…**, or turn off the server | ## Security model diff --git a/images/mcp-connect-client-dark.png b/images/mcp-connect-client-dark.png new file mode 100644 index 0000000..7d4514d Binary files /dev/null and b/images/mcp-connect-client-dark.png differ diff --git a/images/mcp-connect-client.png b/images/mcp-connect-client.png new file mode 100644 index 0000000..b16dd64 Binary files /dev/null and b/images/mcp-connect-client.png differ diff --git a/integrations/mcp-clients.mdx b/integrations/mcp-clients.mdx index 7a81be6..a0acb5b 100644 --- a/integrations/mcp-clients.mdx +++ b/integrations/mcp-clients.mdx @@ -1,83 +1,122 @@ --- title: MCP Clients -description: Connect Claude Desktop, Claude Code, Cursor, VS Code, Cline, Continue, Zed, Windsurf, Antigravity, Goose, and custom clients to TablePro +description: Set up 21 AI clients, from Claude Code and ChatGPT to Cursor, VS Code and Zed, to use your saved connections through TablePro --- -Paste one absolute path into your client's MCP config and stop there. `tablepro-mcp` ships inside the app bundle; it starts TablePro when nothing is running, finds the private socket, and carries the token, so none of those end up in the file. +Most clients take one click. Open **Settings > MCP**, click **Connect a Client…**, and click **Install** on the client's row. -```json -{ - "mcpServers": { - "tablepro": { - "command": "/Applications/TablePro.app/Contents/MacOS/tablepro-mcp" - } - } -} -``` + + Connect a Client sheet with clients under On This Mac and Other Clients, each row showing a status and a button, and the selected client's settings file and configuration underneath + Connect a Client sheet with clients under On This Mac and Other Clients, each row showing a status and a button, and the selected client's settings file and configuration underneath + -For an install outside `/Applications`, use your own bundle's path. **Connect a Client…** in **Settings > MCP** shows snippets with it filled in. +On macOS, every entry TablePro writes starts the bundled bridge, `tablepro-mcp`, from inside the app. The bridge launches TablePro when nothing is running, finds the private socket and carries the token, so the client's file holds no token and no port. -TablePro for Linux has no bridge. Its clients take an address and a token instead: see [TablePro for Linux](#tablepro-for-linux). +TablePro for Linux has no bridge. Its clients get an address and a token instead: see [TablePro for Linux](#tablepro-for-linux). -## Clients that take the JSON above +## Set up a client + + + + Turn on **Enable MCP Server** in **Settings > MCP**. While it is off, the sheet says so and clients you add cannot connect yet. + + + Click **Connect a Client…**. Clients found on this Mac are under **On This Mac**, the rest under **Other Clients**. The same button is on the toolbar of **Connected Clients** in the MCP Activity window. + + + Click **Install** on the client's row. **Install…**, with an ellipsis, opens the client to confirm the new server there; the row reads **Finish in** and the client's name until you do. + + + Select the row to see whether the client picks up the change at once or needs a new session, a reload or a restart. + + -Only the config file differs. + +The row reads **Connected** once the client calls the server. + -| 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** | +A client under **Other Clients** offers **Copy** only, since there is nothing on this Mac to install into. Select any row for its settings file, **Show in Finder**, and the command or configuration to paste by hand. -## Claude Code +## How each client is set up -```bash -claude mcp add tablepro -- /Applications/TablePro.app/Contents/MacOS/tablepro-mcp -``` +A row uses the first method that works on this Mac: the client's install link, its own command, or an edit of its settings file. **Copy** is always there as well. -The double dash separates Claude Code's flags from the command it runs. stdio is the default transport. Verify with `claude mcp list`. +| Client | Install | Settings file | Takes effect | +|---|---|---|---| +| Claude Desktop | Edits the file | `~/Library/Application Support/Claude/claude_desktop_config.json` | Quit and reopen | +| Claude Code | Runs `claude mcp add --scope user` | `~/.claude.json`, read only | New session | +| ChatGPT | Runs `codex mcp add`, else edits the file | `~/.codex/config.toml` | Quit and reopen | +| Codex CLI | Runs `codex mcp add`, else edits the file | `~/.codex/config.toml` | New session | +| ChatGPT Classic | Cannot connect | None | None | +| Cursor | Opens Cursor to confirm, else edits the file | `~/.cursor/mcp.json` | At once | +| Visual Studio Code | Opens VS Code to confirm, else edits the file | `~/Library/Application Support/Code/User/mcp.json` | At once | +| Visual Studio Code - Insiders | Opens VS Code - Insiders to confirm, else edits the file | `~/Library/Application Support/Code - Insiders/User/mcp.json` | At once | +| Devin Desktop | Edits the file | `~/.config/devin/mcp_config.json` | Reload | +| Zed | Edits the file | `~/.config/zed/settings.json` | At once | +| Gemini CLI | Runs `gemini mcp add --scope user`, else edits the file | `~/.gemini/settings.json` | New session | +| GitHub Copilot CLI | Edits the file | `~/.copilot/mcp-config.json` | New session | +| opencode | Runs `opencode mcp add --global` | `~/.config/opencode/opencode.json`, read only | New session | +| Cline | Edits the file | `~/.cline/data/settings/cline_mcp_settings.json` | At once | +| Goose | Opens Goose to confirm | `~/.config/goose/config.yaml`, not read | Quit and reopen | +| LM Studio | Opens LM Studio to confirm, else edits the file | `~/.lmstudio/mcp.json` | At once | +| Kiro | Edits the file | `~/.kiro/settings/mcp.json` | At once | +| Warp | Edits the file | `~/.warp/.mcp.json` | At once | +| Junie | Edits the file | `~/.junie/mcp/mcp.json` | New session | +| JetBrains AI Assistant | Copy only | None | Quit and reopen | +| Raycast | Opens Raycast to confirm | None | At once | -## VS code +A read-only file is one the client's own command manages: TablePro reads it for the status and never writes it. A client with no settings file TablePro reads never shows **Set up**; it reads **Connected** once it calls the server. -Native MCP support arrived in 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`: +`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `COPILOT_HOME`, `CLINE_DIR` and `XDG_CONFIG_HOME` move these files only when they are in TablePro's own environment. An app opened from the Dock or Finder does not get them from your shell profile, so a client whose folder you moved that way needs **Copy**. -```json -{ - "servers": { - "tablepro": { - "type": "stdio", - "command": "/Applications/TablePro.app/Contents/MacOS/tablepro-mcp" - } - } -} -``` +### ChatGPT and Codex CLI + +Both read `~/.codex/config.toml`, so installing one sets up both, and both rows read **Connected** when either one connects. ChatGPT Classic reaches MCP servers only from OpenAI's cloud, never from your Mac. Its row gives that reason and has no button; set up ChatGPT instead. -Open Copilot Chat in agent mode and confirm the TablePro tools appear in the tools picker. +## What the status means -## Continue +| Status | Meaning | Button | +|---|---|---| +| **Not found** | The client is not on this Mac | **Copy** | +| No status | The client is on this Mac without TablePro | **Install** | +| **Set up** | The entry starts this copy of TablePro | None | +| **Connected** | The client called the server in the last five minutes. A client that connects while the list is open reads **Connected just now** for a minute | None | +| **Turned off** | The entry is there, but turned off in the client's own MCP settings | None. Turn it on in the client | +| **Set up with a token** | The entry reaches the HTTP server with a token from **Settings > MCP > Authentication** | None. TablePro keeps it, with the token's limits. To use the bridge instead, remove it, then install | +| **TablePro moved** | The entry starts a `tablepro-mcp` that is no longer there | **Update** | +| **Uses another copy** | The entry starts a different copy of TablePro, such as a beta in another folder | **Update** | +| **One project only** | Claude Code has TablePro in one project's settings only | **Install** adds it for every project | +| **Old setup in a project** | Claude Code has TablePro for every project, but one project has its own entry for a copy that is gone or different, and that one wins there | None. Remove TablePro from that project's settings | +| **Can't read settings** | The settings file is not valid, or names a key twice | **Copy** | -Continue reads MCP configs from `.continue/mcpServers/` in your workspace. Create `.continue/mcpServers/tablepro.yaml`: +**Update** edits the settings file where TablePro may write it, and otherwise runs the client's command; it never uses the install link. In the file it rewrites only the keys TablePro sets, so a value you added to the entry, such as an `env` entry, stays. A client's command replaces the whole entry. -```yaml -mcpServers: - - name: tablepro - type: stdio - command: /Applications/TablePro.app/Contents/MacOS/tablepro-mcp -``` +## What TablePro writes -Reload Continue's config from the gear menu. +Install, Update and Remove change one thing in the client's settings file: the `tablepro` entry, or for Codex and ChatGPT the `[mcp_servers.tablepro]` table. Other servers, comments, key order and indentation stay as they were. -## Zed +- Before TablePro replaces a file, the file as it was goes beside it as `.tablepro-backup`, such as `~/.cursor/mcp.json.tablepro-backup`. The next write replaces it. To undo a change, rename the backup over the file. +- A settings file that does not exist yet is created with mode `0600`, and the folders above it as needed. +- A settings file that is a symbolic link is written through, at the file it points to. +- A file TablePro cannot parse, one that names a key twice, and a Codex file that defines `tablepro` other than as a `[mcp_servers.tablepro]` table are not touched. The row says why, and **Copy** still works. -Zed keys MCP servers under `context_servers` (not `mcpServers`) in `~/.config/zed/settings.json`: +## Remove TablePro from a client + +Select the client's row and click **Remove…**, or press `Delete`, then confirm. Claude Code, Codex CLI, ChatGPT and Gemini CLI are removed through their own command where TablePro finds it. The rest lose the `tablepro` entry from their settings file, with the backup kept. + +Goose, opencode, Raycast and JetBrains AI Assistant have no **Remove**. Remove TablePro in the client itself. + +## Set up a client by hand + +Right-click a row and choose **Copy Command** or **Copy Configuration**. Both carry this copy's bridge path, and the command quotes it where it has a space. + +A client that is not in the list takes the bridge as a command: ```json { - "context_servers": { + "mcpServers": { "tablepro": { "command": "/Applications/TablePro.app/Contents/MacOS/tablepro-mcp" } @@ -85,30 +124,19 @@ Zed keys MCP servers under `context_servers` (not `mcpServers`) in `~/.config/ze } ``` -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. +For an install outside `/Applications`, use your own bundle's path. -## Goose +For Claude Code, from Terminal: -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 -extensions: - tablepro: - type: stdio - cmd: /Applications/TablePro.app/Contents/MacOS/tablepro-mcp - enabled: true - timeout: 300 +```bash +claude mcp add --scope user tablepro -- /Applications/TablePro.app/Contents/MacOS/tablepro-mcp ``` -Run `goose session` and ask for the tool list to confirm. - -## Setup snippets in TablePro - -Click **Connect a Client…** in **Settings > MCP**. The sheet covers Claude Desktop, Claude Code, Cursor, and Zed, with numbered steps and copyable snippets that already carry the right binary path for your install. +`--scope user` adds the server to every project. Without it, Claude Code adds it to the current project only, and the row reads **One project only**. The double dash separates Claude Code's flags from the command it runs. Verify with `claude mcp list`. ## What the config leaves out -TablePro does not have to be open first, but **Enable MCP Server** has to be on. Finding no trusted handshake, the bridge runs `open -g tablepro://integrations/start-mcp` and polls for one every 200ms for up to 10 seconds. With the toggle off, TablePro refuses the start and the bridge exits with that error at once. A TablePro started that way stays out of the Dock, the app switcher and the menu bar until it has a window to show; open the app yourself and it behaves normally for the rest of that run. +TablePro does not have to be open first, but **Enable MCP Server** has to be on. Finding no trusted handshake, the bridge runs `open -g tablepro://integrations/start-mcp` and polls for one every 200ms for up to 10 seconds. With the toggle off, or a server that fails to start, TablePro writes down its refusal and the bridge exits with the matching error at once. A TablePro started that way stays out of the Dock, the app switcher and the menu bar until it has a window to show; open the app yourself and it behaves normally for the rest of that run. The token is not yours to manage either. Each server start mints one named `__stdio_bridge__`, writes it into the handshake file, and rotates it 15 minutes before its one-hour expiry. It is **Read & Write**, so an agent on the bridge can read and write but cannot call `confirm_destructive_operation`. @@ -122,38 +150,53 @@ For a narrower scope than `readWrite`, or a connection allowlist, use the [HTTP ## TablePro for Linux -TablePro for Linux has no `tablepro-mcp` bridge. A client reaches its server over HTTP on `127.0.0.1` with an access token, and the server runs only while TablePro is open. - -1. Turn on **Preferences > MCP > Enable MCP Server**. -2. Under **Client Setup**, click **Copy Address**, then **Copy Access Token**. -3. Give both to the client. - -Claude Code: +The server runs only while TablePro is open, and answers HTTP on `127.0.0.1`. Each client entry holds the address and an `Authorization` header with the access token, so it works without a bridge. + + + + Turn on **Preferences > MCP > Enable MCP Server**. + + + Under **Clients**, click **Install** on the client's row. Click the row itself for its status, its configuration file, the setup to paste by hand, and **Remove…**. + + + The message after Install says whether to restart the client, start a new session or reload. Another message says when a client connects. + + + +The list holds the macOS clients except ChatGPT Classic and Raycast, with the ones set up or found on this computer first. + +- **Install** writes the entry into the client's file as described in [What TablePro writes](#what-tablepro-writes). The file holds the token, so TablePro leaves it readable only by you. +- Claude Code is installed through `claude mcp add --scope user --transport http`, which TablePro runs without a shell. The Flatpak never runs a client's command: there the row offers **Copy**, and you run the command in a terminal. +- Goose, opencode and JetBrains AI Assistant offer **Copy** only. +- Claude Desktop starts MCP servers only as local commands, so it cannot reach this server. Its row reads **Cannot connect to an address**. +- The setup shown on a client's page masks the token. **Copy** includes it. +- The server answers only programs running as your user. Any other connection gets `403` with "TablePro serves only programs of the user it runs as", whatever token it sends. + +| Status | Meaning | +|---|---| +| **Not set up** | The client's file has no TablePro entry | +| **Set up** | The entry has this address and the current token | +| **Set up with an old access token** | The token was regenerated since. **Update** writes the new one | +| **Set up for another address** | The entry points at another address, such as an old port. **Update** fixes it | +| **Set up for another server** | The entry starts a program instead of using this address. **Update** replaces it | +| **Set up for one project only** | Claude Code has TablePro in one project only. **Install** adds it for every project | +| **Set up but turned off in the client** | The entry is current but turned off in the client's own settings. Turn it on there | +| **Set up, but a project uses an old setup** | One Claude Code project has its own entry with an old address or token, and that one wins there. Remove TablePro from that project's settings | +| **Set up by hand in the client** | TablePro cannot read where this client keeps its servers | +| **Its configuration file cannot be read** | The file is not valid or not text. **Copy** the setup instead | + +**Regenerate Access Token…** works with the server on or off. Rows set up with the old token say so, and offer **Update**, while the server runs. The [Linux command](/linux/command-line#check-status) reads the new token itself. + +To set up a client by hand, use **Copy Address** and **Copy Authorization Header** under **Client Setup**. For Claude Code: ```bash -claude mcp add --transport http tablepro http://127.0.0.1:23508/mcp \ +claude mcp add --scope user --transport http tablepro http://127.0.0.1:23508/mcp \ --header "Authorization: Bearer tp_your_token_here" ``` `claude mcp list` should show it as connected. -Zed, in `~/.config/zed/settings.json`: - -```json -{ - "context_servers": { - "tablepro": { - "url": "http://127.0.0.1:23508/mcp", - "headers": { - "Authorization": "Bearer tp_your_token_here" - } - } - } -} -``` - -Claude Desktop starts MCP servers only as commands, so it needs a stdio-to-HTTP bridge of its own to reach this server. - ### Linux tools Start with `list_connections` and pass an id from its result as `connection_id`. Call `connect` for @@ -193,12 +236,11 @@ A filter has `column`, `operator`, and either `value` or `values`. Operators are null checks need neither. `logic` is `and` by default, or `or`. Each sort entry has `column` and an optional `direction`: `ascending` by default, or `descending`. -After **Regenerate Access Token…**, update the token in each MCP client. The -[Linux command](/linux/command-line#check-status) reads the replacement itself. - ## HTTP transport -Use HTTP when the client cannot spawn a local process. Mint a token in **Settings > MCP > Authentication** and point the client at the server: +Use HTTP when the client cannot start a local process. Click **Generate Token** in **Settings > MCP > Authentication**. The sheet that shows the new token has a **Client** menu: pick the client for its command or configuration with the address filled in, or **Other Client** for the address and header alone. The token is masked on screen, and the copy button includes it. + +For a client that is not in the menu: ```json { @@ -213,7 +255,7 @@ Use HTTP when the client cannot spawn a local process. Mint a token in **Setting } ``` -Replace `23508` with the port shown in **Settings > MCP**. Other clients use the same `url` plus `headers` shape, sometimes under `type: streamable-http`. Check the client's docs. +Replace `23508` with the port shown in **Settings > MCP**. When the configured port was taken and the server bound another, the sheet warns that the address changes when TablePro restarts. Other clients use the same `url` plus `headers` shape, sometimes under `type: streamable-http`. Check the client's docs. Three things change on this route. The server binds `127.0.0.1` over plain HTTP with no remote mode and no TLS, so a client on another machine needs an SSH port forward. `GET /mcp` answers `405`, so a client that opens a `GET` stream for notifications fails; notifications ride the response stream of the request they belong to. And `2025-11-25` and `2025-06-18` still work through the old `initialize` handshake and `Mcp-Session-Id`, while `2025-03-26` is refused. @@ -231,12 +273,16 @@ Clients see the full [tool catalog](/developers/mcp-tools), the [resources](/dev ## When it does not work -The bridge writes its failure to stderr and as a JSON-RPC error, so the message in the client names the layer that refused. +The bridge writes its failure to stderr and as a JSON-RPC error, so the message in the client names the layer that refused. A failed **Install**, **Update** or **Remove** shows its message under the client's name in **Connect a Client**. ### The TablePro MCP server is turned off **Enable MCP Server** is off in **Settings > MCP**. Turn it on, then relaunch the client. +### The TablePro MCP server is turned on but failed to start + +**Settings > MCP** shows why under **Status**. Fix that, click **Try Again**, then relaunch the client. + ### TablePro is not running The bridge could not launch the app, or got no trusted handshake within 10 seconds. Open TablePro and check that **Settings > MCP** shows the server running; if it does, toggle **Enable MCP Server** off and on, then relaunch the client. @@ -264,3 +310,23 @@ The bridge token is stale. The bridge re-reads the handshake and retries once on ### Rate limited (`-33010`) Five failed auth attempts inside 60 seconds triggered a 5-minute lockout for every client on this Mac. A request that sends no token is not a failed attempt. Wait it out, or restart TablePro. The other [rate limits](/developers/tokens#rate-limits) return the same code. + +### The … command stopped with exit code … + +The client's own command refused the change. Its output is under the message. Fix what it names, or copy the command and run it in Terminal. + +### … could not be read as valid settings, so TablePro left it unchanged + +The client's settings file is not valid JSON, JSON with comments, or TOML. Open it with **Show in Finder** and fix it, or paste the setup from **Copy Configuration** by hand. + +### … names the same key twice, so TablePro left it unchanged + +Two members of one object on the way to TablePro's entry share a name. Delete the duplicate, then click **Install** again. + +### TablePro serves only programs of the user it runs as + +TablePro for Linux answered `403`: the client runs as another user, or the server could not tell which user it runs as. Run the client as the user who runs TablePro. + +### TablePro is running from a disk image or a temporary location + +**Install** and **Update** are dimmed, because a client set up for that copy breaks once the disk image is ejected. Move TablePro to the Applications folder, open it from there, and install again. diff --git a/integrations/terminal.mdx b/integrations/terminal.mdx index 0968ede..992cf41 100644 --- a/integrations/terminal.mdx +++ b/integrations/terminal.mdx @@ -102,7 +102,7 @@ Table names accept letters, digits and underscores, with dots between parts such `tablepro status` checks the app, MCP server and pairing without starting the app or asking for approval. Add `--format json` for scripts. It exits 0 when ready, 1 when the app cannot be reached, and 3 when the server is off or the command is not paired. -Other commands that need the server start the app if needed. The MCP server must already be enabled in Settings. +Other commands that need the server start the app if needed. The MCP server must already be enabled in Settings; when it is enabled but fails to start, the command says so and exits 1. @@ -118,6 +118,8 @@ Other commands that need the server start the app if needed. The MCP server must An unattended command with no token exits 3. A rejected or expired token is removed and that run exits 3; run `tablepro pair` again. Pairing again stores a replacement and asks the server to revoke the previous token. If that fails, the command prints a warning; revoke the old token in Settings. +When TablePro cannot issue the token after you approve, the browser tab says it could not finish pairing, TablePro shows why, and the command exits 1. Run `tablepro pair` again once the cause is fixed. + `tablepro unpair` revokes the token and removes its Keychain copy. If the server cannot be reached, only the local copy is removed; revoke the remaining token in **Settings > MCP > Authentication**. If the server reports that it could not save the revocation, the local token stays for another attempt. These failures exit 1. ## Shell completion