Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions developers/mcp-protocol.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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 |
Expand All @@ -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.

Expand Down Expand Up @@ -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
{
Expand Down
13 changes: 12 additions & 1 deletion developers/pairing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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=<uuid>&state=<state>, or ?error=access_denied when the user says no.
// Step 3. Your callback receives ?code=<uuid>&state=<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<string> {
Expand Down Expand Up @@ -114,6 +115,10 @@ passes an extension a single launch parameter named `context`, as Raycast does.
| `context` | `?context={"code":"<uuid>","state":"<state>"}` | `?context={"error":"access_denied","error_description":"user_denied","state":"<state>"}` |
| absent (deprecated) | `?context={"code":"<uuid>"}` for `raycast://`, `?code=<uuid>` 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.
Expand Down Expand Up @@ -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.

Expand Down
5 changes: 3 additions & 2 deletions developers/tokens.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand All @@ -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.<name>`, `resource.read` |
Expand Down
25 changes: 17 additions & 8 deletions features/mcp.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,29 +16,31 @@ 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.

## Server configuration

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

Expand Down Expand Up @@ -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

Expand Down
Binary file added images/mcp-connect-client-dark.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/mcp-connect-client.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading