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
10 changes: 7 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,10 +52,14 @@ Copy `.env.example` to `.env` for local development.

### Connection slots and session lifetime

The concurrent-connection limit (20, per API token, `src/ratelimit/index.ts`) is acquired on session creation and released on `DELETE`, transport close, or by the idle sweeper. Two rules keep the pool from silting up, both covered by `tests/connectionSlots.spec.ts`:
The connection limit (20, per API token, `src/ratelimit/index.ts`) is acquired on session creation and released on `DELETE`, transport close, eviction, or by the idle sweeper (10 minutes). It caps how many sessions of one token may **work** at once, not how many it has abandoned:

- An initialize request that never produces a session (malformed body, aborted client) releases its slot from `res.on('close')`. Without that the slot is unreachable — the transport never opened, so `onclose` never fires, and the sweeper never sees a session that was never registered.
- A session that initialized but never made a call is reclaimed after **30 s** (`unusedSessionTimeoutMs`) instead of the ordinary 10-minute idle timeout. Reconnect-happy clients leave these behind by the dozen; each one holds a slot.
- When the pool is full, `evictIdlestSession()` closes the session of the **same token** that has been idle longest and has no POST in flight (`inFlight`). Only if all 20 are mid-request does the client get `429`. A client returning to an evicted session gets `404` and must re-initialize (MCP spec). A GET stream does not count as in flight. Coverage: `tests/sessionEviction.spec.ts`, which replays the 15 November 2026 incident.
- An initialize request that never produces a session (malformed body, aborted client) releases its slot from `res.on('close')`. Without that the slot is unreachable — the transport never opened, so `onclose` never fires, and nothing can evict a session that was never registered. Coverage: `tests/connectionSlots.spec.ts`.

ChatGPT opens a new session for every tool call (initialize, `notifications/initialized`, a GET it aborts after a millisecond, one `tools/call`) and never sends `DELETE`. Twice the response was to treat the symptom: raising the limit from 5 to 20, then a 30-second timeout for "unused" sessions, which never fired because the `initialized` notification and the GET already counted as use. Do not raise the limit or add per-client timeouts again; eviction is what makes the pool independent of how many sessions a client leaves behind.

`Session initialized`, `Session evicted` and every 429 that knows its token log the token fingerprint, so a burst can be attributed to a tenant. All 429s are counted in `mcp_rate_limit_exceeded_total{type}`, evictions in `mcp_sessions_evicted_total`.

Client IP for rate limiting comes from the **rightmost** `X-Forwarded-For` entry — the hop our own proxy appended. The leftmost entry is client-supplied and would let a caller pick its own rate-limit bucket. `docker-compose.yml` additionally has Caddy overwrite the header rather than append to it.

Expand Down
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,7 @@ The security characteristics differ significantly between transport modes:
| **Network exposure** | None (local process) | TCP port, **no auth** | TCP port, Bearer auth |
| **Authentication** | Not needed (local) | None | Bearer token or OAuth 2.0, validated against SeaTable |
| **Rate limiting** | None | None | Per-token, per-IP, global |
| **Connection limits** | N/A | None | 20 concurrent sessions per token |
| **Connection limits** | N/A | None | 20 sessions per token; the longest-idle one makes room |
| **Data scope** | All configured bases | All configured bases | One base per client token |

> **⚠️ Warning:** Selfhosted HTTP mode (`--sse` / `--http`) has **no authentication**. Anyone who can reach the port gets full access to all configured bases, including write and delete operations. Only run it in trusted networks (localhost, Docker-internal) or behind a reverse proxy that handles authentication. For untrusted networks, use **managed mode** instead.
Expand All @@ -226,7 +226,7 @@ The security characteristics differ significantly between transport modes:

SeaTable's own API gateway enforces rate limits **per base** (default: 500 requests/minute per `base_uuid`) and **per organization** (monthly quota). These limits apply regardless of whether requests come from the MCP server, the web UI, or direct API calls. The MCP server does not duplicate these limits — instead, it retries automatically with exponential backoff when SeaTable returns `429 Too Many Requests`.

In **managed mode**, the MCP server adds its own rate limits to protect the server process itself (not the SeaTable backend): 60 req/min per token, 120/min per IP, 30/min for new session creation, and 20 concurrent connections per token.
In **managed mode**, the MCP server adds its own rate limits to protect the server process itself (not the SeaTable backend): 60 req/min per token, 120/min per IP, 30/min for new session creation, and 20 sessions per token. When a token's 20 sessions are all taken, the one idle longest is closed to make room (a client returning to it gets `404` and initializes again, as the MCP spec requires); only if all 20 are in the middle of a request is the new one rejected with `429`. ChatGPT opens a new session for every tool call and never closes one, so it relies on this.

### Input Validation

Expand Down Expand Up @@ -279,7 +279,8 @@ Available metrics:
| `mcp_tool_calls_by_tool_total{tool}` | Counter | Total calls per tool (regardless of outcome) |
| `mcp_tool_duration_seconds{tool}` | Histogram | Tool execution time |
| `mcp_http_requests_total{method, status}` | Counter | HTTP requests by method and status code |
| `mcp_rate_limit_exceeded_total{type}` | Counter | Rate limit rejections (global/per_ip/per_token) |
| `mcp_rate_limit_exceeded_total{type}` | Counter | Rate limit rejections (`global`, `per_ip`, `per_token`, `pre_auth`, `oauth`, `connections`) |
| `mcp_sessions_evicted_total` | Counter | Idle sessions closed to make room for a new session of the same token |
| `mcp_auth_validations_total{result}` | Counter | Auth validations (success/failure/cache_hit) |
| `mcp_sql_failures_total{tool, reason}` | Counter | Failed `query_sql`/`execute_sql` calls (e.g. `subquery`, `join`, `wrong_statement_update`, `unknown_name`, `invalid_value`, `seatable_error`) |
| `mcp_active_sessions` | Gauge | Currently active HTTP sessions |
Expand Down
2 changes: 1 addition & 1 deletion docs/openai-tunnel.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ Done by someone in the workspace with developer mode access and *Tunnels Read +

## Open points

- Not yet verified end to end: whether `tunnel-client` passes the `mcp-session-id` header through correctly. The server is stateful and reclaims unused sessions after 30 seconds; problems would show up in the `seatable-mcp` logs on the first connection.
- Not yet verified end to end: whether `tunnel-client` passes the `mcp-session-id` header through correctly. The server is stateful; idle sessions are closed after 10 minutes or earlier when a token's 20 slots are full; problems would show up in the `seatable-mcp` logs on the first connection.
- The `tunnel-client` image's entrypoint (`tunnel-client run`) and environment variable names are taken from OpenAI's repository and documentation, not from a running deployment.

Update this file once a deployment has confirmed or corrected these points.
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@seatable/mcp-seatable",
"version": "1.9.6",
"version": "1.9.7",
"type": "module",
"license": "MIT",
"mcpName": "io.github.seatable/seatable",
Expand Down
15 changes: 15 additions & 0 deletions src/fingerprint.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
import { createHash } from 'node:crypto'

function fingerprint(value: string): string {
return createHash('sha256').update(value).digest('hex').slice(0, 12)
}

/** Session IDs are credentials-adjacent routing values — log a fingerprint, never the value. */
export function sessionFingerprint(sessionId: string): string {
return fingerprint(sessionId)
}

/** Same rule for API tokens: enough to correlate one tenant's lines, never the credential. */
export function tokenFingerprint(apiToken: string): string {
return fingerprint(apiToken)
}
Loading
Loading