@tidebase/mcp

@tidebase/mcp

MCP server for Tidebase — lets AI assistants (Claude Code, Claude Desktop, Cursor, or any MCP client) inspect agent runs, read checkpoints and state versions, resolve approval gates, and trigger recovery.

Tidebase is an open-source checkpoint layer for AI agents: wrap your steps, and failed runs resume from the last safe point — in your own Postgres, without moving execution into a new runtime.

Install

Claude Code:

claude mcp add tidebase -e TIDEBASE_URL=http://localhost:7373 -- npx -y @tidebase/mcp

Claude Desktop / generic MCP client config:

{
  "mcpServers": {
    "tidebase": {
      "command": "npx",
      "args": ["-y", "@tidebase/mcp"],
      "env": { "TIDEBASE_URL": "http://localhost:7373" }
    }
  }
}

Tools

Tool	What it does
tidebase_health	Verify the server is reachable
tidebase_list_runs	List the 100 most recent runs with status
tidebase_get_run	Full run detail: steps, resume contracts, state, gates, child runs, events, usage
tidebase_create_run	Register a run (your app still invokes the workflow)
tidebase_get_state_versions	Versioned state history; snapshots are labeled versions
tidebase_resolve_gate	Approve/reject/cancel a pending gate (requires resolveToken; exactly-once)
tidebase_trigger_recovery	Dispatch the run's recovery webhook to resume it

What this enables

• "Why did run run_abc stop?" → the assistant reads the run detail and explains which step failed and how it was classified (failed_retryable / manual_review / failed).
• "Is it safe to rerun?" → the assistant reads the step resume contracts and answers from the recorded side effects and idempotency keys.
• "Approve the pending gate on the report run" → resolved exactly once, with an audit actor.
• "Resume everything that died overnight" → list failed runs, trigger recovery for each.

Configuration

Env var	Default	Meaning
TIDEBASE_URL	http://localhost:7373	Base URL of your Tidebase server

Note: Tidebase's alpha has no API authentication; only point this at trusted local/self-hosted servers.

Develop

npm install
npm run build
TIDEBASE_URL=http://localhost:7373 node dist/index.js