Connecting Cursor & Roo Code

Both Cursor and Roo Code support MCP servers and can use the local proxy for full folderPath support.

Option A: Remote MCP (No Local Files)

Cursor

Open Cursor settings and navigate to Features → Model Context Protocol.

Add a new MCP server:

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

Save settings and restart Cursor. On first use, you will be redirected to authorize the connection.

Option B: Local Proxy (Recommended for Development)

The @headlessops-ai/mcp package provides a local proxy between the AI client 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 — Cursor Configuration

In Cursor MCP settings, configure the server as a local command instead of a URL:

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

Step 3 — Roo Code Configuration

In .roo/mcp.json or your global Roo MCP settings:

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

Or with npx (no global install required):

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

Step 4 — Windsurf / Other stdio-based Clients

For Windsurf or any other MCP client that supports stdio transport, the pattern is the same:

{
  "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 the absolute path if your client doesn't inherit the shell PATH.

Workspace Resolution

Create iterator/iterator.config.json in your repository root:

{ "workspaceId": "ws_abc123" }

Both Cursor and Roo Code agents read this file automatically when working in the repository.

Local Folder Convention

All integration files are managed as local text files in the iterator/ directory:

iterator/
  iterator.config.json       # Workspace ID config
  crm-sync/
    integration.yaml
    fetch_contact.ts
    update_crm.ts
    helpers.ts               # optional
    knowledge_base.md        # documents design and schemas
    fix_log.md               # debugging history
  invoice-processor/
    integration.yaml
    fetch_invoice.ts
    process_payment.ts
    knowledge_base.md

Working with an Existing Integration

1. Download first — use integration_files_list (download mode) to write all files to iterator/{name}/ locally
2. Edit locally — make all changes to the local files
3. Push-run — call integration_files_push_run with folderPath pointing to iterator/{name}/

Creating a New Integration

1. Create the iterator/{name}/ directory locally
2. Write integration.yaml and all step .ts files
3. Write knowledge_base.md documenting the design
4. Call integration_files_push_run with folderPath to deploy and test

Example Agent Prompts

With the local proxy set up:

• "Download the files for the crm-sync integration, fix the failing step, and redeploy"
• "Create a new scheduled integration that runs every day at 9am and syncs Airtable → HubSpot. Put the files in iterator/airtable-hubspot-sync/"
• "The last run of invoice-processor failed — read the logs, fix the bug, update fix_log.md, and push a new version"

Without the proxy (inline file mode):

• "Write a simple webhook integration that echoes the incoming payload back and run it once to verify"
• "Create a manual integration that fetches a user by email from my Stripe account"

Inline Files vs folderPath

Default recommendation: Use folderPath for anything with more than a few lines of code. The local proxy setup is a one-time step and makes the agent significantly more effective.