Documentation Index
Fetch the complete documentation index at: https://docs.tablepro.app/llms.txt
Use this file to discover all available pages before exploring further.
Tokens
Every external request needs a bearer token. Tokens carry a scope, an optional connection allowlist, and an optional expiry. Tokens are stored hashed (SHA-256 + salt) at ~/Library/Application Support/TablePro/mcp-tokens.json with 0600 permissions. The plaintext is shown once at creation and never again.
Token shape
struct MCPAuthToken {
let id: UUID
var name: String
let prefix: String // First 8 chars of plaintext, e.g. "tp_a1b2c3"
let hashedToken: String // SHA-256 + salt of the plaintext
var permissions: TokenPermissions // readOnly, readWrite, fullAccess
var allowedConnectionIds: Set<UUID>? // nil means all connections
var expiresAt: Date? // nil means never
var isActive: Bool
let createdAt: Date
var lastUsedAt: Date?
}
prefix is shown in the token list so the user can identify a token without revealing the secret.
Scopes
| Scope | Read schema | SELECT | INSERT/UPDATE/DELETE | DROP/TRUNCATE | UI mutation |
|---|
readOnly | yes | yes | no | no | no |
readWrite | yes | yes | yes | no | yes |
fullAccess | yes | yes | yes | yes (with phrase) | yes |
open_connection_window, open_table_tab, focus_query_tab. These open windows and tabs in the running app.
DROP and TRUNCATE always require an explicit confirmation phrase via confirm_destructive_operation, even with fullAccess. There is no token scope that bypasses the phrase.
Connection allowlist
Each token can be limited to a subset of connections.
allowedConnectionIds = nil means all connections.allowedConnectionIds = { uuid1, uuid2 } means only those.
A request that targets a connection outside the allowlist returns 403 forbidden before any per-connection check runs.
External access combination
The effective permission is MIN(token.scope, connection.externalAccess).
| Token scope | Connection access | Effective |
|---|
readOnly | readWrite | readOnly |
readWrite | readOnly | readOnly |
fullAccess | readOnly | readOnly |
fullAccess | readWrite | readWrite (no destructive) |
fullAccess | blocked | denied |
| any | blocked | denied |
fullAccess token cannot mutate data on a readOnly connection. A token’s reach is bounded by both itself and the connection.
Creation
Tokens are created in three ways:
- Pairing flow (most common). See Pairing.
- Settings UI. Settings > Integrations > Authentication, then Generate Token. Pick name, scope, allowlist, expiry. The plaintext is shown once in a reveal sheet.
- AppleScript-style URL is not supported. Tokens are not exposed as a URL scheme action.
The plaintext format is tp_<base64url(32 bytes)>. The first 8 chars are the prefix.
Expiry
Optional. If set, the token stops authenticating at the expiry time. Expired requests return 401 unauthorized with message: "Token expired".
Recommended values:
readWrite and fullAccess for human-driven extensions: 90 days.readOnly for personal use: never.- CI or automation: 30 days, rotated.
Revocation
Settings > Integrations > Authentication lists all tokens with prefix, name, scope, allowlist, last-used time, and expiry. Each row has:
- Revoke: marks the token inactive. Stays in the list with status
Revoked. Cannot be reactivated.
- Delete: removes the row entirely.
A revoked token returns 401 unauthorized immediately. The MCP server invalidates any cached session for the token within one second.
After revoking a token used by an extension, the extension shows an “unauthorized” state on the next call. The user runs the pairing command again to mint a new token.
Audit log
Every authentication, every tool call, every resource read is recorded in ~/Library/Application Support/TablePro/mcp-audit.db with the token id (not the plaintext). The activity log view in Settings > Integrations > Activity Log shows:
| Field | Example |
|---|
| Timestamp | 2026-04-26 10:14:22 |
| Token | Raycast on macbook-pro (tp_a1b2c3) |
| Category | query, auth, access, admin |
| Action | execute_query, pair, revoke |
| Connection | Production (or -) |
| Outcome | success, denied, error |
Rate limits
Per-IP, on failed auth:
| Failures | Lockout |
|---|
| 2 | 1 second |
| 3 | 5 seconds |
| 4 | 30 seconds |
| 5+ | 5 minutes |
429 Too Many Requests.
What tokens cannot do
| Capability | State |
|---|
| Read connection passwords | no |
| Read SSH keys | no |
| Read license data | no |
| Read app settings | no |
Read local files outside ~/Library/Application Support/TablePro/ | no |
| Mutate Safe Mode rules | no |
| Mutate other tokens | no |
| Mutate connection records | no |
