--- title: Agent Guide: Deploying Remote MCP Servers description: Complete guide for AI agents to deploy and manage MCP servers on MCPLambda using the mcpl CLI and MCPLambda MCP server. --- This guide is written for **AI agents** — coding assistants, autonomous agents, and LLM-powered tools — that need to deploy and manage remote MCP servers on MCPLambda on behalf of a human user. --- ## Overview MCPLambda is a PaaS for deploying MCP (Model Context Protocol) servers. An AI agent can use the `mcpl` CLI or the **MCPLambda MCP server** to: 1. **Install** the `mcpl` CLI on the user's machine. 2. **Authenticate** on behalf of the user. 3. **Deploy** an MCP server from a package manager, Git repository, or container image. 4. **Retrieve** the deployment URL and API key. 5. **Connect** the deployed server to an AI client (Cursor, Claude Desktop, VSCode, etc.). There are two paths for agents: - **`mcpl` CLI** — The most direct path. Handles authentication, deployment, and status tracking with JSON output for programmatic consumption. - **MCPLambda MCP server** — Connect to `api.mcplambda.io/mcp` as a remote MCP server and use tools like `create_deployment`, `get_deployment`, `search_registry` to manage infrastructure using MCP itself. --- ## Prerequisites ### Install the mcpl CLI The installer is served from the MCPLambda website and downloads the latest binary from GitHub Releases. **macOS / Linux:** ```bash curl -fsSL https://mcplambda.io/mcpl/install.sh | sh ``` **Windows (PowerShell 5.1+):** ```powershell irm https://mcplambda.io/mcpl/install.ps1 | iex ``` The installer: - Detects OS and CPU architecture (`darwin`/`linux` x `amd64`/`arm64`). - Resolves the latest GitHub Release (or a specific version via `MCPL_VERSION`). - Downloads the archive and `checksums.txt`. - Verifies the SHA-256 checksum. - Installs `mcpl` to `/usr/local/bin` (or `~/.local/bin` as fallback). **Install a specific version:** ```bash curl -fsSL https://mcplambda.io/mcpl/install.sh | MCPL_VERSION=1.2.3 sh ``` **Verify installation:** ```bash mcpl --version ``` > **Agent tip:** If `/usr/local/bin` is not writable, the installer falls back to `~/.local/bin`. Check if that directory is in `PATH` and add it to the user's shell profile if needed: > ```bash > export PATH="$HOME/.local/bin:$PATH" > ``` ### System Requirements - `curl` and `tar` must be available (used by the installer). - `sha256sum` or `shasum` for checksum verification (pre-installed on most systems). - A terminal/shell that can run the `mcpl` binary. --- ## Authentication ### Two Authentication Contexts Before proceeding, it is important to understand that MCPLambda has **two separate authentication layers**: | Context | Token Type | Purpose | Who Uses It | |---------|-----------|---------|-------------| | **Platform API** | Service Account Token (`mcpl_sat_`) | Deploy, list, manage deployments | The AI agent (via CLI or MCP server) | | **Deployed Server** | Deployment API Key (`mcpl_live_`) | Connect an MCP client to the deployed MCP server | The user's MCP client (Cursor, Claude Desktop) | The agent authenticates to the **platform** to deploy servers. The user's MCP client authenticates to the **deployed server** to use tools. These are separate concerns with separate tokens. > **Key insight:** If you deploy with `auth_type: oauth` (the default), the user's MCP client handles OAuth automatically — **no deployment API key is needed**. The API key flow is only relevant when `auth_type: key` is chosen for service-to-service or agent-driven access. ### Current Flow: `mcpl login` (Browser-Based) ```bash mcpl login ``` This opens a browser window to the MCPLambda login page where the user chooses GitHub or Google. Upon success, tokens are saved to `~/.mcpl/config.json`. **How it works:** 1. Starts a local callback server. 2. Opens the browser to the MCPLambda login page. 3. User authenticates with GitHub or Google. 4. Tokens are saved to `~/.mcpl/config.json`. 5. The default project is loaded automatically. ### Headless / Non-Interactive Auth (Suggested) The current `mcpl login` flow requires a browser, which is not ideal for headless agent environments. The following approaches are recommended for agent-driven workflows: 1. **Service Account Tokens** — A long-lived API token generated from the dashboard that agents can use with `mcpl login --token ` or by setting `MCPL_API_TOKEN` in the environment. 2. **OAuth Device Flow** — A non-browser flow where the agent displays a code and the user authorizes it on any device. 3. **Existing Session Reuse** — If the user has already run `mcpl login`, the agent can reuse the session from `~/.mcpl/config.json`. **Check current auth status:** ```bash mcpl whoami -o json ``` ```json { "user": "user@example.com", "authenticated": true, "project": "my-project", "project_id": "abc-123" } ``` > **Agent action:** Before deploying, always run `mcpl whoami` to verify the user is authenticated. If not authenticated, prompt the user to run `mcpl login` or provide a service account token. **Token scopes (proposed):** | Scope | Description | |-------|-------------| | `deployments:read` | List and view deployments | | `deployments:write` | Create, update, delete deployments | | `secrets:read` | View project secrets (masked) | | `secrets:write` | Create, update, delete secrets | | `projects:read` | List and view projects | | `projects:write` | Create, update, delete projects | | `billing:read` | View billing info | | `billing:write` | Change plans, manage billing | | `admin` | Full account access (use with caution) | > **Agent recommendation:** Agents should request tokens scoped to `deployments:write` and `secrets:write` only — never `billing:write` or `admin`. --- ## Deployment Paths MCPLambda supports three deployment strategies. The `mcpl deploy` command auto-detects the type from the source string. Below are detailed examples for each flow. ### 1. Package Flow (Fastest) Deploy directly from a package manager URL. No Dockerfile or build infrastructure needed — MCPLambda's backend resolves the package and spins up a container with the required runtime automatically. **Supported protocols:** `npx://`, `uvx://`, `pip://`, `go://` #### Example: Deploy a Node.js MCP server (NPX) ```bash mcpl deploy npx://@modelcontextprotocol/server-everything \ --name my-everything \ --transport streamable-http \ --server-profile small \ -o json ``` #### Example: Deploy a Python MCP server with environment variables (UVX) ```bash mcpl deploy uvx://mcp-server-fetch \ --name fetch-server \ --transport streamable-http \ -e API_KEY=sk-abc123 \ -e DEBUG=true \ --server-profile small \ -o json ``` #### Example: Deploy with API key auth and secrets ```bash mcpl deploy npx://@modelcontextprotocol/server-github \ --name github-mcp \ --transport streamable-http \ --auth-type key \ --api-key-duration 30days \ -e GITHUB_TOKEN=ghp_xxx \ --server-profile medium \ -o json ``` #### Example: Deploy a Go MCP server ```bash mcpl deploy go://github.com/mark3labs/mcp-go \ --name go-mcp \ --transport streamable-http \ -o json ``` > **Agent tip:** The package flow is the fastest path. Use it when deploying community servers from npm, PyPI, or Go modules. The platform auto-detects the runtime and handles containerization. --- ### 2. Git Flow (GitOps) Deploy from a Git repository. MCPLambda's Image Builder service detects your language, builds a secure container image, and deploys it. Every push to the configured branch triggers an automatic rebuild. **Additional flags for Git deployments:** - `--branch`: Git branch (defaults to repo's default branch). - `--build-strategy`: `auto` (default), `dockerfile`, `pip`, `uv`, `poetry`, `npm`, `pnpm`, `go`. - `--build-command`: Post-install build command (e.g., `npm run build`). - `--install-command`: Override the default install step. - `--run`: Command to start the MCP server (required if no `mcplambda.yaml` in repo). #### Example: Simple Node.js server (auto-detected) If your repo has a `package.json` with a start script, MCPLambda auto-detects the build strategy: ```bash mcpl deploy https://github.com/user/my-mcp-server \ --branch main \ --name my-node-server \ --transport streamable-http \ -o json ``` #### Example: TypeScript server with explicit build command For TypeScript projects that need compilation before running: ```bash mcpl deploy https://github.com/user/ts-mcp-server \ --branch main \ --name ts-mcp-server \ --build-strategy npm \ --install-command "npm ci" \ --build-command "npm run build" \ --run "node dist/index.js" \ --transport streamable-http \ -o json ``` #### Example: Python server with UV build strategy For Python projects using `uv` as the package manager: ```bash mcpl deploy https://github.com/user/py-mcp-server \ --branch main \ --name py-mcp-server \ --build-strategy uv \ --install-command "uv sync" \ --run "uv run mcp-server" \ --transport streamable-http \ -e API_KEY=sk-abc123 \ -o json ``` #### Example: Python server with Poetry ```bash mcpl deploy https://github.com/user/poetry-mcp-server \ --branch main \ --name poetry-mcp \ --build-strategy poetry \ --install-command "poetry install --no-dev" \ --run "poetry run python -m mcp_server" \ --transport streamable-http \ -o json ``` #### Example: Server with a Dockerfile If your repo contains a `Dockerfile`, use the `dockerfile` build strategy. MCPLambda builds the image directly: ```bash mcpl deploy https://github.com/user/custom-mcp-server \ --branch main \ --name custom-mcp \ --build-strategy dockerfile \ --transport streamable-http \ -e DATABASE_URL=postgres://... \ --server-profile medium \ -o json ``` #### Example: Server with `mcplambda.yaml` If your repo contains a `mcplambda.yaml` file, MCPLambda reads build and run configuration from it. You don't need to pass `--build-command`, `--install-command`, or `--run`. Full field reference, merge rules, and processing steps: **[mcplambda.yaml (Git Deploy Config)](/docs/mcplambda-yaml/)**. ```yaml # mcplambda.yaml in your repo root build_strategy: npm install_command: npm ci build_command: npm run build run: node dist/index.js transport: streamable-http ``` ```bash mcpl deploy https://github.com/user/mcp-server-with-yaml \ --branch main \ --name yaml-server \ -o json ``` #### Example: Git deploy with secrets and env vars ```bash mcpl deploy https://github.com/user/api-mcp-server \ --branch main \ --name api-mcp \ --build-strategy pnpm \ --install-command "pnpm install --frozen-lockfile" \ --build-command "pnpm build" \ --run "node dist/server.js" \ --transport streamable-http \ -e NODE_ENV=production \ -e LOG_LEVEL=info \ --auth-type key \ --api-key-duration 90days \ --server-profile medium \ -o json ``` > **Agent tip:** For Git deployments, check if the repo has a `mcplambda.yaml` first. If it does, you can skip most flags. If not, you need to provide `--run` at minimum, and likely `--build-strategy`, `--install-command`, and `--build-command` depending on the language. Explicit CLI flags always override the yaml when both are set. --- ### 3. Image Flow (Pre-built Containers) Deploy a pre-built container image from any registry. MCPLambda pulls the image and orchestrates the deployment. **Supported registries:** Docker Hub, GHCR, Amazon ECR, Google Artifact Registry. #### Example: Deploy from GitHub Container Registry ```bash mcpl deploy ghcr.io/user/mcp-image:latest \ --name prod-server \ --transport streamable-http \ -e API_KEY=sk-abc123 \ --server-profile medium \ -o json ``` #### Example: Deploy from Docker Hub with auth ```bash mcpl deploy docker.io/user/mcp-server:v1.2.0 \ --name docker-mcp \ --transport streamable-http \ --auth-type key \ --api-key-duration 30days \ -e DATABASE_URL=postgres://... \ --server-profile large \ -o json ``` #### Example: Deploy from Amazon ECR ```bash mcpl deploy 123456789.dkr.ecr.us-east-1.amazonaws.com/mcp-server:latest \ --name ecr-mcp \ --transport streamable-http \ -o json ``` > **Agent tip:** The image flow is best when you have a pre-built container or complex system-level dependencies. Make sure the image exposes the MCP server on port 8000 (default) or specify `--port` if different. --- ### Common Deployment Flags | Flag | Description | |------|-------------| | `--name` | Custom deployment name (DNS-1123: lowercase alphanumeric + hyphens). | | `--project` | Project ID or name (defaults to active project). | | `--transport` | Transport type: `stdio`, `streamable-http` (recommended), `sse`. | | `-e, --env` | Environment variables (e.g., `-e API_KEY=secret`). | | `--server-profile` | Compute profile: `small`, `medium`, `large`. | | `--auth-type` | Authentication: `oauth` (default), `key`, `none`. | | `--api-key-duration` | API key duration (e.g., `30days`) — only for `auth_type: key`. | | `--no-wait` | Return immediately without streaming build logs. | | `-o json` | JSON output for programmatic consumption. | **Git-only flags:** | Flag | Description | |------|-------------| | `--branch` | Git branch (defaults to repo's default branch). | | `--build-strategy` | `auto`, `dockerfile`, `pip`, `uv`, `poetry`, `npm`, `pnpm`, `go`. | | `--build-command` | Post-install build command (e.g., `npm run build`). | | `--install-command` | Override the default install step. | | `--run` | Command to start the MCP server (required if no `mcplambda.yaml`). | > **Agent tip:** Always use `-o json` for programmatic access. The JSON response includes the deployment `id`, `url`, `subdomain`, and `status` — everything you need to proceed to the next step. --- ## The MCPLambda MCP Server MCPLambda provides an **MCP server** at `api.mcplambda.io/mcp` that wraps the platform's deployment management capabilities. This allows AI agents to deploy and manage MCP servers **using MCP itself** — a meta-MCP approach. ### Connection Add the MCPLambda MCP server to your client config: ```json { "mcpServers": { "mcplambda": { "url": "https://api.mcplambda.io/mcp", "headers": { "Authorization": "Bearer mcpl_sat_abc123..." } } } } ``` > Use a service account token (`mcpl_sat_`) for authentication. ### Available Tools #### Deployment Management | Tool | Description | |------|-------------| | `list_deployments` | List all deployments in a project. | | `get_deployment` | Get details and status of a deployment. | | `create_deployment` | Deploy a new MCP server (package, git, or image). | | `delete_deployment` | Delete a deployment. | | `start_deployment` | Start a stopped deployment. | | `stop_deployment` | Stop a running deployment. | | `get_deployment_logs` | Fetch recent logs for a deployment. | | `get_deployment_api_key` | Retrieve the API key for a deployment (only for `auth_type: key`). | | `rotate_deployment_api_key` | Rotate the API key. | #### Project Management | Tool | Description | |------|-------------| | `list_projects` | List all projects. | | `create_project` | Create a new project. | #### Secret Management | Tool | Description | |------|-------------| | `list_secrets` | List project secrets (masked). | | `create_secret` | Create a project secret. | #### Registry | Tool | Description | |------|-------------| | `search_registry` | Search the MCP server registry. | | `get_registry_server` | Get details of a registry server. | ### Example Agent Interaction ```text User: "Deploy the MCP filesystem server for me." Agent (calls mcplambda MCP server): -> search_registry("filesystem") <- Found: @modelcontextprotocol/server-filesystem -> create_deployment( name: "filesystem-server", package_name: "npx://@modelcontextprotocol/server-filesystem", transport: "streamable-http", auth_type: "key", api_key_duration: unit: "days", value: 30 ) <- id: "dep-abc", url: "https://filesystem-server.mcplambda.io", status: "pending" -> get_deployment("dep-abc") // poll until running <- status: "running", url: "https://filesystem-server.mcplambda.io" -> get_deployment_api_key("dep-abc") <- api_key: "mcpl_live_...", key_prefix: "mcpl_li" Agent: "Done! Your filesystem server is deployed at https://filesystem-server.mcplambda.io/mcp. I've added it to your Claude Desktop config with the API key." ``` --- ## Retrieving Deployment URL & API Key After deployment, you need the **Deployment URL** to connect an AI client. You only need an **API Key** if you chose `auth_type: key` — with the default `oauth` auth, the client handles authentication automatically. ### Get Deployment URL ```bash mcpl deploy status my-server -o json ``` ```json { "id": "dep-abc123", "name": "my-server", "status": "running", "url": "https://my-server.mcplambda.io", "subdomain": "my-server", "transport": "streamable-http", "auth_type": "oauth" } ``` The `url` field is the full deployment URL. For `streamable-http` transport, append `/mcp` to get the MCP endpoint: `https://my-server.mcplambda.io/mcp`. ### Get API Key (only for `auth_type: key`) If the deployment was created with `auth_type: key`, retrieve the API key via the CLI: ```bash mcpl deploy api-key -o json ``` Response: ```json { "api_key": "mcpl_live_abc123...", "expires_at": "2026-12-07T00:00:00Z", "key_id": "key-xyz789", "key_prefix": "mcpl_li" } ``` > **Security:** The API key is returned in plaintext. Store it securely and never commit it to version control. The `key_prefix` is safe to log or display. ### Choosing an Auth Type When deploying, you can choose the authentication type for the **deployed server** (this is separate from the platform auth the agent uses): | Auth Type | Description | Best For | |-----------|-------------|----------| | `oauth` (default) | OAuth 2.1 with PKCE — users authenticate via browser. | Interactive clients (Cursor, Claude Desktop). No API key needed. | | `key` | API key with configurable expiry. | Agent-driven workflows, service-to-service. Requires key retrieval. | | `none` | No authentication (public). | Development, testing only. | > **Agent tip:** For agent-driven deployments where the agent itself will call the MCP server, use `auth_type: key` with a short duration (e.g., 30 days). For deployments where a human user will connect via Cursor or Claude Desktop, use the default `oauth` — the client handles auth automatically and no key retrieval is needed. --- ## Connecting to AI Clients Once you have the deployment URL (and API key if applicable), connect it to an AI client. ### Cursor 1. Open **Cursor Settings** > **General** > **MCP**. 2. Click **+ Add New MCP Server**. 3. **Name:** `mcpl-` 4. **Type:** `SSE` (Cursor uses this for all HTTP-based remote transports). 5. **URL:** `https://.mcplambda.io/mcp` 6. Click **Save**. ### Claude Desktop Add to `claude_desktop_config.json`: ```json { "mcpServers": { "mcpl-server": { "url": "https://my-server.mcplambda.io/mcp", "headers": { "Authorization": "Bearer mcpl_live_abc123..." } } } } ``` > For `oauth` auth type, the client handles the OAuth flow automatically. For `key` auth type, include the `Authorization` header. ### VSCode (Cline, Roo Code, Continue) 1. Open the extension's MCP settings. 2. Add a new server with type **SSE/HTTP**. 3. URL: `https://.mcplambda.io/mcp` 4. If using API key auth, add the `Authorization: Bearer ` header. ### Programmatic Connection (MCP SDK) ```python from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client url = "https://my-server.mcplambda.io/mcp" headers = {"Authorization": "Bearer mcpl_live_abc123..."} async with streamablehttp_client(url, headers=headers) as (read, write, _): async with ClientSession(read, write) as session: await session.initialize() tools = await session.list_tools() print(tools) ``` --- ## Managing Deployments ### List Deployments ```bash mcpl deploy list -o json ``` ### Update a Deployment ```bash mcpl deploy update my-server --env API_KEY=newvalue --transport streamable-http ``` ### Lifecycle Management ```bash mcpl deploy stop my-server # Scale to 0 mcpl deploy start my-server # Scale to 1 mcpl deploy restart my-server # Rolling restart mcpl deploy delete my-server # Permanently delete ``` ### View Logs ```bash mcpl deploy logs my-server # Tail live logs mcpl deploy logs my-server --since 5m # Last 5 minutes ``` ### Environment Variables & Secrets ```bash # View env vars for a deployment mcpl deploy env my-server -o json # Create a project secret mcpl secret create API_KEY my-secret-value # Reference secrets in deployments mcpl deploy npx://@mcp/server --secret-id ``` --- ## Security Best Practices for Agents When deploying MCP servers on behalf of users, follow these principles: ### 1. Least Privilege - Use `auth_type: key` with short durations (hours/days, not years). - Only expose the tools the user needs (use the `--tools` flag to allowlist specific tools). - Use `server_profile: small` unless the workload requires more resources. ### 2. Secret Management - Never hardcode API keys or secrets in deployment commands. - Use project secrets: `mcpl secret create API_KEY value` then reference by ID. - Use inline secrets for one-time use: `mcpl deploy ... --secret API_KEY=value`. - Mask sensitive values in logs and output. ### 3. Audit & Monitor - After deploying, check logs: `mcpl deploy logs `. - Monitor status: `mcpl deploy status --watch`. - Use the analytics endpoints to track tool invocations. ### 4. Cleanup - Stop unused deployments: `mcpl deploy stop `. - Delete deployments that are no longer needed: `mcpl deploy delete `. - Rotate API keys periodically by redeploying with a new key duration. --- ## JSON Output for Scripting All `mcpl` commands support `-o json` for structured output. This is essential for agent-driven workflows. ```bash # List deployments as JSON mcpl deploy list -o json | jq '.[].name' # Deploy and capture the response RESULT=$(mcpl deploy npx://@mcp/server-time --name my-timer -o json) URL=$(echo "$RESULT" | jq -r '.url') ID=$(echo "$RESULT" | jq -r '.id') # Wait for deployment to be ready mcpl deploy status "$ID" --watch -o json # Get the API key (only needed if auth_type=key) mcpl deploy api-key "$ID" -o json | jq -r '.api_key' ``` --- ## Full Agent Workflow Example Here is a complete end-to-end workflow that an AI agent can follow to deploy an MCP server and connect it to a user's client: ```bash #!/usr/bin/env bash set -euo pipefail # 1. Install mcpl CLI (if not already installed) if ! command -v mcpl &>/dev/null; then echo "Installing mcpl CLI..." curl -fsSL https://mcplambda.io/mcpl/install.sh | sh export PATH="$HOME/.local/bin:$PATH" fi # 2. Verify authentication AUTH=$(mcpl whoami -o json 2>/dev/null || echo '{}') if [ "$(echo "$AUTH" | jq -r '.authenticated')" != "true" ]; then echo "User is not authenticated. Please run: mcpl login" exit 1 fi PROJECT_ID=$(echo "$AUTH" | jq -r '.project_id') # 3. Deploy an MCP server with API key auth echo "Deploying MCP server..." DEPLOY_RESULT=$(mcpl deploy npx://@modelcontextprotocol/server-everything \ --name agent-everything \ --project "$PROJECT_ID" \ --transport streamable-http \ --auth-type key \ --api-key-duration 30days \ --server-profile small \ -o json) DEPLOY_ID=$(echo "$DEPLOY_RESULT" | jq -r '.id') DEPLOY_URL=$(echo "$DEPLOY_RESULT" | jq -r '.url') echo "Deployment created: $DEPLOY_URL (ID: $DEPLOY_ID)" # 4. Wait for the deployment to be ready echo "Waiting for deployment to be ready..." mcpl deploy status "$DEPLOY_ID" --watch # 5. Retrieve the API key (only needed because we used auth_type=key) API_KEY=$(mcpl deploy api-key "$DEPLOY_ID" -o json | jq -r '.api_key') echo "API Key: ${API_KEY:0:12}... (truncated for security)" # 6. Output the connection info MCP_URL="${DEPLOY_URL}/mcp" echo "" echo "=== Connection Info ===" echo "URL: $MCP_URL" echo "Auth: Bearer $API_KEY" echo "" echo "Add to Claude Desktop (claude_desktop_config.json):" cat < **Note:** The example above uses `auth_type: key` because the agent itself will be calling the MCP server. If deploying for a human user who will connect via Cursor or Claude Desktop, use the default `oauth` auth type and skip steps 5-6 — the client handles authentication automatically. --- ## CLI Command Summary All `mcpl` commands support `-o json` for structured output. | Command | Purpose | |---------|---------| | `mcpl login` | Authenticate (browser) | | `mcpl login --token ` | Authenticate (headless) — *proposed* | | `mcpl whoami -o json` | Check auth status | | `mcpl deploy -o json` | Deploy a server | | `mcpl deploy list -o json` | List deployments | | `mcpl deploy status -o json` | Get status | | `mcpl deploy status --watch` | Watch status until ready | | `mcpl deploy logs ` | Stream logs | | `mcpl deploy api-key -o json` | Get API key (only for `auth_type: key`) | | `mcpl deploy stop ` | Stop a deployment | | `mcpl deploy start ` | Start a deployment | | `mcpl deploy delete ` | Delete a deployment | | `mcpl deploy env -o json` | View env vars | | `mcpl secret create ` | Create a secret | | `mcpl secret list -o json` | List secrets | | `mcpl project list -o json` | List projects | | `mcpl project create ` | Create a project | --- ## Error Handling All errors follow a consistent format with an `error.code` field to determine the appropriate recovery action. **Common error codes:** | Code | Description | Agent Action | |------|-------------|--------------| | `unauthorized` | Token is invalid or expired. | Re-authenticate. | | `forbidden` | Token lacks required scope. | Request a token with broader scope. | | `not_found` | Resource doesn't exist. | Check the ID/name. | | `conflict` | Resource already exists (e.g., duplicate name). | Use a different name. | | `insufficient_units` | Not enough compute units. | Stop deployments or upgrade plan. | | `validation_error` | Invalid request. | Fix the validation errors. | | `rate_limited` | Too many requests. | Retry with exponential backoff. | > **Agent tip:** Always check the `error.code` field to determine the appropriate recovery action. --- ## Suggested Improvements for Agent-Driven Workflows The following improvements would make MCPLambda even more agent-friendly. ### 1. Headless Authentication - **`mcpl login --token `** — Authenticate with a service account token (no browser needed). - **`MCPL_API_TOKEN` env var** — Automatically authenticate CLI commands. - **OAuth Device Flow** — Non-browser flow for headless environments. ### 2. Deploy-and-Get-Key in One Step - **`mcpl deploy ... --return-api-key`** — Return the API key in the deployment JSON response, eliminating the need for a separate `api-key` call. Only relevant when `auth_type: key`. ### 3. Wait-for-Ready Flag - **`mcpl deploy ... --wait`** — Block until the deployment reaches `running` or `failed` (currently `--no-wait` does the opposite; a positive `--wait` flag would be more intuitive for agents). ### 4. Agent-Scoped Tokens - **Short-lived, scoped API tokens** — Tokens that can only deploy/manage, not billing or account settings. - **Per-deployment tokens** — Tokens scoped to a single deployment. ### 5. Key Rotation - **`mcpl deploy api-key rotate `** — Rotate the API key for a deployment, invalidating the old one and returning a new plaintext key. - **Multiple keys per deployment** — Allow multiple active API keys for zero-downtime rotation. - **Scoped keys** — API keys with tool-level scopes for least-privilege access.