MCP Server

Recuro ships an MCP (Model Context Protocol) server that lets AI agents create crons, queue jobs, and inspect executions — directly from your editor or chat client.

Setup

1. Get your API token

Go to Settings → API in the Recuro dashboard and copy your token.

2. Add the server to your MCP client

Add this to your MCP configuration file (e.g. mcp.json, claude_desktop_config.json, or your editor’s MCP settings):

{
  "mcpServers": {
    "recuro": {
      "command": "npx",
      "args": ["-y", "recuro-mcp"],
      "env": {
        "RECURO_API_TOKEN": "your_token_here"
      }
    }
  }
}

Replace your_token_here with your actual API token.

3. Start using it

Your AI agent will now see Recuro’s tools and can manage your crons and jobs through natural language.

Example prompts:

“Create a cron that pings https://api.example.com/health every 5 minutes”
“List all my active crons”
“Queue a job to POST to https://api.example.com/sync on the webhooks queue”
“Show me the details of cron 42”
“Pause the health-check cron”
“Delete job 123”

Compatible clients

The MCP server works with any client that supports the Model Context Protocol:

Claude Code (CLI)
Claude Desktop
Cursor
Windsurf
VS Code (GitHub Copilot)
Zed
Any other MCP-compatible client

Client configuration paths

Client	Config file
Claude Code	`.mcp.json` in project root, or `~/.claude/mcp.json` globally
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
Cursor	`.cursor/mcp.json` in project root
VS Code	`.vscode/mcp.json` in project root

Available tools

Cron tools

Tool	Description
`list-crons`	List crons with optional filters (active/paused) and search by name or URL
`create-cron`	Create a new recurring cron job
`get-cron`	Get full details of a cron by ID
`update-cron`	Update any fields on an existing cron
`delete-cron`	Permanently delete a cron and its history

Job tools

Tool	Description
`list-jobs`	List jobs with optional status filter, queue filter, and search
`create-job`	Create a one-off job in a named queue (auto-created if new)
`get-job`	Get full details of a job including run results
`delete-job`	Permanently delete a job and its run history

Tool reference

create-cron

Create a recurring HTTP request on a cron schedule.

Parameters:

Field	Type	Required	Description
`name`	string	Yes	Display name for the cron
`url`	string	Yes	Target URL to call
`cron_expression`	string	Yes	Standard 5-field cron expression (e.g. `/5 * * *`)
`method`	string	No	HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. Defaults to `GET`
`headers`	object	No	Key-value HTTP headers
`payload`	string	No	Raw request body
`callback_url`	string	No	URL called after each execution completes
`timeout_seconds`	integer	No	Timeout in seconds (1–300). Defaults to `30`
`alert_threshold`	integer	No	Alert after N consecutive failures: `1`, `2`, or `3`
`is_active`	boolean	No	Whether the cron starts active. Defaults to `true`

Example response:

{
  "id": 1,
  "name": "Health Check",
  "url": "https://api.example.com/health",
  "method": "GET",
  "cron_expression": "*/5 * * * *",
  "is_active": true,
  "next_run_at": "2025-01-15T10:05:00+00:00"
}

update-cron

Update an existing cron. Only the fields you provide are changed — everything else stays the same.

Parameters:

Field	Type	Required	Description
`id`	integer	Yes	The cron ID to update
All fields from `create-cron`	—	No	Any field you want to change

create-job

Queue a one-off HTTP request. The queue is auto-created if it doesn’t exist.

Parameters:

Field	Type	Required	Description
`queue`	string	Yes	Queue name (auto-created if new)
`url`	string	Yes	Target URL to call
`method`	string	No	HTTP method. Defaults to `POST`
`headers`	object	No	Key-value HTTP headers
`payload`	object	No	JSON request body
`callback_url`	string	No	URL called after the job completes
`delay`	integer	No	Seconds to wait before executing (0–86400). Defaults to `0`

Example response:

{
  "id": 42,
  "queue_id": 3,
  "queue_name": "webhooks",
  "url": "https://api.example.com/sync",
  "method": "POST",
  "status": "pending",
  "scheduled_at": "2025-01-15T10:00:00+00:00"
}

get-cron

Returns the full cron configuration including status, execution timing, and alert state.

Parameters:

Field	Type	Required	Description
`id`	integer	Yes	The cron ID

Example response:

{
  "id": 1,
  "name": "Health Check",
  "url": "https://api.example.com/health",
  "method": "GET",
  "headers": null,
  "payload": null,
  "callback_url": null,
  "cron_expression": "*/5 * * * *",
  "timeout_seconds": 30,
  "alert_threshold": 2,
  "consecutive_failures": 0,
  "is_active": true,
  "is_alerted": false,
  "last_run_at": "2025-01-15T10:00:00+00:00",
  "next_run_at": "2025-01-15T10:05:00+00:00",
  "last_status": "completed",
  "last_response": null,
  "created_at": "2025-01-10T08:30:00+00:00"
}

get-job

Returns the full job details including queue info and run results (HTTP response, duration, errors).

Parameters:

Field	Type	Required	Description
`id`	integer	Yes	The job ID

Example response:

{
  "id": 42,
  "url": "https://api.example.com/sync",
  "method": "POST",
  "headers": { "Authorization": "Bearer token" },
  "payload": { "event": "user.created" },
  "callback_url": null,
  "queue": "webhooks",
  "queue_id": 3,
  "status": "completed",
  "final_status": "success",
  "attempt_number": 1,
  "is_retry": false,
  "delay_seconds": 0,
  "scheduled_at": "2025-01-15T10:00:00+00:00",
  "created_at": "2025-01-15T10:00:00+00:00",
  "run": {
    "response_status": 200,
    "response_body": "{\"ok\":true}",
    "duration_ms": 142,
    "error_message": null,
    "started_at": "2025-01-15T10:00:01+00:00",
    "executed_at": "2025-01-15T10:00:01+00:00"
  }
}

list-crons / list-jobs

Returns a paginated list. Optional parameters:

Field	Type	Description
`filter`	string	Filter by status. Crons: `active`, `paused`, `all`. Jobs: `pending`, `processing`, `completed`, `failed`, `retrying`
`search`	string	Search by name (crons) or URL (jobs)
`queue_id`	integer	Jobs only — filter by queue
`page`	integer	Page number

delete-cron / delete-job

Permanently deletes the resource and all associated history. Requires the id parameter. Returns { "deleted": true, "id": <id> }.

Authentication

The MCP server authenticates using the same API token you use for the REST API. The token is passed via the MCP_API_TOKEN environment variable in your MCP configuration.

All operations are scoped to your team — the MCP server can only see and modify resources belonging to your current team.

How it works

The MCP client passes your token as the MCP_API_TOKEN environment variable
Recuro hashes the token (SHA-256) and looks up the matching user
All tool calls run in that user’s team context
Resources from other teams are never accessible

Generating a token

Log in to the Recuro dashboard
Go to Settings → API
Click Generate Token (or Regenerate to replace an existing one)
Copy the token — it’s only shown once

The same token works for both the REST API and the MCP server.