Connect Your AI Client
Connect any MCP-compatible AI client to headlessops.ai in under 2 minutes — Claude Code, Claude Desktop, Cursor, Codex, Windsurf, VS Code Copilot, or any generic client.
Connect Your AI Client
HeadlessOps exposes a native MCP server at:
https://app.headlessops.ai/mcpPick your client below, paste the config snippet, restart, and authorize in your browser.
Quick Setup
Run the following command in your terminal:
claude mcp add headlessops --transport http https://app.headlessops.ai/mcpThat's it. Claude Code will prompt you to authorize in your browser on first use.
Or configure manually in ~/.claude/claude_desktop_config.json (macOS/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"headlessops": {
"url": "https://app.headlessops.ai/mcp",
"type": "http"
}
}
}Restart Claude Code and authorize when prompted.
Edit your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"headlessops": {
"url": "https://app.headlessops.ai/mcp",
"type": "http"
}
}
}- Save the file
- Restart Claude Desktop
- Authorize in the browser when prompted
Open Cursor Settings → Features → Model Context Protocol and add:
{
"name": "HeadlessOps",
"url": "https://app.headlessops.ai/mcp",
"type": "http"
}- Save settings
- Restart Cursor
- Authorize in the browser when prompted
Add to your codex.json MCP configuration:
{
"mcpServers": {
"headlessops": {
"url": "https://app.headlessops.ai/mcp",
"type": "http"
}
}
}Or with the local proxy (required for folderPath support):
{
"mcpServers": {
"headlessops": {
"command": "npx",
"args": ["-y", "@headlessops-ai/mcp", "--mcp-url", "https://app.headlessops.ai/mcp"]
}
}
}Open Windsurf Settings → MCP and add a new server:
{
"mcpServers": {
"headlessops": {
"url": "https://app.headlessops.ai/mcp",
"type": "http"
}
}
}Or with the local proxy:
{
"mcpServers": {
"headlessops": {
"command": "headlessops-mcp",
"args": ["--mcp-url", "https://app.headlessops.ai/mcp"]
}
}
}Add to your VS Code settings.json:
{
"mcp": {
"servers": {
"headlessops": {
"url": "https://app.headlessops.ai/mcp",
"type": "http"
}
}
}
}Or with the local proxy:
{
"mcp": {
"servers": {
"headlessops": {
"type": "stdio",
"command": "headlessops-mcp",
"args": ["--mcp-url", "https://app.headlessops.ai/mcp"]
}
}
}
}Any MCP client that supports HTTP or stdio transport works.
HTTP transport (direct URL):
{
"url": "https://app.headlessops.ai/mcp",
"type": "http"
}stdio transport (via local proxy):
npm install -g @headlessops-ai/mcp{
"command": "headlessops-mcp",
"args": ["--mcp-url", "https://app.headlessops.ai/mcp"]
}macOS Homebrew Node: use
/opt/homebrew/bin/headlessops-mcpas thecommandif your client doesn't inherit shell PATH.
Authentication
All connections use OAuth 2.1 with PKCE — no API key required. OAuth is user-level: each user authenticates individually and receives their own access token scoped to their account. On first connection, your AI client opens a browser window where you log in to HeadlessOps and grant access. The token is stored automatically.
This means multiple users can each connect their own AI client independently — every user authorizes with their own HeadlessOps account.
Working with Local Files (folderPath)
To let your AI agent read and write local files directly, install the local proxy:
npm install -g @headlessops-ai/mcpThen replace the url config with:
{
"command": "headlessops-mcp",
"args": ["--mcp-url", "https://app.headlessops.ai/mcp"]
}