Milkey CLI

Official Milkey CLI for automatic MCP (Model Context Protocol) setup across AI coding agents.

npx @milkeyskills/cli setup

Milkey is a hosted skills infrastructure platform for AI agents and developers. This CLI detects supported AI coding agents on your system, asks for your approval, collects your Milkey API key via a secure hidden prompt, and safely configures Milkey as a remote MCP server in your agents' configuration files.

Table of Contents

• Quick Start
• Requirements
• Commands
  • setup
  • detect
  • status
  • doctor
  • remove
  • print-config
• Supported Agents
• Setup Scopes
• Authentication Modes
• Non-Interactive & CI Usage
• Security
• Manual Configuration
• Development
• Architecture

Quick Start

The fastest way to get started:

# Using npx (no installation required)
npx @milkeyskills/cli setup

# Or install globally
npm install -g @milkeyskills/cli
milkey setup

The CLI will:

1. Detect installed AI coding agents on your system
2. Ask which agents to configure
3. Ask where to configure (global or project-level)
4. Prompt for your Milkey API key (hidden input)
5. Show a plan of changes and ask for confirmation
6. Write configurations safely with automatic backups

Requirements

• Node.js >= 20
• A Milkey API key (starts with mk_sk_)
• One or more supported AI coding agents

Commands

milkey setup

Configure Milkey MCP for AI coding agents. This is the primary command.

# Interactive setup with auto-detection
milkey setup

# Dry run - see what would change without writing anything
milkey setup --dry-run

# Target specific agents
milkey setup --agent cursor,codex

# Skip all confirmations (useful for CI/CD)
milkey setup --yes --agent cursor --api-key mk_sk_...

# Configure only global/user scope
milkey setup --scope user

# Configure only project scope
milkey setup --scope project

# Configure both user and project scopes
milkey setup --scope both

# Use environment variable instead of direct key
milkey setup --env-var
milkey setup --env-var MY_CUSTOM_KEY_NAME

# Force replace existing valid configuration
milkey setup --force

# Output JSON (useful for automation)
milkey setup --json --yes --agent cursor

# Custom config path for generic agents
milkey setup --agent generic --config-path ./mcp.json

Setup options:

| Option | Description | |--------|-------------| | --dry-run | Show planned changes without writing anything | | --agent <ids> | Comma-separated agent IDs (e.g., cursor,codex,windsurf) | | --scope <scope> | user, project, manual, or both | | --yes | Skip confirmations where possible | | --api-key <key> | Provide API key for non-interactive setup | | --env-var [name] | Use environment variable reference (default: MILKEY_API_KEY) | | --config-path <path> | Manual config path for generic/manual clients | | --force | Replace existing valid Milkey entry | | --json | Output machine-readable JSON | | --verbose | Show verbose output | | --debug | Show stack traces for unexpected errors |

milkey detect

Detect installed or suspected AI coding agents on your system.

# Detect all supported agents
milkey detect

# Detect specific agents
milkey detect --agent cursor,codex

# JSON output
milkey detect --json

Detection looks for:

• Agent configuration directories (e.g., ~/.cursor, ~/.codex)
• Agent executables on PATH (e.g., cursor, codex, gemini)
• Existing configuration files

milkey status

Show Milkey MCP status for all known agents - combines detection and doctor results in a single view.

milkey status
milkey status --agent cursor
milkey status --json

Shows:

• Whether each agent is detected
• Whether Milkey is configured
• Config file path
• Authentication mode (direct key, env var, or missing)
• Any issues found

milkey doctor

Validate Milkey MCP configuration and detect common mistakes.

milkey doctor
milkey doctor --agent cursor,codex
milkey doctor --json

The doctor checks:

• Node.js version (>= 20)
• Config file existence and syntax
• Milkey MCP entry presence
• Authorization header correctness
• Duplicate keys
• Agent-specific config shape issues (e.g., Windsurf uses serverUrl not url)

milkey remove

Remove only the Milkey MCP entry from selected agents. Other MCP servers and settings are preserved.

# Interactive removal
milkey remove

# Remove from specific agents
milkey remove --agent cursor,codex

# Skip confirmation
milkey remove --yes

# Remove from project scope only
milkey remove --agent cursor --scope project

milkey print-config

Print a manual Milkey MCP config snippet for a specific agent.

milkey print-config --agent cursor
milkey print-config --agent codex --env-var
milkey print-config --agent generic --api-key mk_sk_...

Supported Agents

| Agent | ID | Scopes | Status | |-------|-----|--------|--------| | Cursor | cursor | user, project | Stable | | Claude Code | claude-code | user | Stable | | Codex | codex | user, project | Stable | | Windsurf | windsurf | user | Stable | | GitHub Copilot IDE / VS Code | copilot-ide | user, project | Stable | | GitHub Copilot CLI | copilot-cli | user | Stable | | Gemini CLI | gemini-cli | user, project | Stable | | Cline | cline | user | Stable | | Roo Code | roo-code | project, manual | Stable | | Continue | continue | project | Stable | | OpenCode | opencode | user, project | Stable | | Zed | zed | manual | Experimental | | Antigravity | antigravity | manual | Experimental | | Generic MCP JSON | generic | manual | Stable |

Setup Scopes

The interactive setup asks where Milkey should be configured before it asks for your API key.

Global / User-Wide (user)

Writes to the agent's user config, such as ~/.cursor/mcp.json. Choose this when you want Milkey available in every project opened by that agent.

Current Project (project)

Writes into the current working directory, such as .cursor/mcp.json. Choose this when you want the repo to carry an MCP config shape, or when testing without touching global agent settings.

Both (both)

Writes Milkey to both user and project locations (if the agent supports both).

Manual (manual)

For generic or experimental clients where you must choose the exact config file path using --config-path.

Authentication Modes

Direct Key (default)

The API key is written directly into the agent's configuration file.

milkey setup

Warning: Config files containing direct API keys are treated as credential files. Do not commit them to version control.

Environment Variable

The configuration references an environment variable instead of storing the key directly.

milkey setup --env-var
# Uses MILKEY_API_KEY

milkey setup --env-var MY_CUSTOM_VAR
# Uses MY_CUSTOM_VAR

Not all agents support environment variable references. The CLI will warn you if the selected agent doesn't support this mode.

Non-Interactive & CI Usage

For CI/CD pipelines and automation:

# Fully automated setup
milkey setup --yes --agent cursor --api-key "$MILKEY_API_KEY"

# Multiple agents
milkey setup --yes --agent cursor,codex,windsurf --api-key "$MILKEY_API_KEY"

# With JSON output for parsing
milkey setup --yes --agent cursor --api-key "$MILKEY_API_KEY" --json

# Dry run in CI
milkey setup --dry-run --yes --agent cursor --api-key "$MILKEY_API_KEY" --json

Security note: Using --api-key can store the key in shell history. For interactive use, prefer the hidden prompt. In CI, use environment variables and secret management.

Security

Milkey CLI takes security seriously:

• API key masking: API keys are masked in all output (e.g., mk_sk_abc...xyz)
• Hidden prompts: API keys are collected via password-style hidden input
• Automatic backups: Existing config files are backed up before modification with timestamped filenames (e.g., mcp.json.milkey-backup-20250115-143022)
• Secure permissions: On macOS/Linux, config files and backups containing secrets get chmod 600 (owner read/write only)
• Atomic writes: Configurations are written atomically via temp file + rename to prevent corruption
• File locking: Concurrent modifications are prevented using file locks
• No disk scanning: The CLI only checks known agent config paths, not the whole disk
• No shell profile modification: The CLI does not modify shell profiles automatically
• Read-only protection: Won't attempt to modify read-only or corporate-managed configs
• Secret masking in logs: Logger automatically masks mk_sk_* tokens in all output

Backup files may contain API keys and should not be committed or shared.

Manual Configuration

If you prefer to configure manually or the CLI doesn't support auto-write for your agent, here are the correct config shapes for each supported agent.

Replace <MILKEY_API_KEY> with your actual key. Do not commit these files.

Cursor

File: ~/.cursor/mcp.json (user) or .cursor/mcp.json (project)

{
  "mcpServers": {
    "milkey": {
      "url": "https://mcp.milkeyai.com/mcp",
      "headers": {
        "Authorization": "Bearer <MILKEY_API_KEY>"
      }
    }
  }
}

Restart: Reload Cursor or open MCP settings.

Claude Code

claude mcp add --scope user --transport http --header "Authorization: Bearer <MILKEY_API_KEY>" milkey https://mcp.milkeyai.com/mcp
claude mcp list

Codex

File: ~/.codex/config.toml (user) or .codex/config.toml (project)

[mcp_servers.milkey]
url = "https://mcp.milkeyai.com/mcp"
startup_timeout_sec = 30.0
tool_timeout_sec = 90.0

[mcp_servers.milkey.http_headers]
Authorization = "Bearer <MILKEY_API_KEY>"

Restart: Restart Codex session or use /mcp.

Windsurf

File: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "milkey": {
      "serverUrl": "https://mcp.milkeyai.com/mcp",
      "headers": {
        "Authorization": "Bearer <MILKEY_API_KEY>"
      }
    }
  }
}

Important: Use serverUrl, not url.

Restart: Refresh the MCP panel or restart Windsurf.

GitHub Copilot IDE / VS Code

User files:

• macOS: ~/Library/Application Support/Code/User/mcp.json
• macOS Insiders: ~/Library/Application Support/Code - Insiders/User/mcp.json
• Windows: %APPDATA%/Code/User/mcp.json
• Linux: ~/.config/Code/User/mcp.json

Project file: .vscode/mcp.json

{
  "servers": {
    "milkey": {
      "url": "https://mcp.milkeyai.com/mcp",
      "requestInit": {
        "headers": {
          "Authorization": "Bearer <MILKEY_API_KEY>"
        }
      }
    }
  }
}

Important: Use top-level servers, not mcpServers.

Restart: Open Agent mode tools list in VS Code or reload the window.

GitHub Copilot CLI

File: ~/.copilot/mcp-config.json

{
  "mcpServers": {
    "milkey": {
      "type": "http",
      "url": "https://mcp.milkeyai.com/mcp",
      "headers": {
        "Authorization": "Bearer <MILKEY_API_KEY>"
      },
      "tools": ["*"]
    }
  }
}

Restart: Restart Copilot CLI.

Gemini CLI

File: ~/.gemini/settings.json (user) or .gemini/settings.json (project)

{
  "mcpServers": {
    "milkey": {
      "httpUrl": "https://mcp.milkeyai.com/mcp",
      "headers": {
        "Authorization": "Bearer <MILKEY_API_KEY>"
      }
    }
  }
}

Important: Use httpUrl, not url.

Restart: Start gemini and run /mcp list.

Cline

File: ~/.cline/data/settings/cline_mcp_settings.json

Or if $CLINE_DIR is set: $CLINE_DIR/data/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "milkey": {
      "url": "https://mcp.milkeyai.com/mcp",
      "headers": {
        "Authorization": "Bearer <MILKEY_API_KEY>"
      },
      "disabled": false
    }
  }
}

Restart: Restart Cline or check MCP settings.

Roo Code

File: .roo/mcp.json (project)

{
  "mcpServers": {
    "milkey": {
      "url": "https://mcp.milkeyai.com/mcp",
      "headers": {
        "Authorization": "Bearer <MILKEY_API_KEY>"
      },
      "disabled": false
    }
  }
}

Note: Global Roo config may require a manual mcp_settings.json path.

Restart: Restart Roo / VS Code window or open the MCP panel.

Continue

File: .continue/mcpServers/milkey.json

{
  "mcpServers": {
    "milkey": {
      "url": "https://mcp.milkeyai.com/mcp",
      "headers": {
        "Authorization": "Bearer <MILKEY_API_KEY>"
      }
    }
  }
}

Restart: Reload Continue / workspace.

OpenCode

Files: ~/.config/opencode/opencode.json, opencode.json, or opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "milkey": {
      "type": "remote",
      "url": "https://mcp.milkeyai.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer <MILKEY_API_KEY>"
      }
    }
  }
}

Restart: Restart OpenCode.

Note: If your OpenCode version rejects remote headers, run milkey doctor and verify the schema for your installed version.

Zed

Zed support is experimental in v1 because public examples are commonly stdio-oriented and use context_servers.

Potential stdio bridge shape:

{
  "context_servers": {
    "milkey": {
      "command": "npx",
      "args": ["-y", "@milkeyskills/mcp-bridge"],
      "env": {
        "MILKEY_API_KEY": "<MILKEY_API_KEY>",
        "MILKEY_MCP_URL": "https://mcp.milkeyai.com/mcp"
      }
    }
  }
}

File: ~/.config/zed/settings.json (Linux/macOS) or %APPDATA%/Zed/settings.json (Windows)

Antigravity

Antigravity support is experimental because the config shape is still evolving. Verify inside the Antigravity MCP UI before relying on it.

{
  "mcpServers": {
    "milkey": {
      "url": "https://mcp.milkeyai.com/mcp",
      "headers": {
        "Authorization": "Bearer <MILKEY_API_KEY>"
      }
    }
  }
}

Generic MCP JSON

For any other client that supports standard MCP JSON:

{
  "mcpServers": {
    "milkey": {
      "url": "https://mcp.milkeyai.com/mcp",
      "headers": {
        "Authorization": "Bearer <MILKEY_API_KEY>"
      }
    }
  }
}

For clients that require different keys, adapt:

• Top-level key: mcpServers or servers
• URL field: url, serverUrl, or httpUrl
• Auth header path: headers.Authorization or requestInit.headers.Authorization

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Type check
npm run typecheck

# Run in development mode
npm run dev -- setup --dry-run

Tests use temporary directories and do not touch your real home directory.

Architecture

Project Structure

src/
├── index.ts              # CLI entry point, command registration
├── commands/
│   ├── setup.ts          # Interactive and automated setup
│   ├── detect.ts         # Agent detection
│   ├── doctor.ts         # Configuration validation
│   ├── status.ts         # Combined detection + doctor view
│   ├── remove.ts         # Remove Milkey entries
│   └── print-config.ts   # Print manual config snippets
├── agents/
│   ├── types.ts          # TypeScript interfaces
│   ├── registry.ts       # Agent registry
│   ├── common.ts         # Shared agent logic (JSON, TOML, command agents)
│   ├── cursor.ts
│   ├── claude-code.ts
│   ├── codex.ts
│   ├── windsurf.ts
│   ├── copilot-ide.ts
│   ├── copilot-cli.ts
│   ├── gemini.ts
│   ├── cline.ts
│   ├── roo.ts
│   ├── continue.ts
│   ├── opencode.ts
│   ├── zed.ts
│   ├── antigravity.ts
│   └── generic.ts
└── lib/
    ├── constants.ts      # Milkey URL, API key shape
    ├── platform.ts       # OS-specific paths
    ├── fs.ts             # File system utilities
    ├── atomic-write.ts   # Atomic file writes with secure permissions
    ├── backups.ts        # Automatic backup creation
    ├── file-lock.ts      # Concurrent modification prevention
    ├── json.ts           # JSON/JSONC parsing and manipulation
    ├── toml.ts           # TOML parsing and manipulation
    ├── masking.ts        # API key masking and validation
    ├── prompts.ts        # Interactive prompts
    ├── logger.ts         # Structured logging (text/JSON)
    ├── errors.ts         # Error types and handling
    ├── path-validation.ts # Path validation and normalization
    └── executables.ts    # Executable detection

Key Design Principles

1. Non-destructive: Existing configs are preserved, merged, and backed up. Only the milkey MCP entry is touched.
2. Idempotent: Running setup twice is safe. If Milkey is already correctly configured, it's a no-op.
3. Secure: API keys are masked, prompts are hidden, files get restricted permissions, and writes are atomic.
4. Cross-platform: Supports macOS, Windows, and Linux with platform-specific path resolution.
5. Agent-aware: Each agent has its own config shape, field names, and restart instructions.

MCP Endpoint

https://mcp.milkeyai.com/mcp

Auth Contract

Authorization: Bearer <MILKEY_API_KEY>

Milkey API keys usually start with mk_sk_.

License: MIT

Issues & Support: Please report issues to the Milkey team with your agent ID and the output of milkey doctor --json.