DOCS · AGENTS

MCP Integration

Connect MCP clients to the remote scheduling server, and point schedules at tools on your own MCP servers.

Recurrence Cloud speaks MCP in both directions: it is a remote MCP server agents can call to manage schedules, and an MCP client that invokes tools on your MCP servers when a schedule fires.

A. The remote MCP server

A stateless Streamable-HTTP JSON-RPC 2.0 endpoint:

POST https://api.recurrence.cloud/api/mcp
Authorization: Bearer <agent API key>   (or X-API-Key)

Handshake & discovery

# 1. initialize — echoes your protocolVersion (built on 2025-06-18)
curl -X POST https://api.recurrence.cloud/api/mcp \
  -H "Authorization: Bearer $AGENT_KEY" -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
        "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "my-agent", "version": "1.0" } } }'

# 2. tools/list — the 17 scheduling tools
# 3. tools/call — e.g. whoami
curl -X POST https://api.recurrence.cloud/api/mcp \
  -H "Authorization: Bearer $AGENT_KEY" -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "whoami", "arguments": {} } }'

The 17 tools

Group Tools
Orientation whoami, list_environments, list_apps
Schedules list_schedules, get_schedule, create_schedule, update_schedule, delete_schedule, test_schedule_due
Delivery targets list_webhooks, create_webhook
Events list_events, add_event
Agent servers register_mcp_server, list_mcp_servers, discover_mcp_tools
Composite create_scheduled_task — schedule + target + first event in one call

All tools are tenant-scoped to the key’s organization; usage failures return MCP isError results; every call is audited.

Prompt → schedule

With recurrenceText, agents never invent cron syntax:

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": { "name": "create_scheduled_task", "arguments": {
    "name": "status-check", "appId": "…",
    "recurrenceText": "every 15 minutes", "timezone": "UTC",
    "target": { "url": "https://api.yourcompany.dev/check" },
    "firstEvent": { "subject": "status-check", "payload": { "type": "ops.status" } } } } }

Client configuration

For HTTP-capable MCP clients (Cursor, editors, mcp-remote):

{ "mcpServers": { "recurrence-cloud": {
    "url": "https://api.recurrence.cloud/api/mcp",
    "headers": { "X-API-Key": "<agent api key>" } } } }

B. Schedules that fire MCP tools

  1. Register your MCP server — POST /api/v1/mcp-servers { "url", "name"?, "headers"?, "timeoutMs"? }.
  2. Discover its tools — GET /api/v1/mcp-servers/:id/tools, or probe ad-hoc with POST /api/v1/mcp-servers/discover. Deep-verify a tool with POST /api/v1/mcp-servers/:id/verify.
  3. Point a schedule at a tool — in the schedule body (or with-webhook), replace the webhook with:
"mcp": { "mcpServerId": "…", "toolName": "reports.generate", "arguments": { "scope": "ops" } }

Each fire becomes a tools/call on your server with the batch’s events merged in — so an agent-reachable server can act on schedule even with no session alive.

Governance

  • Tenant isolation in the shared executor (MCP and REST in lockstep)
  • Full audit trail: GET /api/activity/agent-activity
  • Rate limiting per agent key
  • test_schedule_due lets agents preview when their drafted recurrence fires

Next: Agent protocols — A2A tasks and UCP contexts.