Agent Guide: Deploying Remote MCP Servers

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:

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

Windows (PowerShell 5.1+):

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:

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

Verify installation:

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:

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)

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 <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:

mcpl whoami -o 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)

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)

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

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

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:

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:

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:

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

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:

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).

# 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

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

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

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

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

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:

{
  "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

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

mcpl deploy status my-server -o 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:

mcpl deploy api-key <deployment-id> -o json

Response:

{
  "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-<deployment-name>
4. Type: SSE (Cursor uses this for all HTTP-based remote transports).
5. URL: https://<deployment-name>.mcplambda.io/mcp
6. Click Save.

Claude Desktop

Add to claude_desktop_config.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://<deployment-name>.mcplambda.io/mcp
4. If using API key auth, add the Authorization: Bearer <key> header.

Programmatic Connection (MCP SDK)

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

mcpl deploy list -o json

Update a Deployment

mcpl deploy update my-server --env API_KEY=newvalue --transport streamable-http

Lifecycle Management

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

mcpl deploy logs my-server           # Tail live logs
mcpl deploy logs my-server --since 5m  # Last 5 minutes

Environment Variables & Secrets

# 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 <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 <name>.
• Monitor status: mcpl deploy status <name> --watch.
• Use the analytics endpoints to track tool invocations.

4. Cleanup

• Stop unused deployments: mcpl deploy stop <name>.
• Delete deployments that are no longer needed: mcpl deploy delete <name>.
• 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.

# 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:

#!/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 <<EOF
{
  "mcpServers": {
    "mcpl-everything": {
      "url": "$MCP_URL",
      "headers": {
        "Authorization": "Bearer $API_KEY"
      }
    }
  }
}
EOF

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 <TOKEN>	Authenticate (headless) — proposed
mcpl whoami -o json	Check auth status
mcpl deploy <source> -o json	Deploy a server
mcpl deploy list -o json	List deployments
mcpl deploy status <name> -o json	Get status
mcpl deploy status <name> --watch	Watch status until ready
mcpl deploy logs <name>	Stream logs
mcpl deploy api-key <id> -o json	Get API key (only for auth_type: key)
mcpl deploy stop <name>	Stop a deployment
mcpl deploy start <name>	Start a deployment
mcpl deploy delete <name>	Delete a deployment
mcpl deploy env <name> -o json	View env vars
mcpl secret create <KEY> <VALUE>	Create a secret
mcpl secret list -o json	List secrets
mcpl project list -o json	List projects
mcpl project create <name>	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 <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 <id> — 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.