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
mcpl gateway list                             # See your Gateways

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.

Keeping the CLI Up to Date

`mcpl version`

Print the CLI version, and — for released builds — the git commit, build date, and platform.

mcpl version

Development builds report a short commit hash instead of a semantic version.

`mcpl update`

Check GitHub Releases for a newer mcpl and install it in place. You are prompted before anything is replaced (the prompt is skipped when stdout is not a terminal).

mcpl update          # Check, confirm, and install
mcpl update --check  # Only report whether a newer version exists

Flag	Type	Default	Description
`--check`	bool	`false`	Only check for updates, do not install

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

`mcpl deploy api-key <name-or-id>`

Show the current API key for a deployment that uses key-based authentication (auth_type: key). Accepts the deployment name or its UUID. The plaintext key is printed so you can store it securely, alongside the key ID, prefix, and expiry.

Aliases: apikey, key

mcpl deploy api-key mcp-k8s

`mcpl deploy api-key rotate <name-or-id>`

Issue a new API key, persist it, and invalidate the previous one. The new plaintext key is printed once — any client still using the old key stops working immediately.

mcpl deploy api-key rotate mcp-k8s
mcpl deploy api-key rotate mcp-k8s --value 90 --unit days

Flag	Type	Default	Description
`--value`	int	—	New key lifetime value (omit both flags for the 30-day default)
`--unit`	string	`days`	New key lifetime unit: `hours`, `days`, `weeks`, `years`

If the new key is issued but the old one cannot be invalidated, the command warns you and the old key may still be valid — re-run rotate to retry.

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

Registry

Browse the MCP Server Registry — a curated catalog of publicly available MCP servers you can deploy. The registry is public, so results are the same for every user.

`mcpl registry search <query>`

Search the registry by case-insensitive substring match across each server’s name and description.

mcpl registry search fetch
mcpl registry search github --limit 5
mcpl registry search time -o json

Flag	Type	Default	Description
`--limit`	int	`20`	Maximum number of results to return

Columns: NAME, TIER, TRANSPORT, PACKAGE, DESCRIPTION, followed by a Showing N of M result(s) summary line.

`mcpl registry info <name>`

Show the full details of one registry server: transport, source package or image, repository, tools, tags, and a table of its environment variables (NAME, REQUIRED, SECRET, DESCRIPTION). Registry names are reverse-DNS style and may contain slashes.

Aliases: get, show

mcpl registry info io.github.stacklok/fetch
mcpl registry info fetch -o json

The output ends with the ready-to-run mcpl deploy command for that server.

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 get <id-or-name>       # Show project details
mcpl project switch <id-or-name>    # Set the active project
mcpl project current                # Show the active project
mcpl project update <id-or-name>    # Update project name/description
mcpl project delete <id-or-name>    # Delete a project

Every command that takes an existing project accepts its ID or its name. create takes --description and --switch; delete takes -y to skip the confirmation prompt.

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

Gateways

A Gateway is one MCP endpoint that aggregates the tools of several running deployments. Your agent connects to a single stable URL and sees every tool behind it; you add or remove servers without touching client config.

Gateway subcommands take the Gateway’s UUID (from mcpl gateway list), not its name — unlike mcpl deploy, which accepts a name or an ID.

`mcpl gateway list`

List Gateways in the active project.

Aliases: ls

mcpl gateway list

Columns: NAME, ID, STATUS, AUTH, URL, MEMBERS, OPTIMIZER.

The OPTIMIZER column reads off (suggest) when a Gateway serves enough distinct tools that the tool optimizer would likely save context; a hint below the table names those Gateways.

`mcpl gateway get <gateway-id>`

Show full Gateway details, including optimizer_enabled, optimizer_config, and distinct_tool_count. Gateway IDs come from mcpl gateway list. This command always prints JSON.

`mcpl gateway create <name>`

Create one MCP endpoint for multiple deployments. The name must be DNS-1123 compatible (max 63 characters).

mcpl gateway create agent-tools --member <deployment-uuid> --member <deployment-uuid>
mcpl gateway create agent-tools --auth key --key-duration 90
mcpl gateway create agent-tools --optimizer

Flag	Type	Default	Description
`--project`	string	active project	Project UUID
`--auth`	string	`oauth`	Authentication: `oauth`, `key`, or `none`
`--member`	string[]	—	Deployment UUID to attach (repeatable, max 20 per Gateway)
`--key-duration`	int	`30`	Key lifetime value (key auth only)
`--key-duration-unit`	string	`days`	Key lifetime unit: `hours`, `days`, `weeks`, `years`
`--optimizer`	bool	`false`	Serve `find_tool`/`call_tool` instead of the full tool list
`--optimizer-max-tools`	int	`8`	Results `find_tool` returns (1–50)
`--optimizer-semantic-ratio`	string	`0.5`	Search blend, `0.0` keyword to `1.0` semantic
`--optimizer-distance-threshold`	string	`1.0`	Semantic distance cutoff, `0` identical to `2` unrelated

With --auth key, the generated API key is printed once at creation. Store it then — it is not retrievable afterwards.

`mcpl gateway update <gateway-id>`

Update one or more fields of an existing Gateway. Only the flags you provide are changed.

mcpl gateway update <gateway-id> --optimizer
mcpl gateway update <gateway-id> --optimizer=false
mcpl gateway update <gateway-id> --optimizer --optimizer-max-tools 20 --optimizer-semantic-ratio 0.8
mcpl gateway update <gateway-id> --name agent-tools-eu

Flag	Type	Default	Description
`--name`	string	—	New Gateway name (DNS-1123, max 63 chars)
`--auth`	string	—	Authentication: `oauth`, `key`, or `none`
`--optimizer`	bool	—	`--optimizer` turns it on, `--optimizer=false` turns it off
`--optimizer-max-tools`	int	—	Results `find_tool` returns (1–50)
`--optimizer-semantic-ratio`	string	—	Search blend, `0.0` keyword to `1.0` semantic
`--optimizer-distance-threshold`	string	—	Semantic distance cutoff, `0` identical to `2` unrelated

Passing no flags is an error. Omitting --optimizer leaves the current setting alone — that is not the same as --optimizer=false.

Tool optimizer

With the optimizer on, the Gateway stops advertising every aggregated tool and advertises two meta-tools instead: find_tool (hybrid keyword + semantic search) and call_tool (dynamic dispatch). Clients search for what they need rather than loading every schema up front.

Before turning it on:

Tools are no longer listed individually. Anything that calls a tool by its exact name gets tool not found until it goes through find_tool first. Agents that discover tools as they go are unaffected.
The Gateway serves MCP 2025-11-25 to every client while the optimizer is on, including clients that support a newer revision.
Changing optimizer settings restarts the Gateway, so connected clients reconnect.

Nothing is deleted and no deployment changes. Turning it back off restores the full tool list.

If the platform has no embedding backend configured, enabling it fails with the tool optimizer is not available on this deployment.

`mcpl gateway add-member <gateway-id> <deployment-id>...`

Attach one or more running deployments. A Gateway holds at most 20 members in total.

mcpl gateway add-member <gateway-id> <deployment-uuid> <deployment-uuid>

`mcpl gateway remove-member <gateway-id> <deployment-id>`

Detach a deployment from the Gateway without deleting the deployment.

mcpl gateway remove-member <gateway-id> <deployment-uuid>

`mcpl gateway start|stop <gateway-id>`

Start or stop a Gateway. Stopping leaves its member deployments running.

mcpl gateway stop <gateway-id>
mcpl gateway start <gateway-id>

`mcpl gateway delete <gateway-id>`

Delete a Gateway. Its member deployments are left untouched.

mcpl gateway delete <gateway-id>

Deep dive: MCPLambda Gateways — patterns and use cases (learn guide).

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'