@fliq/mcp

A Model Context Protocol (MCP) server for Fliq — the Postgres-native HTTP job scheduler.

It lets any MCP-capable AI agent (Claude Desktop, Claude Code, Cursor, custom agents) schedule and manage HTTP jobs, recurring cron schedules, rate-limited buffers, and alert channels — and inspect usage and billing — in natural language. Under the hood every tool is a single call to the Fliq REST API (https://api.fliq.sh) authenticated with one of your fliq_sk_* API tokens.

• Durable one-off + cron HTTP jobs with retries, backoff and crash recovery.
• Buffers: outbound rate-limiting so an agent can hammer a 429-prone API (Stripe, Shopify, an LLM) without getting throttled.
• Replay failed jobs/items, get per-attempt history, watch usage and balance.

Distributed over stdio — add it to your agent in one config line.

Get an API token

In the Fliq dashboard → Settings → API tokens, create a token. It looks like fliq_sk_… and is shown once. That token is the only credential the server needs.

Install / run

No install needed — run it on demand with npx:

FLIQ_API_TOKEN=fliq_sk_xxx npx @fliq/mcp

Or install globally:

npm install -g @fliq/mcp
FLIQ_API_TOKEN=fliq_sk_xxx fliq-mcp

It speaks MCP over stdio — you normally don't run it by hand; your MCP client launches it (see the config blocks below).

Configuration (environment)

Variable	Required	Default	Description
FLIQ_API_TOKEN	yes	—	Your fliq_sk_* API token.
FLIQ_API_URL	no	https://api.fliq.sh	Override the API base URL (e.g. self-hosted).

Client configuration

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json), then restart Claude:

{
  "mcpServers": {
    "fliq": {
      "command": "npx",
      "args": ["-y", "@fliq/mcp"],
      "env": {
        "FLIQ_API_TOKEN": "fliq_sk_xxx"
      }
    }
  }
}

Claude Code

claude mcp add fliq \
  --env FLIQ_API_TOKEN=fliq_sk_xxx \
  -- npx -y @fliq/mcp

(Add --scope user to make it available in every project. To point at a self-hosted Fliq, also pass --env FLIQ_API_URL=https://api.your-host.)

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "fliq": {
      "command": "npx",
      "args": ["-y", "@fliq/mcp"],
      "env": {
        "FLIQ_API_TOKEN": "fliq_sk_xxx"
      }
    }
  }
}

Tools

Each tool is one REST call with a typed (zod) input schema. Non-2xx responses become clear tool errors — e.g. 402 = out of credits, 409 = not in a replayable state, 401 = bad/revoked token.

Jobs

Tool	Description
schedule_job	Schedule a one-off HTTP job at an RFC3339 time, with retries.
get_job	Fetch a job by id (status + execution timestamps).
list_jobs	List jobs, optionally filtered by status; cursor-paginated.
cancel_job	Cancel a pending job.
replay_job	Re-run a permanently-failed job as a fresh pending job.
list_job_attempts	List every execution attempt (status code, error, timing).

Schedules (cron)

Tool	Description
create_schedule	Create a recurring schedule from a cron expression.
list_schedules	List schedules; cursor-paginated.
pause_schedule	Pause a schedule (stops firing).
resume_schedule	Resume a paused schedule.
delete_schedule	Permanently delete a schedule.

Buffers (outbound rate limiting)

Tool	Description
create_buffer	Create a rate-limited outbound queue (deliveries/sec).
list_buffers	List buffers; cursor-paginated.
push_buffer_item	Enqueue one item; drains respecting the rate limit.
buffer_stats	Aggregated status breakdown + success rate.
replay_buffer_item	Re-run a failed item onto the tail of the buffer.

Alerts

Tool	Description
list_alert_channels	List channels notified on permanent failures.
create_alert_channel	Create a webhook or slack alert channel.

Analytics & billing

Tool	Description
job_stats	Execution totals, success rate, avg/p95 duration over N days.
usage_stats	Daily job + buffer execution buckets, balance, plan.
get_balance	Current credit balance, plan, daily limit.

How billing works

Each execution attempt (including retries) costs one credit. schedule_job and replay_job pass the same credit gate; if you're out of credits they return a 402 tool error. Use get_balance / usage_stats to keep an eye on it.

Development

npm install
npm run build      # tsc → dist/index.js (with shebang, executable)
npm start          # run the built server (needs FLIQ_API_TOKEN)

Source layout:

• src/client.ts — thin fetch wrapper: attaches the bearer token, builds query strings, maps non-2xx to status-aware FliqApiErrors.
• src/index.ts — the MCP server: reads config from env, registers all tools.

License

MIT