Custom MCP Servers

Runlayer Deploy enables you to deploy custom MCP servers to managed infrastructure with automatic scaling, monitoring, and HTTPS endpoints.

Create and manage deployment-backed connectors from Connectors. The previous Deploy page is no longer in the navigation.

Want to build and deploy your MCP server automatically with your agent? Start with the MCP Builder Quickstart. That flow uses Runlayer MCP + MCP Builder on top of Runlayer Deploy.

When to use Runlayer Deploy:

Deploy custom MCP servers not already available as connectors
Build internal or proprietary integrations
Run services requiring specific dependencies or configurations

Prerequisites

Before deploying, ensure you have:

Docker installed and running locally
Runlayer CLI installed (uvx runlayer)
A Dockerfile and application code ready to deploy

Non-admin users can request deploy-based MCP servers through the connectors flow. The request follows the standard approval workflow. Direct deployment via the CLI needs the Access Runlayer deploy or Add/edit/delete MCPs capability, which the built-in Developer, IT Admin and Super Admin roles have; it does not go through an approval. The new connector is granted to everyone with the Developer role by default. See Roles.

Quick Start

Authenticate the CLI with your Runlayer instance:

uvx runlayer login --host <runlayer-url>

Create the connector

Open Connectors. Select Add Connector → Deploy an MCP server on Runlayer → Create from manifest.Enter the connector details. Runlayer creates the connector with Draft status and opens its Manifest tab.

Pull the manifest

Copy the deployment ID from the Manifest tab. Then run:

uvx runlayer deploy pull --deployment-id <deployment-id> --host <runlayer-url>

This command creates a local runlayer.yaml file.

Configure Service

Edit the generated runlayer.yaml file:

Set your service port
Choose CPU and memory resources
Add environment variables
Configure build settings for your Dockerfile

Deploy

Build and deploy your service:

uvx runlayer deploy --config runlayer.yaml --host <runlayer-url>

After the first deployment succeeds, Runlayer changes the connector from Draft to Active. No separate publish or registration step is required.To change configuration later, see Updating a deployment.

Runtimes

Docker

The Docker runtime builds your application locally using Docker and deploys it as a container. This gives you full control over dependencies and supports any language or framework. Build Configuration:

dockerfile: Path to your Dockerfile (default: Dockerfile)
context: Build context directory (default: .)
platform: CPU architecture - x86 or arm (default: arm, recommended for cost savings)
args: Build arguments as key-value pairs
target: Target stage for multi-stage builds (optional)

Coming Soon

Managed Runtimes for Python and TypeScript—deploy with just your code and dependencies.

Configuration Reference

Complete runlayer.yaml structure:

id: <uuid>              # Auto-generated, do not modify
name: my-service        # Lowercase, URL-friendly name
runtime: docker         # Currently only "docker" is supported

build:
  dockerfile: Dockerfile
  context: .
  platform: arm         # "arm" or "x86" (arm recommended)
  target: null          # Optional: multi-stage build target
  args: {}              # Build arguments (key-value pairs)

service:
  port: 8000           # Container port your app listens on
  path: /mcp           # URL path prefix (optional)
  expose: []           # OAuth-only unauthenticated paths (optional)

infrastructure:
  cpu: 512             # CPU units
  memory: 1024         # Memory in MB
  platform: arm        # CPU architecture (must match build.platform)
  enable_db: false     # Enable database storage
  aws:                 # AWS config (hosted deployments only)
    assume_roles: {}   # Named map of IAM role ARNs to assume
  private_connections: []  # Private network connections the server can use (optional)

env: {}                # Environment variables (key-value pairs)

Field Details

service.expose Allow unauthenticated access to OAuth routes your deployed MCP server implements. Omit service.expose for non-OAuth servers. Use this only for OAuth discovery and OAuth protocol endpoints that must be reachable before a client has a Runlayer Bearer token:

service:
  port: 8000
  path: /mcp
  expose:
    - "/.well-known/*"
    - "/register"
    - "/authorize"
    - "/token"
    - "/revoke"

Exposed paths bypass Runlayer authentication. Do not use Deploy to publish arbitrary unauthenticated HTTP routes, APIs, webhooks, or probes. MCP endpoints (service.path, /mcp, and legacy /sse) must stay authenticated and should not be listed in service.expose.

infrastructure Valid CPU and memory combinations:

CPU (vCPU)	Memory Options (MB)	Best For
256 (.25 vCPU)	512, 1024, 2048	Minimal services
512 (.5 vCPU)	1024, 2048, 3072, 4096	Light services
1024 (1 vCPU)	2048, 3072, 4096, 5120, 6144, 7168, 8192	Standard services
2048 (2 vCPU)	4096-16384 (1024 MB increments)	Medium workloads
4096 (4 vCPU)	8192-30720 (1024 MB increments)	Heavy workloads

See AWS Fargate pricing for cost estimates.

infrastructure.platform CPU architecture for the container runtime: x86 or arm.

In build mode: Defaults to build.platform. If explicitly set, must match build.platform or validation will fail.
In image mode: Defaults to x86 if not specified. Set this to match the architecture of your pre-built Docker image.

infrastructure.scaling Run more than one copy (replica) of the server, at a fixed count or autoscaled between bounds. Available for ECS deployments. Without the block a new deployment runs one task; on an update, omitting it keeps the stored scaling, and scaling: null resets to one task.

infrastructure:
  cpu: 512
  memory: 1024
  scaling:
    min_replicas: 2       # always running
    max_replicas: 6       # up to 8
    target_cpu_percent: 60              # optional, default 60
    target_network_mib_per_second: 5    # optional, per replica, default 5

Field	Default	Description
`min_replicas`	1	Replicas that always run
`max_replicas`	1	Upper bound, at most 8. Above `min_replicas`, Runlayer adds or removes replicas to hold average CPU and network throughput per replica at their targets
`target_cpu_percent`	60	Average CPU per replica to hold, 10–90, as a percentage of the replica’s own `cpu`. At `cpu: 2048` and 60%, a replica scales out once about 1.2 vCPU is busy
`target_network_mib_per_second`	5	Average received plus sent MiB per second per replica to hold. Needs ECS Container Insights on the cluster; without it, scaling follows CPU only

Set min_replicas equal to max_replicas for a fixed count. Autoscaling (max_replicas above min_replicas) needs a Runlayer installation whose deploy worker may read service metrics; validation says so when it doesn’t. More than one replica needs a Runlayer backend that reaches Deploy services directly: when the backend sends HTTP through HTTP_PROXY, HTTPS_PROXY or ALL_PROXY, Runlayer rejects max_replicas above 1 when you save and again on every deploy, because requests of one session could land on different replicas (NO_PROXY doesn’t help). Every request of one MCP session reaches the same replica. A replica must not depend on state kept in memory by another replica: keep shared state, such as OAuth tokens, in the managed database (infrastructure.enable_db). When a replica is removed, it stops receiving new sessions and gets SIGTERM, and Runlayer allows a grace period for it to exit. A server that finishes its in-flight requests before exiting keeps those calls; a server that exits immediately cancels them, and clients see the call fail. Stdio connectors that Runlayer wraps for you currently exit promptly on SIGTERM, so a call in flight on a removed replica fails; the same happens on every redeploy, with or without scaling. infrastructure.enable_db Enable a managed database for persistent storage. The provisioned backend depends on where Runlayer Deploy runs:

Runlayer-hosted (ECS): a real AWS DynamoDB table, with TOKEN_ENCRYPTION_KMS_KEY_ID + TOKEN_ENCRYPTION_MODE injected for application-layer encryption (see below).
Self-hosted on Kubernetes: ExtendDB, a DynamoDB-wire-protocol adapter backed by the instance’s own PostgreSQL, run by runlayer-operator over HTTPS in-cluster. Requires the instance’s ExtendDB component to be enabled and reporting ExtendDBReady — enable_db deployments are rejected otherwise. ExtendDBReady means the adapter Deployment is up, credentials exist, and its readiness probe’s last Postgres connectivity check (both catalog and data databases) succeeded — that check is cached for up to 5 minutes, so it is not a live guarantee between checks. All enable_db MCPs on an instance share one SigV4 access key: table names separate which table each MCP uses, but not who can call SigV4 — any enable_db MCP (or anyone with that Secret) can read or overwrite another MCP’s stored tokens on that adapter until per-MCP keys land. Disabling ExtendDB is blocked while any MCP still has enable_db: true — clear those first (undeploy deletes the table).
Local Docker (dev only): DynamoDB Local.

In every case your container gets the same table-level environment variables:

DB_TABLE_NAME - The table name
DB_TABLE_REGION - The AWS region (Kubernetes/local use a fixed region since there is no real AWS table)

On Kubernetes you additionally get AWS_ENDPOINT_URL_DYNAMODB (HTTPS to the in-cluster adapter), profile-scoped SigV4 auth (EXTENDDB_AWS_PROFILE=extenddb, plus EXTENDDB_AWS_SHARED_CREDENTIALS_FILE / EXTENDDB_AWS_CONFIG_FILE pointing at the mounted profile files — not process-wide AWS_CONFIG_FILE). Do not rely on the global AWS_ENDPOINT_URL.

How the MCP authenticates to ExtendDB (Kubernetes)

The pod talks DynamoDB protocol over HTTPS to the in-cluster ExtendDB Service. ExtendDB verifies SigV4 on each request. On Kubernetes, the operator mounts the shared access key and CA as AWS profile extenddb and sets EXTENDDB_AWS_PROFILE — keys and AWS_CA_BUNDLE are not exported on the default chain, so IRSA (eks.amazonaws.com/role-arn on the MCP ServiceAccount) can coexist for other AWS APIs. GKE Workload Identity (iam.gke.io/gcp-service-account) is unchanged. ECS and local Docker still use the default session (task role or DynamoDB Local); they never set EXTENDDB_AWS_PROFILE.

Image requirement: A default-session boto3.client("dynamodb") no longer works on Kubernetes after the operator profile change. Every enable_db image must follow the selection rule below (Runlayer connector images ship this in mcps-by-runlayer). Upgrade connector images before or with the operator bump.

Use this selection rule in the image:

If EXTENDDB_AWS_PROFILE is set (Kubernetes): build the DynamoDB client from that profile using the operator-mounted file paths (EXTENDDB_AWS_SHARED_CREDENTIALS_FILE, EXTENDDB_AWS_CONFIG_FILE). Botocore does not read those env vars by itself — point a botocore.session.Session at the files, then wrap it in boto3.Session (see snippet below).
If it is unset (ECS or local Docker): use a normal default-session Dynamo client.
Keep other AWS clients on the default chain (IRSA) — do not set process-wide AWS_PROFILE or put the ExtendDB key back into AWS_ACCESS_KEY_ID.
On Kubernetes, trust ExtendDB TLS via the profile’s ca_bundle (or the client’s CA config), not process-wide AWS_CA_BUNDLE.
Keep using AWS_ENDPOINT_URL_DYNAMODB (Kubernetes), DB_TABLE_NAME, and DB_TABLE_REGION.

Table contract and example

On ECS only, you additionally get:

TOKEN_ENCRYPTION_KMS_KEY_ID - The ARN of the environment’s customer-managed KMS key for application-layer encryption
TOKEN_ENCRYPTION_MODE - encrypted on new deployments; absent (bridge) on older deployments, which keep their mode

The deployment task role can call kms:GenerateDataKey and kms:Decrypt on that key, which has automatic rotation enabled.

No KMS on self-hosted Kubernetes (v1): TOKEN_ENCRYPTION_KMS_KEY_ID is not set for K8S enable_db deployments — ExtendDB v1 ships without a customer-managed-key equivalent. Encrypt sensitive fields yourself if you need application-layer encryption on self-hosted Kubernetes.

The table uses a partition key (pk) and sort key (sk) schema. TTL is enabled via the ttl attribute (set to a Unix timestamp to auto-expire items). Use any standard DynamoDB client to interact with the table—boto3 (Python), AWS SDK (Node.js), or any AWS SDK. All standard DynamoDB operations are supported: GetItem, PutItem, Query, Scan, BatchGetItem, BatchWriteItem, etc. On self-hosted Kubernetes, the SDK must honor service-specific endpoint env vars (AWS_ENDPOINT_URL_DYNAMODB, not the global AWS_ENDPOINT_URL) — botocore ≥ 1.31.0 / boto3 ≥ 1.28.0 (or AWS SDK for JavaScript v3+, Java 2.x, Go v2). Older SDKs need a bump or an explicit Dynamo client endpoint. The table is encrypted at rest on ECS and local Docker; ExtendDB on self-hosted Kubernetes terminates TLS at the adapter but does not separately encrypt Postgres at rest beyond your database’s own configuration. Application-layer encryption is opt-in for custom data on every backend. Encrypt sensitive values before writing them; the OAuth guide describes automatic token encryption in Runlayer’s auth framework. Example MCP tool with persistence (Python): This default-session example is correct for ECS and local Docker only. On Kubernetes, gate on EXTENDDB_AWS_PROFILE as in How the MCP authenticates to ExtendDB — do not hardcode profile_name="extenddb" (that breaks ECS).

import os
import boto3
import botocore.session
from typing import Any

def dynamodb_resource():
    profile = os.environ.get("EXTENDDB_AWS_PROFILE")
    if not profile:
        return boto3.resource("dynamodb", region_name=os.environ.get("DB_TABLE_REGION"))
    botocore_session = botocore.session.Session()
    botocore_session.set_config_variable("credentials_file", os.environ["EXTENDDB_AWS_SHARED_CREDENTIALS_FILE"])
    botocore_session.set_config_variable("config_file", os.environ["EXTENDDB_AWS_CONFIG_FILE"])
    session = boto3.Session(botocore_session=botocore_session, profile_name=profile)
    return session.resource(
        "dynamodb",
        region_name=os.environ.get("DB_TABLE_REGION"),
        endpoint_url=os.environ.get("AWS_ENDPOINT_URL_DYNAMODB"),
    )

dynamodb = dynamodb_resource()

@mcp.tool
def add_item(pk: str, sk: str, data: dict[str, Any]) -> dict:
    """Add an item to the database."""
    table_name = os.environ.get("DB_TABLE_NAME")
    if not table_name:
        return {"error": "DB_TABLE_NAME not set"}

    table = dynamodb.Table(table_name)
    item = {"pk": pk, "sk": sk, **data}

    try:
        table.put_item(Item=item)
        return {"success": True, "item": item}
    except Exception as e:
        return {"success": False, "error": str(e)}

Irreversible: Once enable_db is set to true and deployed, it cannot be disabled. Attempting to set it back to false will fail validation to prevent data loss.

Building a deployed server that needs OAuth with a third-party service (e.g., Slack, Google)? See the OAuth for Deployed MCP Servers guide for the dual-auth architecture and token storage patterns.

Private connections

Use infrastructure.private_connections when your deployed server needs to reach a system that isn’t on the public internet, such as an internal API or database. This works on Runlayer-hosted and self-hosted ECS deployments, but not on self-hosted Kubernetes. First, an admin creates a tunnel or AWS PrivateLink connection in Settings → Network Access. See private connectivity for what each kind is and how to set it up. Then add the connection’s name to your runlayer.yaml:

infrastructure:
  private_connections:
    - acme-api

Runlayer creates an environment variable on your server that holds the connection’s private address. Runlayer names it after the connection: for acme-api, the variable is PRIVATE_CONNECTION_ACME_API_DNS. Your code reads it to know where to send requests, on one of the ports set on the connection. To name the variable yourself, add hostname_env. This entry puts the address in ACME_DB_HOST:

infrastructure:
  private_connections:
    - name: acme-db
      hostname_env: ACME_DB_HOST

Unlike settings such as scaling, private_connections doesn’t keep its current value when you leave it out. If you deploy again without it in your runlayer.yaml, the server loses all its connections.

AWS cross-account roles (hosted only)

Use infrastructure.aws.assume_roles when a hosted connector needs to call AWS APIs in your account without storing long-lived access keys in env. This applies only to Runlayer-hosted ECS deployments—not remote or local catalog connectors. How it works

You declare customer role ARNs in infrastructure.aws.assume_roles.
Runlayer provisions a dedicated ECS task role per deployment in the Runlayer-hosted AWS account.
The connector container runs with that task role and calls sts:AssumeRole on your roles using ExternalId = <deployment-id>.
Runlayer does not broker STS or store static AWS keys.

Runlayer-side config

infrastructure:
  aws:
    assume_roles:
      secrets: arn:aws:iam::123456789012:role/acme-mcp-secrets-reader
      blobs: arn:aws:iam::123456789012:role/acme-mcp-s3-reader

Runtime environment variables

Variable	Description
`RUNLAYER_DEPLOYMENT_ID`	Deployment UUID — pass as `ExternalId` when assuming customer roles
`RUNLAYER_DEPLOYMENT_TASK_ROLE_ARN`	This deployment’s ECS task role — the principal your trust policy must allow
`RUNLAYER_AWS_ROLE_<NAME>`	Customer role ARN for map key `<NAME>` (uppercased, e.g. `secrets` → `RUNLAYER_AWS_ROLE_SECRETS`)

Customer setup checklist (per role ARN)

Step	Action
1	Create or choose a least-privilege IAM role in your AWS account
2	Attach a permissions policy granting only what the connector needs (S3, Secrets Manager, etc.)
3	Add a trust policy allowing only the Runlayer deployment task role ARN with `sts:ExternalId` = deployment UUID
4	Add the role ARN to `infrastructure.aws.assume_roles.<name>` in `runlayer.yaml`
5	Deploy and copy `task_role_arn` from CLI output, deployment page, or API

Where to find the assuming principal

Source	Field
`runlayer deploy` success output	`task_role_arn`
Deployment API / dashboard	`task_role_arn`
Running container	`RUNLAYER_DEPLOYMENT_TASK_ROLE_ARN`

task_role_arn is per deployment and stable across redeploys. Use it as the sole Principal.AWS in your trust policy—not the Runlayer AWS account ID or a broad shared role. Trust policy template

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowRunlayerDeploymentTaskRole",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<RUNLAYER_DEPLOYMENT_TASK_ROLE_ARN>"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<deployment-uuid>"
        }
      }
    }
  ]
}

<RUNLAYER_DEPLOYMENT_TASK_ROLE_ARN> — from deploy output / API / RUNLAYER_DEPLOYMENT_TASK_ROLE_ARN env var
<deployment-uuid> — the id in runlayer.yaml (same as RUNLAYER_DEPLOYMENT_ID)

Trust vs permissions

Trust policy — who can assume the role (the Runlayer deployment task role only)
Permissions policy — what the connector can do after assume (your data-plane access)

Troubleshooting Deploy succeeds once Runlayer infrastructure is provisioned; runtime AssumeRole errors are authoritative if your customer trust policy is not ready yet. Common issues: wrong principal (account root instead of task_role_arn), missing or incorrect ExternalId, typo in role ARN.

Scope trust policies to the deployment’s task_role_arn. Do not grant broad Runlayer account access. Use least-privilege permissions policies on customer roles.

env Environment variables are passed to your container at runtime. Values are automatically masked as *** in stored configurations and API responses for security. env values are passed to the container as-is. Secret store references (secretref://...) are not resolved here, so Runlayer rejects them; to keep a credential in your own AWS account, read it at runtime with AWS cross-account roles. CLI Variable Substitution: The CLI supports shell-style environment variable substitution when loading runlayer.yaml, allowing you to reference local environment variables or .env files without hardcoding sensitive values. Syntax:

${VAR} - Required variable (deployment fails if not set)
${VAR:-default} - Use default value if variable is unset or empty
${VAR-default} - Use default value only if variable is unset (not if empty)
$$DEPLOYMENT_URL - Special backend variable - your deployment’s public URL (backend replaces at runtime)
$$RUNLAYER_URL - Special backend variable - the Runlayer platform URL
$$RUNLAYER_OAUTH_CALLBACK_URL - Special backend variable - OAuth callback URL for integrations

$$DEPLOYMENT_URL is a special variable that resolves to your deployment’s URL. OAuth servers commonly use it as their issuer/base URL.

Example with CLI substitution:

env:
  DATABASE_URL: ${DATABASE_URL}                # Required from environment
  API_KEY: ${API_KEY}                          # Required from environment
  LOG_LEVEL: ${LOG_LEVEL:-info}                # Defaults to 'info'
  DEBUG: ${DEBUG:-false}                       # Defaults to 'false'
  CALLBACK_URL: $$DEPLOYMENT_URL/callback   # Backend replaces with deployment URL

Loading variables:

# From environment
export DATABASE_URL=postgres://localhost/db
export API_KEY=secret123
uvx runlayer deploy --host <runlayer-url>

# From .env file (auto-discovered)
# Place .env next to runlayer.yaml or in current directory
uvx runlayer deploy --host <runlayer-url>

# From specific .env file
uvx runlayer deploy --host <runlayer-url> --env-file .env.prod

Auto-discovery: The CLI automatically searches for .env in your current working directory. Automatic Environment Variables: The backend automatically injects the following variables into your container:

DEPLOYMENT_URL - Your deployment URL: https://your-platform.com/api/v1/proxy/hosted/{deployment_id}
RUNLAYER_URL - The Runlayer platform URL
RUNLAYER_OAUTH_CALLBACK_URL - OAuth callback URL: https://your-platform.com/oauth/callback

This allows OAuth-aware services to know their deployment URL and build issuer or callback metadata. Backend Placeholder Replacement: Use $$DEPLOYMENT_URL (double dollar sign) as a placeholder in your YAML configuration. The backend replaces this at deployment time with your deployment URL. Example:

service:
  port: 8000
  path: /mcp
  expose:
    - "/.well-known/*"
    - "/authorize"
    - "/token"

env:
  # Backend replaces $$DEPLOYMENT_URL with actual deployment URL
  OAUTH_ISSUER: "$$DEPLOYMENT_URL"

At runtime, this becomes:

OAUTH_ISSUER: https://your-platform.com/api/v1/proxy/hosted/{deployment_id}

Important: Use double $$ ($$DEPLOYMENT_URL), not single $.

CLI Commands

CI/CD with organization API keys

For automated deploy pipelines, create an organization API key with the Deploy role in Settings → Organization API keys. Deploy-scoped organization keys can initialize, validate, deploy, pull, and destroy deployments without being tied to a user session. You can pass the key directly:

uvx runlayer deploy --config runlayer.yaml --host <runlayer-url> --secret <org-api-key>

Or store it locally under a name and reference it in deploy commands:

uvx runlayer org-api-key add ci-deploy --host <runlayer-url>
uvx runlayer --org-api-key ci-deploy deploy --config runlayer.yaml --host <runlayer-url>

Organization API keys can manage deployment records and infrastructure. They cannot activate a Draft connector because activation requires a user session.

Run the first deployment with a user session. After the connector becomes Active, use an organization API key for later CI/CD deployments.

`deploy init` (alternate entry point)

Use deploy init to start from the CLI instead of the Connectors page.

uvx runlayer login --host <runlayer-url>
uvx runlayer deploy init --host <runlayer-url>

What it does:

Creates a deployment and its linked connector with Draft status
Generates a runlayer.yaml template with your deployment ID
Prompts for deployment name (must be lowercase and URL-friendly)

The first successful deployment with a user session changes the connector from Draft to Active. Options:

--config, -c: Path to create config file (default: runlayer.yaml)
--secret, -s: API key override (optional; prefer uvx runlayer login)
--host, -H: Runlayer instance URL (required)

`deploy`

Build and deploy your service.

uvx runlayer deploy --config runlayer.yaml --host <runlayer-url>

What it does:

Loads environment variables from .env (auto-discovered) or --env-file
Substitutes variables in your YAML configuration
Validates your YAML configuration
Builds Docker image locally using your Dockerfile
Pushes image to managed registry
Deploys infrastructure
Monitors deployment with live log streaming
Prints the deployment URL so you can open it directly

Options:

--config, -c: Path to config file (default: runlayer.yaml)
--secret, -s: API key override (optional; prefer uvx runlayer login)
--host, -H: Runlayer instance URL (required)
--env-file, -e: Path to .env file for variable substitution (optional, auto-discovers .env by default)

`deploy validate`

Validate configuration without deploying.

uvx runlayer deploy validate --config runlayer.yaml --host <runlayer-url>

Checks YAML syntax and validates against backend schema. Useful for CI/CD pipelines or pre-deployment validation. Options:

--config, -c: Path to config file (default: runlayer.yaml)
--secret, -s: API key override (optional; prefer uvx runlayer login)
--host, -H: Runlayer instance URL (required)
--env-file, -e: Path to .env file for variable substitution (optional, auto-discovers .env by default)

`deploy pull`

Fetch the current deployment configuration from the backend and save it as a local runlayer.yaml.

uvx runlayer deploy pull --deployment-id <deployment-id> --host <runlayer-url>

What it does:

Uses --deployment-id, or reads the deployment ID from an existing runlayer.yaml
Creates a timestamped backup of the current file (if present)
Downloads the latest configuration and writes it locally

Environment variables appear as ${VAR_NAME} placeholders; backend variables like $$DEPLOYMENT_URL are preserved as-is. Options:

--config, -c: Path to save config file (default: runlayer.yaml)
--deployment-id, -d: Deployment ID (overrides config file)
--secret, -s: API key override (optional; prefer uvx runlayer login)
--host, -H: Runlayer instance URL (required)

Updating a deployment

Configuration changes are made through the CLI, not the web UI:

Get the current configuration — use your local runlayer.yaml, or fetch the latest with deploy pull (see above)
Edit the YAML — port, CPU/memory, environment variables, build settings, exposed paths, etc.
Redeploy with uvx runlayer deploy --config runlayer.yaml --host <runlayer-url>

The UI supports a smaller set of post-deployment actions:

Action	Where
Rename deployment, change icon	Deployment settings dialog
Redeploy the current configuration (e.g. after fixing an external dependency)	Redeploy action on the deployment detail page
Delete deployment	Deployment detail page

The deployment settings dialog only edits the display name and icon. All runlayer.yaml fields (service, build, infrastructure, env) require the CLI edit-and-redeploy workflow above.

`deploy destroy`

Teardown deployment and destroy infrastructure.

uvx runlayer deploy destroy --config runlayer.yaml --host <runlayer-url>

This action is destructive and cannot be undone. All infrastructure resources will be permanently deleted.

If the deployment has connected MCP servers, the UI will show them and offer a Delete All option that removes the deployment and its connected servers in one step (requires permission to delete those servers). Without permission, you must ask the connector owner to disconnect them first. Options:

--config, -c: Path to config file containing deployment ID
--deployment-id, -d: Deployment ID (overrides config file)
--secret, -s: API key override (optional; prefer uvx runlayer login)
--host, -H: Runlayer instance URL (required)

Examples

Example: Multi-stage Node.js Build with legacy SSE transport

TypeScript MCP server with build arguments and optimized production build:

name: custom-mcp
runtime: docker

build:
  dockerfile: Dockerfile
  context: .
  platform: x86
  target: production
  args:
    NODE_VERSION: "20"

service:
  port: 3000
  path: /sse

infrastructure:
  cpu: 1024
  memory: 2048

env:
  NODE_ENV: "production"

Example: Environment Variable Substitution

Production MCP server with secrets loaded from .env file: runlayer.yaml:

name: production-mcp
runtime: docker

build:
  dockerfile: Dockerfile
  context: .
  platform: arm

service:
  port: 8000
  path: /mcp

infrastructure:
  cpu: 1024
  memory: 2048

env:
  # Required variables (CLI substitutes from .env file)
  DATABASE_URL: ${DATABASE_URL}
  API_KEY: ${API_KEY}
  JWT_SECRET: ${JWT_SECRET}

  # Variables with defaults (CLI substitutes with fallback)
  LOG_LEVEL: ${LOG_LEVEL:-info}
  DEBUG: ${DEBUG:-false}
  WORKERS: ${WORKERS:-4}

  # Special backend variable
  BASE_URL: $$DEPLOYMENT_URL

.env:

DATABASE_URL=postgres://prod-db.example.com:5432/myapp
API_KEY=prod_key_12345
JWT_SECRET=super_secret_jwt_key
LOG_LEVEL=warn
WORKERS=8

Deploy:

# Uses .env automatically (same directory as runlayer.yaml)
uvx runlayer deploy --host <runlayer-url>

# Or specify explicitly
uvx runlayer deploy --host <runlayer-url> --env-file .env.production

Timing matters: CLI substitution (${VAR}) happens before sending to backend. Backend substitution ($$DEPLOYMENT_URL) happens at deployment time. This means validation errors will show CLI-substituted values, but $$DEPLOYMENT_URL remains as-is until the backend deploys your service.

Example: OAuth MCP Server

OAuth-enabled MCP server with unauthenticated OAuth routes:

name: oauth-mcp
runtime: docker

build:
  dockerfile: Dockerfile
  context: .
  platform: arm

service:
  port: 8000
  path: /mcp
  expose:
    - "/.well-known/*"
    - "/register"
    - "/authorize"
    - "/token"
    - "/revoke"

infrastructure:
  cpu: 512
  memory: 1024

env:
  OAUTH_CLIENT_ID: "${OAUTH_CLIENT_ID}"
  OAUTH_CLIENT_SECRET: "${OAUTH_CLIENT_SECRET}"
  OAUTH_REDIRECT_URIS: "$$RUNLAYER_OAUTH_CALLBACK_URL"
  BASE_URL: "$$DEPLOYMENT_URL"

Connector Status

Runlayer creates the connector before the first deployment. It appears in Connectors with Draft status, shown as Setup required in the table. The first successful deployment changes the same connector to Active. Runlayer keeps its connector ID and endpoint. You do not need to publish or register it separately. While the connector is in Draft, only its creator can see it. Users cannot connect to it. If a deployment fails, open the connector’s Manifest tab to review its deployment runs and logs.

Identity Forward

When enabled on any HTTP-based MCP connector (Streaming HTTP or SSE), the Runlayer proxy injects the authenticated caller’s identity into upstream HTTP requests. Your server reads it to scope data per user, write meaningful audit logs, enforce per-user rate limits, or personalize responses. Identity Forward works on catalog connectors, manually added connectors, and deployed connectors alike — it is not limited to Runlayer Deploy. There are two independent toggles:

Toggle	Carries	When to use
Forward identity headers	Plain `X-Runlayer-*` headers. Read them directly — no SDK, no verification.	Upstreams you fully control on a trusted network path.
Forward signed identity token (preferred)	A short-lived Runlayer-signed JWT in `X-Runlayer-Identity-Token`, verifiable via JWKS.	Any upstream you want to cryptographically prove the call came through Runlayer.

The toggles are independent and may be enabled together during a migration. Prefer the signed token whenever the path between Runlayer and the upstream isn’t fully trusted.

Plain headers are network-trust only. Anything that can reach the upstream URL directly could spoof them. The signed token option closes that gap — see Verifying the signed token below.
Identity is NOT a substitute for authorization. Enforce permissions in Runlayer policies and your server logic.
Runlayer reserves the identity header names (X-Runlayer-Subject-Type, X-Runlayer-Org-Id, X-Runlayer-User-Email, X-Runlayer-User-Id, X-Runlayer-Agent-Id, X-Runlayer-Agent-Name, X-Runlayer-Identity-Token). They are stripped from any admin-configured headers, placeholder substitution, and headers the caller sends to Runlayer before the request is sent, then re-injected by the proxy when the corresponding toggle is on. Other X-Runlayer-* headers (e.g. X-Runlayer-Custom-Foo) are admin-defined and pass through untouched.
Header / claim values are never written to Runlayer proxy request logs (only a boolean identity_forward_applied, the subject type, and which mode was applied are logged).
Both toggles are off by default and admin-only. Enabling sends end-user emails / agent identifiers to the upstream server — accept responsibility per your privacy policy.

Headers sent

Header	Description	Sent for
`X-Runlayer-Subject-Type`	One of `user`, `agent`, `obo`	always
`X-Runlayer-Org-Id`	Runlayer organization UUID	always
`X-Runlayer-User-Email`	End-user email	`user`, `obo`
`X-Runlayer-User-Id`	Runlayer user UUID	`user`, `obo`
`X-Runlayer-Agent-Id`	Agent account UUID	`agent`, `obo`
`X-Runlayer-Agent-Name`	Agent display name	`agent`, `obo`

Subject types

Subject type	When it occurs
`user`	A human end-user calling directly through their MCP client (Cursor, Claude Desktop, etc.).
`agent`	A standalone agent account (machine-to-machine) calling with its own credentials. No human in the loop.
`obo`	An agent calling on behalf of a delegating user. Both agent identity and the delegator’s user identity are forwarded.

Example requests

Human user:

POST /mcp HTTP/1.1
Host: my-server.deploy.runlayer.com
X-Runlayer-Subject-Type: user
X-Runlayer-Org-Id: 9f3a...
X-Runlayer-User-Email: jane@acme.com
X-Runlayer-User-Id: 7b1c...

Standalone agent (m2m):

POST /mcp HTTP/1.1
Host: my-server.deploy.runlayer.com
X-Runlayer-Subject-Type: agent
X-Runlayer-Org-Id: 9f3a...
X-Runlayer-Agent-Id: a4d2...
X-Runlayer-Agent-Name: nightly-reporter

Agent on-behalf-of a user (OBO):

POST /mcp HTTP/1.1
Host: my-server.deploy.runlayer.com
X-Runlayer-Subject-Type: obo
X-Runlayer-Org-Id: 9f3a...
X-Runlayer-User-Email: jane@acme.com
X-Runlayer-User-Id: 7b1c...
X-Runlayer-Agent-Id: a4d2...
X-Runlayer-Agent-Name: jane-research-agent

Signed identity token

When Forward signed identity token is enabled, Runlayer mints a short-lived JWT for every upstream request and sends it as:

X-Runlayer-Identity-Token: <jwt>

Verify it with any standard JWT library against the JWKS Runlayer publishes:

GET https://<your-runlayer>/.well-known/runlayer-identity-forward.jwks.json

Token shape:

Claim	Value
`alg` (header)	`EdDSA`
`kid` (header)	Stable fingerprint of the signing key.
`iss`	Runlayer instance URL.
`aud`	`runlayer:identity-forward:<server-id>` — per-upstream so a token minted for one server can’t be replayed against another. The `<server-id>` is the Runlayer server UUID surfaced in the admin UI for that server.
`iat` / `exp`	Issued-at + expiry; TTL is 5 minutes.
`jti`	Unique per request.
`sub`	The principal the call runs for: the user’s id, or the agent’s id when an agent calls for itself.
`subject_type`	`user` or `agent` — the kind of principal `sub` names.
`act`	Present only when an agent acts on a user’s behalf: `{ "sub": "<agent-id>", "type": "agent", "name": "<agent-name>" }` (RFC 8693 actor claim; `name` is omitted when the agent has none). Absent when the caller acts for itself.
`organization_id`	Runlayer organization UUID.
`user_email`, `user_id`	Present whenever a user is involved: a direct user call, or an agent acting for one.
`agent_id`, `agent_name`	Present whenever an agent is involved: a standalone agent call, or an agent acting for a user.
`attributes`	Optional. Extra caller values you select per connector (see below), keyed by their dotted path. Absent when nothing was configured or nothing resolved.

Delegation is spelled differently on the two channels: the unsigned X-Runlayer-Subject-Type header reports obo, while the token reports subject_type: "user" plus an act claim. Earlier releases put obo in the token’s subject_type as well; verifiers that matched on it should check for act instead.

Adding subject or actor attributes

The signed token carries a fixed identity set by default. To include more about the caller — their name, an IdP-synced attribute such as department, or the acting agent’s identity attributes — list dotted paths under Extra signed-token claims on the connector (API: transport_config.identity_forward.claims):

{
  "identity_forward": {
    "signed": true,
    "claims": [
      "subject.name",
      "subject.identity_attributes.department_name",
      "actor.name",
      "actor.identity_attributes.team"
    ]
  }
}

Each path is resolved against the caller and emitted under a single attributes claim, keyed by the path you configured:

"attributes": {
  "subject.name": "Alice Smith",
  "subject.identity_attributes.department_name": "Sales"
}

Two roots are allowed. subject.* is the principal the call runs for (the token’s sub); actor.* is the agent acting on its behalf (the token’s act). Both roots have the same leaves: id, type (user or agent), email (users only), name (the user’s full name or the agent’s name), and identity_attributes.<key>. Each path must name a single value; a bare subject.identity_attributes or actor.identity_attributes is rejected, and a path that resolves to an object or list is omitted from the token. To keep the token within upstream header limits, individual values and the overall attributes object are size-capped: oversized values are omitted, and if the object as a whole is too large, later paths are dropped before earlier ones. The fixed identity claims are always sent. Keep attribute values small and order your paths most-important-first. Trust each value according to who can set it. A user’s identity attributes are synced from your identity provider. An agent’s name and identity attributes are set by anyone who can manage agent accounts (including developers), and a user’s name is editable by the user themselves. Because subject.* can name a user or an agent, check subject.type before trusting a subject.identity_attributes.<key> value; authorize on IdP-synced user attributes and treat the rest as display data. Paths that do not resolve for a given caller are omitted rather than sent as null — actor.* is absent unless an agent is acting for a user, and subject.email is absent when the subject is an agent. When an agent acts on behalf of a user, subject.* describes the delegating user and actor.* describes the acting agent, so both sides resolve. Attributes are added to the signed token only; the unsigned X-Runlayer-* headers are unchanged.

Verifying the signed token

Python (FastAPI + PyJWT):

import functools
import jwt
from fastapi import HTTPException, Request

RUNLAYER = "https://<your-runlayer>"
# Each upstream pins its own server-scoped audience. Copy the Runlayer
# server UUID from the server detail page in the admin UI.
RUNLAYER_SERVER_ID = "<runlayer-server-uuid>"
AUDIENCE = f"runlayer:identity-forward:{RUNLAYER_SERVER_ID}"


@functools.lru_cache(maxsize=1)
def _jwks_client() -> jwt.PyJWKClient:
    return jwt.PyJWKClient(
        f"{RUNLAYER}/.well-known/runlayer-identity-forward.jwks.json"
    )


def verified_caller(req: Request) -> dict:
    token = req.headers.get("x-runlayer-identity-token")
    if not token:
        raise HTTPException(401, "missing identity token")
    signing_key = _jwks_client().get_signing_key_from_jwt(token).key
    try:
        return jwt.decode(
            token,
            signing_key,
            algorithms=["EdDSA"],
            audience=AUDIENCE,
            issuer=RUNLAYER,
        )
    except jwt.InvalidTokenError as e:
        raise HTTPException(401, f"invalid identity token: {e}")

TypeScript (Express + jose):

import { createRemoteJWKSet, jwtVerify } from "jose";

const RUNLAYER = "https://<your-runlayer>";
// Per-upstream audience: copy the Runlayer server UUID from the admin UI.
const RUNLAYER_SERVER_ID = "<runlayer-server-uuid>";
const AUDIENCE = `runlayer:identity-forward:${RUNLAYER_SERVER_ID}`;
const JWKS = createRemoteJWKSet(
  new URL(`${RUNLAYER}/.well-known/runlayer-identity-forward.jwks.json`),
);

export async function verifiedCaller(req: Request) {
  const token = req.header("x-runlayer-identity-token");
  if (!token) throw new Error("missing identity token");
  const { payload } = await jwtVerify(token, JWKS, {
    audience: AUDIENCE,
    issuer: RUNLAYER,
  });
  return payload;
}

Enable

Open the server’s configuration in Runlayer (admin only).
Toggle Forward identity headers and/or Forward signed identity token on. The signed option is recommended; the plain headers are kept for backwards compatibility and trusted-network scenarios.
Save. The standard server-update audit log entry records the change like any other server-config edit.

Reading the headers

Python (FastAPI / FastMCP):

from fastapi import Request, HTTPException


def get_caller(req: Request) -> dict:
    subject_type = req.headers.get("x-runlayer-subject-type")
    if subject_type is None:
        raise HTTPException(401, "missing identity")

    return {
        "subject_type": subject_type,
        "org_id": req.headers.get("x-runlayer-org-id"),
        "user_email": req.headers.get("x-runlayer-user-email"),
        "user_id": req.headers.get("x-runlayer-user-id"),
        "agent_id": req.headers.get("x-runlayer-agent-id"),
        "agent_name": req.headers.get("x-runlayer-agent-name"),
    }

TypeScript (Express):

function getCaller(req: Request) {
  const subjectType = req.header("x-runlayer-subject-type");
  if (!subjectType) throw new Error("missing identity");

  return {
    subjectType,
    orgId: req.header("x-runlayer-org-id"),
    userEmail: req.header("x-runlayer-user-email"),
    userId: req.header("x-runlayer-user-id"),
    agentId: req.header("x-runlayer-agent-id"),
    agentName: req.header("x-runlayer-agent-name"),
  };
}

Limitations

Transports: streaming-http and sse only. Not supported on stdio (use environment variables / placeholders if you need identity for stdio).
Email-only personalization. Organization roles, groups, and custom claims are not forwarded.
Runlayer self-MCP (runlayer-mcp) does not receive identity headers or tokens.
Signed tokens have a 5-minute TTL. Verify upstream and re-fetch the JWKS when an unknown kid is presented (rotation rotates kid automatically).

Client User-Agent

Independent of the Identity Forward toggles, the proxy sets the upstream User-Agent on Streaming HTTP and SSE connectors to identify the end client that made the request:

User-Agent: <client>/<version> Runlayer/<runlayer-version>

<client>/<version> is the first product token of the MCP client’s own User-Agent (for example cursor/1.2.3 or claude-code/2.0.1); the client’s platform details are dropped. Unknown clients keep their original name. When no client is behind the request (background tool-list refreshes, connection tests, triggers) the value is just Runlayer/<runlayer-version>. Upstreams that gate access by client — for example Figma’s remote MCP server, which requires the gateway to indicate the downstream client — can parse the first token. Combine with a meta.request.user_agent policy rule (see Policies) to allowlist clients per connector. To pin a fixed value for one connector instead, add a User-Agent entry to the connector’s custom headers; an admin-configured User-Agent is never overwritten. stdio connectors are unaffected. The proxy’s own OAuth requests to the connector’s authorization server (metadata discovery, client registration, token exchange, refresh, revocation) send User-Agent: Runlayer/<runlayer-version>. The connector’s custom headers do not apply to those requests, so an allowlist at the identity provider should admit Runlayer.

Troubleshooting

Docker build fails

Solutions:

Test build locally first: docker build -t test .
Check Dockerfile syntax and instructions
Verify build context includes all required files
Check build arguments are passed correctly

Invalid CPU/memory combination

Solution:Refer to the configuration reference table for valid combinations. Not all CPU/memory pairs are supported. For example, 256 CPU only supports 512, 1024, or 2048 MB memory.

Deployment stuck or timeout

Solutions:Check deployment logs in the web UI. Common issues:

Container failing health checks (check your app responds on the configured port)
Wrong port configured in YAML
Missing required environment variables
Application crashes at startup (check application logs)

Can't destroy deployment

Solution:If the deployment has connected MCP servers, use the Delete All option to remove the deployment and its servers together. If you lack permission to delete those servers, ask the connector owner or an administrator to do it.

Environment variables not working

Explanation:Values are automatically masked as *** in stored configurations and API responses for security. This is expected behavior. Your actual values are securely passed to the container at runtime and are not visible in the UI or API.

Variable substitution errors

Common issues:

“Required environment variable ‘VAR’ is not set”: Variable isn’t in your environment or .env file. Check spelling and ensure it’s exported.
Wrong default syntax: Use ${VAR:-default} (with colon) to handle empty strings, or ${VAR-default} (no colon) to only use default if unset.
$$DEPLOYMENT_URL getting substituted by CLI: Use double dollar sign ($$DEPLOYMENT_URL), not single (${DEPLOYMENT_URL}). Single dollar triggers CLI substitution, double dollar preserves it for backend replacement.

Build works locally but fails in deployment

Solutions:

Verify platform architecture matches (x86 vs arm)
Check all dependencies are in Dockerfile, not just on your local machine
Ensure build arguments are specified in YAML if required
Review build logs for missing packages or permission errors

Upstream server doesn't see identity headers / token

Checklist:

The relevant Identity Forward toggle (headers and/or signed token) is on for this server (admin server config).
Transport is streaming-http or sse. stdio is not supported.
Caller has identity (logged-in user, OBO agent, or standalone agent account); anonymous calls forward only Subject-Type and Org-Id.
You’re reading the headers case-insensitively (HTTP header names are not case-sensitive; httpx canonicalizes them on send).
For the signed token: the verifier’s expected audience must be runlayer:identity-forward:<server-id> for this specific server (copy the UUID from the Runlayer admin UI). A token minted for server A intentionally fails audience check on server B. Also confirm the JWKS URL is reachable from the upstream environment.

exec format error

exec /usr/local/bin/python: exec format error

Cause: The Docker image architecture doesn’t match infrastructure.platform.Fix: Set infrastructure.platform to match your docker image architecture.

For x86/amd64 images: platform: x86
For ARM images: platform: arm

Next Steps

MCP Builder Quickstart

Scaffold a custom MCP server fast with the MCP Builder prompt

OAuth for Deployed Servers

Dual-auth architecture and token storage for OAuth connectors

Connectors

View and manage your connectors

Security Best Practices

Secure your MCP deployments and integrations

​Prerequisites

​Quick Start

​Runtimes

​Docker

​Coming Soon

​Configuration Reference

​Field Details

​How the MCP authenticates to ExtendDB (Kubernetes)

​Table contract and example

​Private connections

​AWS cross-account roles (hosted only)

​CLI Commands

​CI/CD with organization API keys

​deploy init (alternate entry point)

​deploy

​deploy validate

​deploy pull

​Updating a deployment

​deploy destroy

​Examples

​Example: Multi-stage Node.js Build with legacy SSE transport

​Example: Environment Variable Substitution

​Example: OAuth MCP Server

​Connector Status

​Identity Forward

​Headers sent

​Subject types

​Example requests

​Signed identity token

​Adding subject or actor attributes

​Verifying the signed token

​Enable

​Reading the headers

​Limitations

​Client User-Agent

​Troubleshooting

​Next Steps

MCP Builder Quickstart

OAuth for Deployed Servers

Connectors

Security Best Practices

Prerequisites

Quick Start

Runtimes

Docker

Coming Soon

Configuration Reference

Field Details

How the MCP authenticates to ExtendDB (Kubernetes)

Table contract and example

Private connections

AWS cross-account roles (hosted only)

CLI Commands

CI/CD with organization API keys

`deploy init` (alternate entry point)

`deploy`

`deploy validate`

`deploy pull`

Updating a deployment

`deploy destroy`

Examples

Example: Multi-stage Node.js Build with legacy SSE transport

Example: Environment Variable Substitution

Example: OAuth MCP Server

Connector Status

Identity Forward

Headers sent

Subject types

Example requests

Signed identity token

Adding subject or actor attributes

Verifying the signed token

Enable

Reading the headers

Limitations

Client User-Agent

Troubleshooting

Next Steps