@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