The mcpl CLI Reference | MCPLambda Docs

mcpl is the official command-line interface for the MCPLambda PaaS. It allows you to automate your agent infrastructure directly from your development environment.

Quick Start

mcpl login                                    # Authenticate via GitHub/Google
mcpl deploy npx://@mcp/server-time            # Deploy an MCP server (streams build logs live)
mcpl deploy list                              # See your deployments
mcpl deploy status mcp-server-time            # Check status by name
mcpl deploy logs mcp-server-time              # Tail live logs by name

Installation

macOS / Linux

curl -fsSL https://mcplambda.io/mcpl/install.sh | sh

The installer detects your OS and CPU architecture, downloads the latest release binary from GitHub, and installs mcpl to /usr/local/bin (falling back to ~/.local/bin).

Windows (PowerShell 5.1+)

irm https://mcplambda.io/mcpl/install.ps1 | iex

Installs mcpl.exe to %LOCALAPPDATA%\mcpl and adds it to your user PATH.

Global Flags

These flags are available on every command.

Flag	Type	Default	Description
`--config`	string	`~/.mcpl/config.json`	Config file path
`-o, --output`	string	`table`	Output format: `table` or `json`

Authentication

`mcpl login`

Authenticate with MCPLambda using your GitHub or Google account. This command opens a browser window to the MCPLambda login page where you can choose your preferred provider.

mcpl login          # Open browser to login page
mcpl login --force  # Re-authenticate even if already logged in

Flag	Type	Default	Description
`--force`	bool	`false`	Re-authenticate even if already logged in

How it works:

Starts a local callback server on your machine.
Opens your browser to the MCPLambda login page.
You choose GitHub or Google on the login page.
Upon successful login, authentication tokens are securely saved to ~/.mcpl/config.json.
Loads your default project automatically.

`mcpl logout`

Clear locally stored authentication tokens.

mcpl logout

`mcpl whoami`

Show the current authenticated user, session status, and active project.

mcpl whoami

Deployments

`mcpl deploy [source]`

Create a new deployment from a package manager, Git repository, or container image.

# Package Flow
mcpl deploy npx://@modelcontextprotocol/server-everything
mcpl deploy uvx://mcp-server-time --name my-timer

# Git Flow
mcpl deploy https://github.com/user/mcp-server --branch main

# Docker Image Flow
mcpl deploy ghcr.io/user/mcp-image:latest --env API_KEY=secret

Common Flags:

--name: Set a custom name for your deployment (DNS-1123 compatible).
--project: Project ID or name (defaults to active project).
--transport: Set the transport type (stdio, streamable-http, sse).
--branch: Git branch (git deployments only).
-e, --env: Add environment variables (e.g., -e API_KEY=secret).
--no-wait: Return immediately without streaming build logs or waiting for readiness.

Behavior:

Auto-detects deployment type from the source string.
Generates a DNS-safe name from the source if --name is not provided.
Real-time Feedback: Streams live build logs via SSE immediately after queuing, so you see image build and startup progress in the terminal.
Prints the final deployment URL and exits once the deployment reaches running or failed.

`mcpl deploy list`

List all deployments in your active project.

Aliases: ls

mcpl deploy list
mcpl deploy list --limit 5

`mcpl deploy status <name-or-id>`

Get the current status of a deployment. Accepts the deployment name or its UUID.

Aliases: get

mcpl deploy status mcp-k8s
mcpl deploy status mcp-k8s --watch
mcpl deploy status mcp-k8s --logs

Flag	Type	Default	Description
`-w, --watch`	bool	`false`	Continuously poll until running, failed, or stopped
`-l, --logs`	bool	`false`	Stream live logs instead of showing static status

`mcpl deploy logs <name-or-id>`

Stream live logs from a deployment via Server-Sent Events. Accepts the deployment name or its UUID.

mcpl deploy logs mcp-k8s
mcpl deploy logs mcp-k8s --since 5m

`mcpl deploy update <name-or-id>`

Update one or more fields of an existing deployment. Only the flags you provide are changed. Accepts the deployment name or its UUID.

mcpl deploy update mcp-k8s --replicas 2
mcpl deploy update mcp-k8s --env API_KEY=newsecret

`mcpl deploy env <name-or-id>`

Show the environment variables and secrets configured for a deployment. Accepts the deployment name or its UUID.

Aliases: env-vars

mcpl deploy env mcp-k8s

Lifecycle Management

All lifecycle commands accept the deployment name or its UUID.

mcpl deploy stop <name-or-id>       # Stop a deployment (scale to 0)
mcpl deploy start <name-or-id>      # Start a stopped deployment (scale to 1)
mcpl deploy restart <name-or-id>    # Trigger a rolling restart
mcpl deploy delete <name-or-id>     # Permanently delete a deployment

Projects

Projects allow you to group deployments and secrets.

mcpl project list           # List all projects
mcpl project create <name>  # Create a new project
mcpl project switch <name>  # Set the active project
mcpl project current        # Show the active project
mcpl project update <id>    # Update project name/description
mcpl project delete <id>    # Delete a project

Secrets

Secrets are injected as environment variables into your deployments. Values are masked by default.

mcpl secret list                      # List project secrets
mcpl secret create <KEY> <VALUE>      # Create a secret
mcpl secret create DEBUG 1 --plain    # Create an unmasked variable
mcpl secret get <id>                  # Show secret details
mcpl secret update <id> <value>       # Update a secret's value
mcpl secret delete <id>               # Delete a secret

Configuration

Environment Variables

Variable	Default	Description
`MCPL_CONFIG_HOME`	`~/.mcpl/config.json`	Config file path
`MCPL_DEBUG`	—	Enable debug logging (`1`, `true`, or `yes`)

Output Formats

JSON

Pass -o json to any command for structured JSON output, suitable for scripting and piping:

mcpl deploy list -o json | jq '.[].name'