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”
• “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 Copilot
• Zed
• Any other MCP-compatible client

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

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

get-cron / get-job

Returns the full resource including configuration, status, execution history, and timing data. Requires the id parameter.

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.

Authentication

The MCP server authenticates using the same API token you use for the REST API. The token is passed via the RECURO_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.

Self-hosted setup

If you’re self-hosting Recuro, you can run the MCP server directly via Artisan:

{
  "mcpServers": {
    "recuro": {
      "command": "php",
      "args": ["artisan", "mcp:start", "recuro"],
      "cwd": "/path/to/your/recuro/src",
      "env": {
        "MCP_API_TOKEN": "your_token_here"
      }
    }
  }
}