MCP INTEGRATION: GIVE YOUR AI AGENT A SCHEDULING PRIMITIVE

MCP integration: give your AI agent a scheduling primitive

Add scheduling tools to any AI agent via the Model Context Protocol. Connect to Recurrence Cloud's remote MCP server, list 17 scheduling tools, and let agents create, manage, and receive scheduled tasks.

MCP gave agents a standard way to call tools now. Recurrence Cloud’s MCP integration gives them a standard way to act later — a remote MCP server exposing the full scheduling lifecycle as 17 tools over plain JSON-RPC. Point any MCP client at it, and your agent can create a cron schedule by itself, decide what the delivery carries, and come back to it a week later. Where most scheduling setups mean “someone wrote a cron entry in a config,” an agent with scheduling tools means plans that outlive the session.

Step 1: The handshake, in three JSON-RPC calls

Recurrence Cloud’s MCP server is stateless and boring on purpose: POST JSON-RPC 2.0 to one endpoint, authenticate with your agent API key.

1. Initialize — the server echoes your protocol version, so it stays compatible across client revisions (built on 2025-06-18):

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

The response carries capabilities.tools, plus serverInfo (recurrence-cloud, Recurrence Cloud Scheduling) and usage instructions your agent can read to orient itself.

2. List tools — 17 of them, grouped by job:

curl -X POST https://api.recurrence.cloud/api/mcp \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'
Group Tools What an agent does with them
Orientation whoami · list_environments · list_apps Learn who it’s operating as and where it can write
Schedules list_schedules · get_schedule · create_schedule · update_schedule · delete_schedule · test_schedule_due Full CRUD; preview when a recurrence fires before committing
Delivery targets list_webhooks · create_webhook Point schedules at existing or new HTTPS endpoints
Events list_events · add_event Attach subject + payload series to a schedule
Agent servers register_mcp_server · list_mcp_servers · discover_mcp_tools Register other MCP servers whose tools should be invoked when a schedule fires
One-shot composite create_scheduled_task Complete schedule + delivery target + first event in a single call

3. Call a tool — same envelope, tool name, and arguments:

{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": { "name": "whoami", "arguments": {} }
}

Responses are standard MCP-shaped results — content: [{ type: "text", ... }] with a structuredContent body where applicable, and isError for predictable usage failures (wrong ids, missing args), so clients render them the way they’d render any MCP tool.

Step 2: Connect an actual client

Because the server speaks Streamable HTTP, most MCP clients reach it without glue code. Configure the endpoint with your API key as a header:

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

That shape works for Cursor and editor clients that support HTTP transports; proxies such as mcp-remote make the same endpoint available to clients that only do stdio. Framework clients (LangChain’s MCP client, Vercel AI SDK’s createMCPClient) take the same URL + headers — the endpoint is deliberately stateless, no SSE plumbing.

Note the auth: Authorization: Bearer and X-API-Key are both accepted. Every request is rate-limited per key and every tool result is scoped to the key’s organization — an agent can only see and touch its own tenant’s schedules.

Step 3: From prompt to schedule

The payoff of the recurrenceText args: agents accept natural language and never invent cron syntax. A user says “check our status page every 15 minutes and tell me if it degrades.” The agent calls:

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

One call: the schedule, its webhook, and its first event exist — and the delivery arrives signed at the endpoint whether the agent session is still alive or gone. The agent can manage what it created later (list_schedules, update_schedule, test_schedule_due) in any future session, because the schedule lives outside the conversation.

Step 4: Close the loop — schedules that fire MCP tools

The integration runs in both directions. A schedule isn’t limited to posting webhooks: its delivery target can be another MCP server, so a firing schedule performs a tools/call with the batch’s events:

  1. register_mcp_server (or the REST /v1/mcp-servers surface) adds your MCP server — say, a reports.generate tool.
  2. discover_mcp_tools confirms the tool exists, before the schedule ever fires.
  3. Create the schedule with the MCP delivery target — "target": { "mcpServerId": "<id>", "toolName": "reports.generate" } — each fire becomes a tool invocation carrying the batch’s events.

So the full circle looks like this: your agent schedules its own future tool calls — “tomorrow morning, pull the invoices and brief me” — by pointing a schedule at the very MCP server the agent is using. See scheduled MCP tool calls for the concept in depth, including the A2A task-delegation shape (agent card at /.well-known/agent-card.json) and UCP context mounts if your agent ecosystem goes beyond MCP.

Governance, so agents aren’t a side door

  • Tenant scoping: all tools resolve through the API key’s organization — no cross-tenant reads, verified in the shared executor the REST API uses too.
  • Auditability: every tools/call lands in GET /v1/agent-activity — key id, tool, arguments, outcome. Agent behavior is a ledger, not a mystery.
  • Preview before fire: test_schedule_due tells the agent when the recurrence it drafted will actually fire.
  • Failure signaling: usage errors return isError results — safe for agent retry loops; retries of deliveries are governed by the schedule’s retry policy, with attempts recorded in the activity trail.

FAQ-style finishing notes

  • Protocol compatibility: initialize echoes your client’s protocolVersion; the server is built on 2025-06-18 and speaks only Streamable HTTP (GET/DELETE return 405).
  • Notifications (notifications/initialized, notifications/cancelled) are accepted and answered with no response — stateless, nothing to clean up.
  • MCP + agents don’t replace the REST API — they’re the same services underneath. Use whichever surface your caller prefers; /api/v1 programmatic routes and MCP tools stay in lockstep.

Get started

FAQ

How do I add scheduling tools to an AI agent?

Point any Model Context Protocol (MCP) client at Recurrence Cloud's remote MCP server — https://api.recurrence.cloud/api/mcp — with your agent API key. One JSON-RPC handshake (initialize, tools/list) exposes 17 scheduling tools; agents can create, inspect, update, and delete schedules without your API being involved.

Which MCP protocol version does Recurrence Cloud support?

The server speaks Streamable HTTP JSON-RPC 2.0 and echoes back whichever protocolVersion the client requests during initialize, so it stays compatible across MCP client revisions (built on 2025-06-18). The endpoint is stateless: POST requests only, no session or SSE handling required.

Does Recurrence Cloud work with Claude Desktop, Cursor, or other MCP clients?

Yes — it's a standard remote MCP server over Streamable HTTP, reachable from any client that supports HTTP transport (Cursor, VS Code and other editors, LangChain's MCP client, Vercel AI SDK's MCP client, mcp-remote). Configure the endpoint URL plus your API key header, then the scheduling tools appear in the client's tool list.

What can agents do via the MCP tools?

The full scheduling lifecycle: whoami, list/get/create/update/delete schedules (including human-friendly recurrenceText), test when a recurrence fires, manage webhooks, attach events to schedules, list environments and apps, register other MCP servers and discover their tools, and create a complete scheduled task in one call.

Is agent activity audited?

Every tools/call writes an entry to the agent audit log (GET /v1/agent-activity) with the key, tool, arguments, and outcome, and every tool is scoped to the API key's organization. Agents get real governance, not a side door into your schedules.

How is this different from scheduled MCP tool calls?

Two directions. This article: the agent as MCP client — your agent calls Recurrence Cloud's tools to create schedules on demand. The concept of scheduled MCP tool calls: the schedule as MCP client — it invokes a tool on *your* MCP server when it fires. Together they form a loop: agents schedule work, and schedules wake agents.