@mcpcloud/cli

The official command-line interface for MCPCloud — manage projects, MCP servers, skills, and API keys from your terminal.

npm install -g @mcpcloud/cli
export MCPCLOUD_BASE_URL=https://your-deployment.example.com   # ask your admin
mcp login
mcp whoami

Note MCPCloud is in private beta. The CLI does not ship with a default API base URL — set MCPCLOUD_BASE_URL (or mcp config set-url <url>) using the URL provided by your MCPCloud admin. A built-in default will be added when the platform launches publicly.

The package installs three equivalent binaries: mcp (primary), mcpsh, and mcpcloud. They all point at the same executable — use whichever you prefer.

Requirements

• Node.js 18 or newer
• An MCPCloud account and API key (create one at https://mcpcloud.sh)

Installation

# global install
npm install -g @mcpcloud/cli
bun  add -g @mcpcloud/cli

# one-off invocation (no install)
npx -y @mcpcloud/cli whoami
bunx --bun @mcpcloud/cli whoami

Configuration

The CLI needs two values to talk to your MCPCloud deployment: an API base URL and an API key. Either or both can come from environment variables, the saved config file, or per-invocation flags.

1. Set the API base URL

The CLI does not assume any default base URL. Use whichever method fits your environment:

# environment variable (recommended for CI / scripts)
export MCPCLOUD_BASE_URL=https://your-deployment.example.com

# persist for your user account (writes to ~/.mcpcloud/config.json)
mcp config set-url https://your-deployment.example.com

# one-off override
mcp --base-url https://your-deployment.example.com whoami

The lookup order is: --base-url flag → MCPCLOUD_BASE_URL env var → saved baseUrl in ~/.mcpcloud/config.json. If none are set the CLI exits with code 3 and a clear message.

2. Authenticate

# Save a key to ~/.mcpcloud/config.json (mode 0600)
mcp login                       # interactive prompt (recommended)
mcp login --key mck_xxx         # non-interactive (avoid: writes to shell history)

# Or use an environment variable (recommended for CI)
export MCPCLOUD_API_KEY=mck_xxx

mcp logout removes the saved key. mcp config show prints the current resolved config (with the API key redacted).

Quick start

mcp whoami                      # show current key + organizations
mcp projects list               # list projects in your default org
mcp servers list                # list MCP servers
mcp servers get srv_123         # detail view
mcp servers logs srv_123        # recent deployment events
mcp tools  list srv_123         # tools exposed by a server
mcp skills list                 # list skills
mcp skills connect skl_123 --agent claude-code --apply
                                  # auto-register a skill with Claude Code
mcp api-keys list               # personal API keys
mcp api-keys create --name CI   # mint a new key (secret shown once)
mcp api-keys revoke key_456

Run mcp <command> --help on any command for the full option list.

Global flags

| Flag | Description | | ------------------ | --------------------------------------------------------------------------------------- | | --json | Emit raw JSON on stdout. Errors come back as { "error": { "code", "message", ... } }. | | --base-url <url> | Override the API base URL for one invocation (useful for staging). | | -v, --version | Print the CLI version. | | -h, --help | Show help for any command. |

Environment variables

| Variable | Description | | ------------------- | ------------------------------------------------------------- | | MCPCLOUD_API_KEY | API key used for authentication (overrides the saved config). | | MCPCLOUD_BASE_URL | API base URL. Required — there is no built-in default. | | MCPCLOUD_ORG_ID | Default organization ID for commands that require one. |

The organization for each command is resolved in this order:

1. The --org flag (when supported).
2. MCPCLOUD_ORG_ID.
3. defaultOrganizationId saved in ~/.mcpcloud/config.json.
4. The server-side default returned from /api/v1/organizations.

Commands

Authentication & config

mcp login [--key <secret>]      # save an API key locally
mcp logout                      # remove the saved key
mcp whoami                      # show current key, base URL, and accessible orgs

mcp config show                 # print resolved config (key redacted)
mcp config set-url <url>        # persist the API base URL
mcp config clear-url            # remove the saved base URL
mcp config set-org <orgId>      # persist a default organization
mcp config clear-org            # remove the saved default organization

Projects

mcp projects list [--org <id>] [--limit <n>]
mcp projects get  <projectId> [--org <id>]

Servers

mcp servers list [--org <id>] [--project <id>] [--limit <n>]
mcp servers get  <serverId> [--org <id>]
mcp servers logs <serverId> [--org <id>] [--limit <n>]

Tools

mcp tools list --project <projectId> [--org <id>]
mcp tools list --server <serverId>  [--org <id>]   # looks up the project for you

Skills

mcp skills list [--org <id>] [--project <id>] [--limit <n>]
mcp skills get  <skillId> [--org <id>]

# Print or apply the MCP configuration that wires a skill into your coding agent.
mcp skills connect <skillId>
    [--org <id>]
    [--agent claude-code|codex|claude-desktop|vscode|cursor|windsurf|antigravity]
    [--name <connection-name>]
    [--apply]                     # for claude-code only: runs `claude mcp add`

API keys

mcp api-keys list
mcp api-keys create --name <displayName>
mcp api-keys revoke <apiKeyId>

The secret returned by api-keys create is shown once. Save it immediately — you cannot retrieve it again.

JSON mode

Every command supports --json for piping into another tool. In JSON mode the CLI emits a single JSON document on success and a { "error": { ... } } envelope on failure. No human-readable text is mixed in.

mcp --json projects list | jq '.projects[].slug'

mcp --json skills connect skl_123 --agent cursor \
  | jq '.snippet'

Exit codes

| Code | Meaning | | ---- | ---------------------------------------------------------------------------------------- | | 0 | Success. | | 1 | Generic failure (API error, validation error, network error). | | 2 | No API key configured. Run mcp login or set MCPCLOUD_API_KEY. | | 3 | No API base URL configured. Set MCPCLOUD_BASE_URL or run mcp config set-url <url>. |

When an API call fails, the CLI prints the response code, status, and request id (when present) to make debugging easier:

Error: Server not found (code: not_found) (status: 404)
  request id: api_018f...
  docs:       https://mcpcloud.sh/docs/errors#not_found

Configuration file

The CLI stores its config at ~/.mcpcloud/config.json with mode 0600. Recognised fields:

{
  "apiKey": "mck_...", // saved by `mcp login`
  "baseUrl": "https://your-deployment...", // saved by `mcp config set-url`
  "defaultOrganizationId": "org_...", // saved by `mcp config set-org`
}

You can edit the file directly or replace it. Environment variables take precedence over its contents.

Reliability

• Timeout: every request is bounded by a 30-second AbortController.
• Retry: transient failures (network errors, HTTP 502/503/504) are retried once with jittered backoff. 4xx responses are never retried.
• Error envelope: server errors are surfaced with their code, message, requestId, and docsUrl so you can correlate with backend logs.

Development

git clone https://github.com/MCPCloud-sh/mcp-hub
cd mcp-hub/packages/cli

bun install
bun run dev -- --help            # run from source
bun run typecheck                # tsc --noEmit
bun run test                     # vitest
bun run build                    # bundle to dist/index.js

The bundled output is a single Node-compatible ESM file with a #!/usr/bin/env node shebang.

Releasing

The CLI is released independently of the dashboard via Changesets.

Support

• Documentation: https://mcpcloud.sh/docs
• Email: [email protected]

License

MIT © MCPCloud.sh