Clockwork

MCP Integration

Clockwork exposes its full toolset over the Model Context Protocol (MCP) — a standard interface for connecting AI agents to external capabilities. With the MCP integration, Claude, ChatGPT, or any compatible AI can create workflows, manage tasks, respond to events, and fill role slots — all through natural language.

Setup: Claude Desktop / Claude Code

Add Clockwork to your MCP server config:

json
{
  "mcpServers": {
    "clockwork": {
      "command": "npx",
      "args": ["-y", "@clockwork/mcp"],
      "env": {
        "CLOCKWORK_API_KEY": "ck_live_your_key_here"
      }
    }
  }
}

That's it. Claude now has access to all 50+ Clockwork tools.

Setup: Hosted MCP endpoint

For AI agents that consume MCP over HTTP (rather than stdio), use the hosted endpoint:

https://mcp.clockwork-co.com/mcp

Pass your API key per request:

bash
curl -X POST https://mcp.clockwork-co.com/mcp \
  -H "Authorization: Bearer ck_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "create_task",
      "arguments": {
        "name": "Review proposal",
        "durationMinutes": 60,
        "priority": "high"
      }
    }
  }'

Available tools

The MCP server exposes 50+ tools that map 1:1 to SDK methods. Key tools:

Workflow management

  • create_workflow_template, publish_template, rollback_template
  • create_workflow_instance, cancel_workflow_instance

Task operations

  • create_task, complete_task, delay_task, assign_task
  • list_tasks, get_task, update_task

Events & monitoring

  • list_events, subscribe_to_events, stream_events

Collaboration

  • create_approval, approve_approval, reject_approval
  • create_conversation, post_conversation_message

Resource management

  • create_resource, allocate_resource, fill_role

See the full list in the SDK Reference — every resource has a corresponding MCP tool.

What AI agents can do

With the MCP tools available, an AI agent can:

User: "Start an onboarding workflow for our new customer Acme Corp"

→ Agent calls create_workflow_instance (templateId: 'tmpl_onboarding', subjectId: 'acme')
→ Agent calls fill_role (slotName: 'account-manager', resourceId: 'res_alice')
→ Agent calls list_tasks to confirm tasks are ready
→ Agent responds: "Onboarding workflow started. Alice is assigned as account manager.
   First task 'Send welcome email' is ready."

Custom MCP server

You can build a custom MCP server that wraps Clockwork with domain-specific tools:

typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { Clockwork } from '@clockwork/sdk'
 
const clockwork = new Clockwork({ apiKey: process.env.CLOCKWORK_API_KEY })
const server = new McpServer({ name: 'my-clockwork-server', version: '1.0.0' })
 
// Custom tool that wraps multiple Clockwork calls
server.tool(
  'start_deal_workflow',
  'Start the standard deal-closing workflow for a new deal',
  {
    dealId: { type: 'string', description: 'The deal ID from your CRM' },
    dealValue: { type: 'number', description: 'Deal value in USD' },
  },
  async ({ dealId, dealValue }) => {
    const { data: instance } = await clockwork.workflowInstances.create({
      templateId: process.env.DEAL_TEMPLATE_ID,
      subjectType: 'deal',
      subjectId: dealId,
      metadata: { dealValue },
    })
 
    return {
      content: [{ type: 'text', text: `Started deal workflow ${instance.id} for deal ${dealId}` }],
    }
  }
)

Environment variables

VariableDescription
CLOCKWORK_API_KEYYour ck_live_... API key
CLOCKWORK_API_URLOverride the API base URL (default: https://platform.clockwork-co.com)

Related