CLI Reference

mcp — the MCPCloud CLI

Deploy and manage MCP servers from the terminal. mcp is the primary command; mcpsh and mcpcloud are aliases pointing at the same binary. Published to npm and installable with any package manager.

npm install -g @mcpcloud/cli

API Reference

Installation

Install globally with the package manager of your choice. All three binaries — mcp, mcpsh, and mcpcloud — point at the same executable.

Installbash

# Install globally via npm
npm install -g @mcpcloud/cli

# Or via bun / pnpm / yarn
bun add -g @mcpcloud/cli
pnpm add -g @mcpcloud/cli
yarn global add @mcpcloud/cli

# Or run without installing
npx @mcpcloud/cli

Authentication

Run mcp login to save a key interactively, or set MCPCLOUD_API_KEY for CI/CD. The environment variable takes precedence over the config file.

Loginbash

mcp login
# Opens the browser sign-in; or paste an API key: mcf_**********************

# Or via environment variable (recommended for CI/CD)
export MCPCLOUD_API_KEY=mcf_**********************

Generate API keys at Dashboard → Settings → API Keys or via mcp api-keys create.

Quick start with mcp init

The guided setup wizard mirrors the browser onboarding flow and is fully scriptable. Paste a spec URL, pick a model, and have a deployed MCP server in under a minute.

mcp initbash

# One command: spec → typed MCP server → live deployment,
# with the generated code hosted in your own repo.
mcp init --from-spec ./openapi.yaml \
  --git-repo acme/my-mcp \
  --deploy --wait

→ Using organization Acme (org_acme)
✓ Project Payments created (proj_123).
✓ Linked acme/my-mcp — the repo fills itself after the first generation.
✓ Server srv_new created from spec.
✓ Deployment active at https://calm-otter-042.mcp.mcpcloud.sh/mcp

# Or interactively, with no flags at all:
mcp init

Command reference

All commands support --json for machine-readable output and return appropriate exit codes.

Authentication

Manage your API key and verify your current session. Login defaults to a browser flow (loopback OAuth-style with PKCE-S256); --paste falls back to API-key entry for SSH / headless environments.

mcp login

Open the dashboard, approve the connection, and save the minted API key to ~/.mcpcloud/config.json

mcp login --paste

SSH-friendly: prompt for an API key generated in the dashboard

mcp login --key <apiKey>

Save a key directly without prompting (CI-friendly)

mcp logout

Remove the saved API key

mcp whoami

Show the currently authenticated user, default org, and the resolved API key prefix + dashboard name (via /api/v1/me)

Onboarding

Guided onboarding: pick org → pick or create project → create a server. With --from-spec it generates from an OpenAPI/GraphQL spec, optionally hosts the code in your repo (--git-repo), and can deploy in the same command.

mcp init

Interactive walkthrough — pick an org, pick or create a project, name a new server

mcp init --org <orgId> --project <projectId> --name <serverName>

Skip prompts when all inputs are provided up-front

mcp init --non-interactive --project <id> --name <name>

CI-mode-friendly: refuses prompts and fails fast on missing input

Two-call CI onboardingbash

# Spec → server → deployed, one call
mcp init --non-interactive --from-spec ./openapi.yaml \
  --org $ORG_ID --project $PROJECT_ID \
  --deploy --wait --json | jq -r '.server.id' > .server-id

Projects

Create, update, and inspect projects within your organization. PATCH semantics: omit a key to leave unchanged; pass --visibility to flip private ↔ public.

mcp projects list

List all projects in the current organization

mcp projects get <projectId>

Get full details for a single project

mcp projects create --name <name>

Create a new project (admin/owner). Optional --description, --visibility private|public.

mcp projects update <projectId> [--name --description --visibility]

Update project metadata (RFC 7396 merge patch — only listed fields change)

mcp projects api-sources <projectId>

List imported API specs / source material for a project

mcp projects api-source <apiSourceId>

Show details for a single imported API spec

List projects as JSONbash

mcp projects list --json | jq '.projects[] | {id, name, servers: .serverCount}'

Servers

Create, deploy, pause, push specs to, and inspect MCP servers. The full lifecycle is now wired against the v1 surface.

mcp servers list

List all servers in the organization

mcp servers list --project <id>

Filter servers by project

mcp servers get <serverId>

Get server details including deployment URL

mcp servers create --project <id> --name <name>

Create an empty server skeleton in a project (admin/owner)

mcp servers update <serverId> [--name --description]

Update server metadata (v1 PATCH carries name + description only — runtime config goes through deploy)

mcp servers deploy <serverId> [--wait]

Push the server's generated bundle to Cloudflare Workers. --wait long-polls deployment events until terminal.

mcp servers deploy <serverId> --upstream-base-url <url> --upstream-api-key <secret>

Deploy with an upstream auth binding (see `--upstream-*` flags for the full set)

mcp servers pause <serverId>

Pause the server's latest active deployment (traffic stops; worker is preserved)

mcp servers push-spec <serverId> --spec <path>

One-shot: push a spec, regenerate the bundle, optionally chain into --deploy --wait. The preview reports exactly what --apply will do (inserted / updated / unchanged); --rename-to-operation-ids also adopts the current tool-naming rule

mcp servers regenerate <serverId> --dry-run

Preview a regenerate: the per-tool changes it would make, new operations, and tools whose names the naming rule has moved away from

mcp servers versions <serverId>

List published versions of a server

mcp servers version <serverId> <versionId>

Show details for one published server version

mcp servers deployments <serverId>

List deployment history for a server

mcp servers oauth-connections <serverId>

Show OAuth connections bound to a server

mcp servers logs <serverId> [--follow] [--since 5m]

Tail deployment events. --follow long-polls /api/v1/deployment/events?follow=1 (Ctrl-C to stop). --since accepts 5m/2h/1d, Unix-ms, or ISO-8601.

mcp servers test-runs new <serverId> --scenario <id>

Run a server sandbox scenario synchronously against the server's latest deployment

mcp servers test-runs list <serverId>

List recent server sandbox runs

mcp servers test-runs get <runId>

Show full assertions, trace, and tool output for one run

mcp servers test-scenarios list <serverId>

List sandbox scenarios bound to a server

Spec-driven edit-and-shipbash

# Iterate locally
mcp dev --spec ./openapi.yaml --open ask

# Push a spec change and ship in one command
mcp servers push-spec srv_123 --spec ./openapi.yaml --deploy --wait

Tools

List tools on a server and trigger AI enrichment. Server-wide enrich is one background job on the platform — the CLI starts it and follows it, rather than looping per tool.

mcp tools list <serverId>

List all tools on a server

mcp tools enrich <toolName>

Enrich one tool and show the suggested vs applied diff

mcp tools enrich --all

Enrich every tool on the server as one job (--only to narrow, --no-wait to detach)

mcp tools rename <old> <new> --server <server>

Rename a tool in place, keeping its id; access grants, saved scenarios and parent compositions follow. --dry-run previews, --map @renames.json renames a batch

mcp tools rename --from-operation-ids --server <server>

Adopt the current naming rule: rename every tool codegen used to flatten (getrecording → getRecording). Custom names are kept

mcp tools delete <name> --server <server> --confirm

Remove one tool (its grants go with it; scenarios are archived). Deploy afterwards to take it off the live server

Converge an older server on the current tool namesbash

# See what would change, then do it (tool ids are kept)
mcp tools rename --from-operation-ids --server srv_123 --dry-run
mcp tools rename --from-operation-ids --server srv_123

# The live server keeps the old names until the next deploy
mcp servers deploy srv_123 --wait

Working-tree sync (`mcp pull` / `mcp push`)

Materialize a server as files — every tool as .md, every handler as .ts, plus an AGENTS.md with the authoring rules the push gate enforces — edit, and push the diff back. Conflicts are refused, never overwritten. Built for coding agents working in bursts.

mcp pull --server <server>

Cloud → files under .mcpcloud/ (cloud is the source of truth; removed tools are pruned)

mcp push --dry-run

Print the exact change set the real push would apply, calling nothing

mcp push

Apply local metadata + handler edits; a tool changed in the cloud since your pull is refused, not overwritten

mcp invoke --local <tool>

Boot the pulled tree in a throwaway process and call one tool — unpushed edits included, no deploy, no daemon

Edit a handler and verify before pushingbash

mcp pull --server my-api
$EDITOR .mcpcloud/tools/<serverId>/get_user.md
mcp invoke --local get_user --args '{"id":"42"}'   # runs YOUR edit
mcp push --dry-run
mcp push

Invoking tools (`mcp invoke`)

Call tools on a deployed server from the terminal. Understands every tool surface: wrapper discovery is looked through, code mode runs your JavaScript next to the tools, and deployment selectors target latest | active | previous.

mcp invoke my-api getUser --args '{"id":"abc"}'

Call a tool; args inline, @path/to/args.json, or @- for stdin

mcp invoke my-api --list

What can I call? Reads the real catalog even behind wrapper discovery

mcp invoke my-api --code @script.js

Code mode: run JS in the server’s sandbox — await tool(name, args) calls tools, only the result crosses the wire

mcp invoke my-api ping --deployment previous

Target a specific deployment by selector instead of the latest

One code-mode round trip instead of three tool callsbash

mcp invoke my-api --code '(async () => {
  const pages = await tool("listPages", {})
  return pages.items.filter((p) => p.status === "draft").length
})()'

Sandbox tests as a CI gate

Author test scenarios, group them into suites, and run them in the sandbox — mockBindings needs no upstream credentials and answers “does this server work”. Exit codes carry the verdict, so CI needs no output parsing.

mcp servers test-scenarios generate my-api

Seed one baseline smoke test per tool from the schemas (safe to re-run)

mcp servers variables set my-api --set NAME=value

Fill the {{variables}} scenarios reference; exits non-zero while any remain unset

mcp servers test-suites run my-api

Run the suite; exit 0 = every scenario passed. --execution-profile mockBindings | previewBindings | liveEndpoint

mcp servers test-runs get <runId>

One run’s assertions, trace, and the tool response

The CI deploy gatebash

mcp servers test-suites run my-api --quiet   # non-zero unless green
mcp servers deploy my-api --wait
mcp servers get my-api --probe --quiet       # non-zero if the endpoint drifts from config

Skills

Create, update, archive, install, and run sandbox tests against skills. Connect a deployed skill to your coding agent in one command.

mcp skills list

List all skills in the organization

mcp skills get <skillId>

Get full details for a single skill

mcp skills create --project <id> --name <name>

Create an empty skill draft in a project (admin/owner)

mcp skills update <skillId> [--name --description --visibility]

Update skill metadata (name, description, visibility)

mcp skills archive <skillId>

Archive a skill (replay-as-success on already-archived rows)

mcp skills install <skillId|registryArtifactId> [--pin <semver>] [--config <json>]

Install a skill into the caller's project. A marketplace registry artifact id installs that published skill into your organization instead (same lane as `mcp marketplace install`). Surfaces `purchase_required` (402) on monetized artifacts.

mcp skills uninstall <skillId>

Mark the caller's installation as removed

mcp skills connect <skillId> --agent claude-code --apply

Print (or auto-apply) the MCP configuration to wire a deployed skill into your coding agent

mcp skills versions <skillId>

List published versions of a skill

mcp skills version <skillId> <versionId>

Show details for one published skill version

mcp skills installations <skillId>

List who has the skill installed in the organization

mcp skills test-runs new <skillId> --scenario <id>

Run a skill sandbox scenario synchronously

mcp skills test-runs list <skillId>

List recent skill sandbox runs

mcp skills test-runs get <runId>

Show full assertions, trace, and output for one skill run

Installations

Manage your skill / artifact installations. Both routes are gated on row ownership — admins cannot flip other users' installations through these commands.

mcp installation disable <installationId>

Disable an installation by id (different addressing from `mcp skills uninstall`)

mcp installation remove <installationId>

Mark an installation as removed by id. Same target state as `mcp skills uninstall` but addresses by installation id.

OAuth

Manage OAuth provider connections. Best-effort upstream revoke; replay-as-success on already-revoked rows.

mcp oauth connection delete <connectionId>

Revoke an OAuth connection. Its tokens are revoked at the provider when the provider has a revocation endpoint; a provider failure never blocks the disconnect.

Deployments

Inspect deployment artifacts directly by deployment id (vs. via the parent server).

mcp deployments list

List recent deployments in the organization

mcp deployments get <deploymentId>

Get a single deployment with health + status

mcp deployments logs <deploymentId> [--follow] [--since 1h]

Tail deployment events. --follow long-polls; jsonl in --json mode.

mcp deployments runtime-auth <deploymentId>

Inspect the deployment's runtime-auth posture before calling /api/v1/runtime/auth/token

Tail a deployment in CIbash

mcp --json deployments logs $DEPLOYMENT_ID --follow --follow-timeout 300 \
  | jq -c 'select(.level == "error")'

Marketplace

Browse the public registry of MCP servers and skills. List defaults to public artifacts; pass --org to surface unlisted artifacts in your org.

mcp marketplace list

List published artifacts (servers + skills)

mcp marketplace list --type skill --query "stripe"

Filter by artifact type and free-text search

mcp marketplace get <artifactId>

Show full details for one registry artifact + recent versions

mcp marketplace versions <artifactId>

List published versions of a registry artifact (paginated)

mcp marketplace version <artifactId> <versionId>

Show details for one published registry version

Local development (`mcp dev`)

Local dev runner that mirrors the deployed worker, hot-reloads on edits, exposes an inspector at /__inspect, and auto-wires Claude Code / Cursor / Codex / VS Code Copilot / Continue. On a git-linked server it goes git-native automatically: it serves from a clone of your repo (reused across sessions and directories, never reset), and commit + push is how changes flow back.

mcp dev <server>

Run locally with hot reload; git-linked servers serve from a clone of the repo, no flag needed

mcp dev <server> --repo ~/code/my-mcp

Git-native: serve from a checkout you already have (origin is verified; the choice is remembered per server)

mcp dev <server> --spec ./openapi.yaml

Watch the spec on disk; cloud-side regen + auto-apply when the tool surface changes

mcp dev invoke <tool> / tail / replay / list / kill

Drive the running session headlessly: call tools, stream inspector records as JSON lines, re-fire recorded calls

mcp dev <server> --offline

Run the cached bundle without touching the cloud

Git-native sessionbash

mcp dev my-api
# → Git-linked server — using existing clone at .mcpcloud/git/acme__my-mcp
# → this server expects UPSTREAM_API_KEY — add values to .mcpcloud/env.json
# ...edit, commit, push...
# → OK: Push 1c9ecbf reconciled (1 updated) — changes ready for deployment.

The GitHub loop (`mcp servers git`)

Your server’s code lives in a repository you own. Link it (at creation or any time after), and the loop runs both ways: committed versions mirror out within seconds, pushes reconcile back through a three-way conflict guard, become versions with the git message and SHA, and the sandbox suite posts its verdict on the commit and on pull requests.

mcp servers git link <server> --repo owner/name

Link an existing repo (empty is fine — the first push bootstraps it) and run the initial sync

mcp init --from-spec api.yaml --git-repo owner/name

Link at creation (--git-path-prefix for monorepos); the repo fills itself after the first generation

mcp servers git status <server>

The whole loop at a glance: repo, mirror + reconcile state, working-tree changes, deployment lag

mcp servers commit <server> -m "message"

Commit the working tree as a version — advances the branch, so the mirror and deploys see it

mcp servers git sync <server>

Push committed HEAD to the repo now instead of waiting for the sweep

mcp servers git unlink <server>

Stop the loop; the repository itself is untouched

The whole loop, headlessbash

mcp servers git link my-api --repo acme/my-mcp --auto-sync
git clone git@github.com:acme/my-mcp && cd my-mcp
mcp dev my-api                      # serves from this checkout
# edit src/tools/getUser.ts, commit, push
# → mcpcloud/code-sync ✓  ·  mcpcloud/tests 17/17 ✓  (on the commit)
mcp servers git status my-api       # mirror synced · working tree clean

Terminal UI (`mcp ui`)

A full-screen TUI over the whole workspace: tabbed browsers for servers, projects, skills, deployments, the marketplace, and local mcp dev sessions with the live inspector. Filter with /, sort with s, tail logs with l, switch orgs with o.

mcp ui

Open the TUI (--no-splash jumps straight to the list, --splash replays the splash)

: or Ctrl-P

Command palette — reach any verb by name without leaving the UI

D

Searchable docs view covering every command plus task playbooks

,

Settings overlay that edits ~/.mcpcloud/config.json in place

A session (splash, then the workspace)bash

$ mcp ui

     ███╗   ███╗ ██████╗██████╗     ██████╗██╗     ██╗
     ████╗ ████║██╔════╝██╔══██╗   ██╔════╝██║     ██║
     ██╔████╔██║██║     ██████╔╝   ██║     ██║     ██║
     ██║╚██╔╝██║██║     ██╔═══╝    ██║     ██║     ██║
     ██║ ╚═╝ ██║╚██████╗██║        ╚██████╗███████╗██║
     ╚═╝     ╚═╝ ╚═════╝╚═╝         ╚═════╝╚══════╝╚═╝
                                        by MCPCloud.sh

 1·SERVERS  2·PROJECTS  3·SKILLS  4·DEPLOYMENTS  5·MARKETPLACE  6·DEV SESSIONS

 ID                     Name                     Status    Version  Last Deployed
 ────────────────────── ──────────────────────── ───────── ──────── ─────────────
▸ms7bqpkq…              Slate                    active    1.0.6    2 minutes ago
 ms77ar6f…              Tally — Payments API     active    1.0.4    3 days ago
 ms76phbz…              Forge — Code & Issues    active    1.0.1    3 days ago

 Tab switch  ↵ detail  / filter  s sort  : palette  d deploy  T test  ? help  q quit

Diagnostics & maintenance

Preflight your local setup, query an anonymous deployment-version probe, and update the CLI.

mcp doctor

Check Node version, config perms, profile, base URL, deployment version + capabilities, API key, claude CLI, latest npm release

mcp doctor --offline

Skip the npm-registry version probe

mcp --ci --warnings-as-errors doctor

Use as a CI gate: warnings exit non-zero

mcp update

Detects how the CLI was installed (npm / bun / brew / pnpm / yarn) and runs the right re-install command

mcp completion bash | zsh | fish

Print a shell-completion script for the current shell

mcp help <topic>

Topic help: auth, profiles, agents, errors

The 8-point health checkbash

$ mcp doctor
      Check               Detail
────  ──────────────────  ─────────────────────────────────────────────
OK    Node version        22.15.0 (>= 18.0.0)
OK    Config file         ~/.mcpcloud/config.json (mode 600, parses cleanly)
OK    Active profile      default (from saved currentProfile)
OK    Base URL            https://api.mcpcloud.sh (production) (from profile)
OK    Deployment version  2026.04.28-1 — 5 capabilities: cli.exchange, …
OK    API key             Authenticated against /api/v1/me
OK    claude CLI          Found at /usr/local/bin/claude
OK    Latest release      Up to date

Config & profiles

Persist base URL, API key, default org, and named profiles. Switch between production and self-hosted deployments without editing JSON.

mcp config set-url <baseUrl>

Persist the API base URL to ~/.mcpcloud/config.json

mcp config set-org <orgId>

Persist a default organization ID

mcp config profile add <name> --url <baseUrl> --key <apiKey> [--org <id>]

Add a named config profile

mcp config profile list

Print all saved profiles

mcp config use <profileName>

Switch the saved current profile

mcp --profile selfhost servers list

One-off override of the active profile

Audit (admin/owner only)

Query the per-organization audit log. Capability-gated: requires viewAuditLogs (admin or owner role).

mcp audit list

List recent audit events for the organization

mcp audit list --action controlPlane.serverDeployed --limit 50

Filter by exact action and limit page size

API Keys

Manage personal API keys for machine and CI/CD access. Created keys are shown once — store them in a secrets manager.

mcp api-keys list

List all API keys with preview and last-used date

mcp api-keys create --name <name>

Create a new API key — shown once, save it

mcp api-keys revoke <keyId>

Permanently revoke a key

Create a CI keybash

mcp api-keys create --name "github-actions" --json | jq -r '.apiKey'

CI/CD integration

The primary non-interactive use case is deploying automatically after a spec file changes. Store your API key as a repository secret and use MCPCLOUD_API_KEY in the workflow.

.github/workflows/mcp-deploy.ymlbash

# .github/workflows/mcp-deploy.yml
name: Deploy MCP Server
on:
  push:
    branches: [main]
    paths: ["openapi.yaml"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2  # optional — bunx works without it on ubuntu
      - name: Deploy MCP server
        run: bunx --bun @mcpcloud/cli servers deploy ${{ env.MCP_SERVER_ID }}
        env:
          MCPCLOUD_API_KEY: ${{ secrets.MCPCLOUD_API_KEY }}

JSON output for scripting

Pass --json to any command to receive machine-readable output. Combine with jq for scripting.

--json flagbash

# All commands accept --json for scripting
mcp servers list --json | jq '.servers[].id'
mcp servers deploy $SERVER_ID --json | jq -r '.deploymentId'
mcp api-keys list --json

Environment variables

MCPCLOUD_API_KEY

API key for authentication. Highest precedence — overrides the key stored in ~/.mcpcloud/config.json and any active profile.

optional

MCPCLOUD_BASE_URL

Override the MCPCloud base URL. Highest precedence after the --base-url flag.

optional

MCPCLOUD_ORG_ID

Default organization ID. Skips the org-discovery step for commands that take --org.

optional

MCPCLOUD_PROFILE

Active config profile name. Resolution: --profile flag > MCPCLOUD_PROFILE > saved currentProfile > "default".

optional

MCPCLOUD_APP_URL

Dashboard origin for `mcp login` (the browser-redirect target). Defaults to https://mcpcloud.sh; useful when running a self-hosted dashboard.

optional

CI

When truthy, the CLI auto-enables CI mode: ANSI color off, ASCII glyphs, prompts refused (only --key / MCPCLOUD_API_KEY work for login), `request id: <none>` fallback when the upstream envelope omits one.

optional

MCPCLOUD_LOG

Set to `debug` (or `trace`) to dump every HTTP request/response with secrets redacted. Equivalent to passing --debug.

optional

MCPSH_NO_AUDIT_LOG

Set to `1` to suppress the local ~/.mcpcloud/audit.log file (every successful POST/PATCH/DELETE writes a line by default).

optional

Next steps

The CLI consumes the same REST API available to all MCPCloud customers. See the API reference for the full endpoint contract.

API Reference Open dashboard