Examples
AI Agent Automation via MCP
Let an AI agent write and deploy an automation end-to-end
AI Agent Automation via MCP
HeadlessOps exposes a native MCP server that lets AI agents (Claude, Cursor, Roo Code, etc.) write, deploy, and run integrations directly.
How It Works
- The agent connects to the MCP server via OAuth 2.1 + PKCE
- The agent reads the platform scripting guide (
GET /api/platform-docs) - The agent lists existing integrations and credentials
- The agent writes
integration.yamland step files - The agent calls
push-runto deploy and execute atomically - The agent polls the run status and reads logs
Example: One-Time Ad-Hoc Task
An agent can perform a one-time action (e.g., create a calendar event) using a manual-trigger integration:
POST /api/integrations/google-calendar-utils/push-run
{
"files": {
"integration.yaml": "name: google-calendar-utils\ndescription: Ad-hoc Google Calendar utilities\ntrigger:\n type: manual\nsteps:\n - id: create_event\n name: Create Calendar Event\n description: Creates a new event in Google Calendar\n file: create_event.ts\n credentials: [GOOGLE_CALENDAR_TOKEN]",
"create_event.ts": "export async function run(input: Record<string, any>, ctx: StepContext) {\n const token = ctx.credentials.GOOGLE_CALENDAR_TOKEN;\n const res = await ctx.http.post(\n 'https://www.googleapis.com/calendar/v3/calendars/primary/events',\n {\n headers: { Authorization: `Bearer ${token}` },\n json: { summary: input.summary, start: { dateTime: input.start_time }, end: { dateTime: input.end_time } },\n timeout: 25000\n }\n );\n if (!res.ok) throw new Error(`Google API returned ${res.status}`);\n const event = await res.json();\n return { event_id: event.id };\n}"
},
"payload": {
"summary": "Meeting with team",
"start_time": "2026-06-10T10:00:00Z",
"end_time": "2026-06-10T11:00:00Z"
}
}Response:
{ "runId": "run_xyz789", "status": "RUNNING" }The agent then polls GET /api/runs/run_xyz789 until status is SUCCEEDED.
MCP Tool Scopes
| Scope | Tools Available |
|---|---|
mcp:tools | Workspaces, Knowledge Base, Data Stores |
integrations:read | List/get integrations and files |
integrations:write | Create/update integrations, push files, deploy, run |
runs:read | List runs, get run details and step logs |
runs:write | Trigger manual runs |
credentials:use | List, create, and manage credentials |
See MCP Setup for connection instructions.