Connecting Claude Code

Claude Code is Anthropic's agentic CLI tool. It supports MCP natively and is the fastest way to connect HeadlessOps to your terminal workflow.

Prerequisites

Claude Code installed (npm install -g @anthropic-ai/claude-code or via the official guide)
A HeadlessOps account with at least one workspace

Option A: One-Command Setup (Recommended)

Run this in your terminal:

claude mcp add headlessops --transport http https://app.headlessops.ai/mcp

Claude Code will add the server to its configuration automatically. On first use, it will open your browser to authorize the connection.

Option B: Manual Configuration

Edit the Claude Code MCP config file:

macOS / Linux: ~/.claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the headlessops entry to mcpServers:

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

Restart Claude Code and authorize in the browser when prompted.

Option C: Local Proxy (Enables `folderPath`)

Install the local proxy to enable the folderPath parameter for reading and writing local files:

Step 1 — Install the Proxy

npm install -g @headlessops-ai/mcp

Step 2 — Configure Claude Code

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

macOS Homebrew Node: Use /opt/homebrew/bin/headlessops-mcp as the command if Claude Code doesn't inherit your shell PATH.

Workspace Resolution

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

{ "workspaceId": "ws_abc123" }

To find your workspace ID:

"List my HeadlessOps workspaces"

Example Prompts

Once connected, try these in Claude Code:

Inspect your workspace:

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

Build and deploy:

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

Debug:

"The crm-sync integration failed — read the logs and fix the error"
"Check run run_abc123 and summarize what went wrong"

Agent Workflow with Local Files

With the local proxy, Claude Code can edit your files directly:

You: "The crm-sync integration is failing on the contact-fetch step.
      Download the files, fix the bug, and push a new version."

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

Connect Claude Code