Connecting Claude Desktop

Prerequisites

Claude Desktop installed (download)
A HeadlessOps account with at least one workspace

Option A: Remote MCP (Recommended)

The simplest setup — Claude connects directly to the HeadlessOps MCP server over HTTPS.

Configuration

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the HeadlessOps MCP server:

{
  "mcpServers": {
    "headlessops": {
      "url": "https://app.headlessops.ai/mcp",
      "type": "http"
    }
  }
}

First Connection

Restart Claude Desktop after saving the config
Open a new conversation
Claude will prompt you to authorize the HeadlessOps MCP connection
A browser window will open — log in to HeadlessOps and grant the requested scopes
Claude is now connected and can manage your automations

Option B: Local Proxy (Enables `folderPath`)

The @headlessops-ai/mcp package provides a local proxy between Claude Desktop and the remote MCP endpoint. It handles OAuth 2.1 + PKCE authentication and resolves folderPath parameters to inline file contents from your local filesystem.

Step 1 — Install the Proxy

npm install -g @headlessops-ai/mcp

Step 2 — Configure Claude Desktop

{
  "mcpServers": {
    "headlessops": {
      "command": "headlessops-mcp",
      "args": ["--mcp-url", "https://app.headlessops.ai/mcp"]
    }
  }
}

macOS Homebrew Node: If you installed Node via Homebrew, the binary lands at /opt/homebrew/bin/headlessops-mcp. Use "/opt/homebrew/bin/headlessops-mcp" as the command value if Claude Desktop doesn't inherit your shell PATH.

Step 3 — Restart Claude Desktop

On first use with the proxy, Claude will initiate an OAuth flow in the browser to authorize the connection.

Workspace Resolution

If you have multiple workspaces, create an iterator/iterator.config.json file in your project repository:

{ "workspaceId": "ws_abc123" }

Claude will automatically use this workspace for all tool calls when working inside that repository.

To find your workspace ID:

"List my workspaces"

Claude will call workspaces_list and show the available workspace IDs.

Example Prompts

Once connected, you can ask Claude in natural language:

Listing and inspecting:

"List all my integrations"
"Show me the last 10 failed runs of crm-sync"
"What files does the invoice-processor integration have?"

Creating and deploying:

"Create a webhook integration that logs incoming payloads and saves them to a data store"
"Write a scheduled integration that runs every Monday at 9am and sends a Slack summary"
"Deploy a manual integration that fetches a contact from HubSpot by email"

Debugging:

"The crm-sync integration failed — read the logs and fix the error"
"Check the last run of daily-report and tell me what happened in step 2"

Working with data stores:

"Create a data store called processed-invoices with columns: invoice_id (TEXT), amount (NUMBER), processed_at (DATE)"
"List all data stores in my workspace"

Agent Workflow with Files

With the local proxy, Claude can work with your local files directly:

You: "The integration at iterator/crm-sync/ needs updating — the contact fetch step 
      is failing. Download the files, fix the error, and push an updated version."

Claude: 
  1. Calls integration_files_list to see what files exist
  2. Downloads files to iterator/crm-sync/ locally using folderPath
  3. Reads the run logs to identify the error
  4. Edits the TypeScript step file
  5. Calls integration_files_push_run with folderPath to push + test
  6. Reports the result

Connect Claude Desktop