mcplambda.yaml (Git Deploy Config)

When you deploy from Git, MCPLambda clones your repository, builds a container image, and starts your MCP server. Commit an mcplambda.yaml file at the repository root to keep the server’s build and runtime defaults next to its source code.

Package and pre-built image deployments do not read this file because they do not clone a source repository.

File names and location

MCPLambda checks these files at the repository root, in order, and uses the first one it finds:

1. mcplambda.yaml
2. mcplambda.yml
3. .mcplambda.yaml
4. .mcplambda.yml

your-mcp-repo/
├── mcplambda.yaml    ← repository root
├── package.json      # or pyproject.toml, go.mod, Dockerfile, …
└── src/

The file is optional for dashboard, CLI, and API-triggered Git deployments. If it is missing, provide a run command in the deployment request. Webhook-driven GitOps deployments require the file.

Example

This example shows the documented schema. Most projects need only run, build, port, and transport.

# Required whenever a config file is present.
run: node dist/index.js

build:
  strategy: npm
  dockerfile: Dockerfile
  context: .
  base_image: node:22-alpine
  install_command: npm ci
  build_command: npm run build

storage: 2Gi

tools:
  - search
  - fetch

env_vars:
  NODE_ENV: production
  LOG_LEVEL: info

args:
  - --host
  - "0.0.0.0"

working_dir: /app
port: 8000
transport: streamable-http

# Accepted by the parser, but not currently applied to Git deploys.
image: ghcr.io/example/server:latest

build is a nested object. The older top-level keys build_strategy, install_command, and build_command are not part of the mcplambda.yaml schema.

Root fields

Field	Type	Default	Description
run	string	—	Command used to start the server for generated source images. Required whenever a config file is present. For dockerfile, the image’s ENTRYPOINT or CMD controls startup, but run is still required by config validation.
build	object	strategy: auto	Source build settings. See Build fields.
storage	string	none	Persistent volume size in Kubernetes quantity format, such as 500Mi, 2Gi, or 10Gi. Currently applied by webhook-driven GitOps; for dashboard, CLI, or API deploys, set storage in the deployment request.
tools	string[]	none	Non-empty MCP tool names to expose. Currently applied by webhook-driven GitOps; for dashboard, CLI, or API deploys, set tools in the deployment request.
env_vars	object	none	Plain-text environment variables. Values from the deployment request override matching yaml keys. Do not store secrets here.
args	string[]	none	Arguments appended to run in generated source images.
working_dir	string	/app	Working directory used by generated source images.
port	integer	8000	Port the MCP server listens on inside the container. Valid range: 1–65535.
transport	string	stdio	MCP transport: stdio, streamable-http, or sse.
image	string	none	Accepted by the parser, but currently not used by the Git image builder. Use an image deployment to deploy an existing image.

Deployment name, project, Git repository and branch, authentication, secret references, and server profile remain deploy-time settings. Project secrets and inline secrets take precedence over plain env_vars supplied in the file or deployment request.

Build fields

All build fields are nested below build.

Field	Type	Default	Description
build.strategy	string	auto	One of auto, dockerfile, pip, uv, poetry, npm, pnpm, or go.
build.dockerfile	string	Dockerfile	Dockerfile path relative to the repository root. Used only by the dockerfile strategy.
build.context	string	.	Build context relative to the repository root. Used only by the dockerfile strategy.
build.base_image	string	strategy default	Overrides the base image for generated pip, uv, poetry, npm, pnpm, and go builds.
build.install_command	string	strategy default	Overrides the dependency installation or compilation command for a generated source image. It does not alter a repository-owned Dockerfile.
build.build_command	string	none	Command run after the source is copied. Currently rendered only by the npm and pnpm strategies. TypeScript projects with a root tsconfig.json default to npm run build or pnpm run build when this field is omitted.

build.dockerfile and build.context must be relative paths and cannot escape the repository root with ...

Build strategies and defaults

Strategy	Auto-detection signal	Default base image	Default install/build step
dockerfile	Dockerfile	From the Dockerfile	From the Dockerfile
uv	uv.lock, or [tool.uv] in pyproject.toml	python:3.13-slim	uv sync --frozen --no-dev
poetry	poetry.lock, or [tool.poetry] in pyproject.toml	python:3.13-slim	poetry install --no-dev --no-interaction
pip	Other pyproject.toml, requirements.txt, or setup.py	python:3.13-slim	pip install --no-cache-dir -r requirements.txt
pnpm	pnpm-lock.yaml	node:22-alpine	corepack enable && pnpm install --frozen-lockfile --prod
npm	package.json	node:22-alpine	npm ci --omit=dev
go	go.mod	golang:1.25-alpine	go build -o /app/server .

auto checks these signals in the order shown above. A root Dockerfile therefore takes precedence over package-manager files. Set build.strategy explicitly when the repository contains more than one signal or needs a different strategy.

Common configurations

TypeScript with npm

run: node dist/index.js
build:
  strategy: npm
  install_command: npm ci
  build_command: npm run build
port: 8000
transport: streamable-http

Node with pnpm

run: node dist/server.js
build:
  strategy: pnpm
  install_command: pnpm install --frozen-lockfile
  build_command: pnpm build
transport: streamable-http

Python with uv

run: uv run mcp-server
build:
  strategy: uv
  install_command: uv sync --frozen --no-dev
transport: streamable-http

Custom Dockerfile and build context

# Required by config validation; the Dockerfile ENTRYPOINT/CMD starts the image.
run: ./server
build:
  strategy: dockerfile
  dockerfile: deploy/Dockerfile
  context: services/mcp
port: 8080
transport: streamable-http

For a Dockerfile build, MCPLambda uses the selected Dockerfile and context directly. base_image, install_command, build_command, args, and working_dir do not rewrite the Dockerfile.

Processing and override rules

For a dashboard, CLI, or API-triggered Git deployment, MCPLambda:

1. Clones the selected repository and branch.
2. Reads the first supported config file from the repository root, if present.
3. Applies explicit deployment request values over yaml values.
4. Validates the merged configuration.
5. Resolves build.strategy; auto inspects repository files.
6. Builds a container image with the repository Dockerfile or a strategy-specific generated Dockerfile.
7. Deploys the built image with the selected server profile, environment, storage, secrets, and authentication settings.

API / CLI / dashboard values  >  mcplambda.yaml  >  strategy defaults

Explicit request values can override run, port, transport, build.strategy, build.install_command, and build.build_command. Environment variables are merged by key, with request values winning. Other yaml fields do not have matching request overrides.

When a config file exists, it must contain a non-empty run value before request overrides are applied. A request can replace that value, but cannot make an otherwise invalid file valid.

Examples:

• Yaml says run: node dist/index.js, but the request supplies node dist/debug.js → the request wins.
• Yaml says build.strategy: npm, but the request supplies pnpm → the request wins.
• Both yaml and the request define LOG_LEVEL → the request value wins.
• Neither yaml nor the request provides run → the deployment fails validation.

Deploy with the file in place

Once the file is committed, a minimal deploy is enough:

mcpl deploy https://github.com/you/my-mcp-server \
  --branch main \
  --name my-mcp-server \
  -o json

Attach environment-specific secrets and select the server profile at deploy time:

mcpl deploy https://github.com/you/my-mcp-server \
  --branch main \
  --name my-mcp-server \
  -e NODE_ENV=production \
  --auth-type key \
  --server-profile medium \
  -o json

Best practices

• Commit the file for servers you redeploy often so humans, automation, and agents share the same build defaults.
• Keep secrets out of env_vars; use project secrets or inline deploy secrets.
• Prefer lockfiles and reproducible install commands such as npm ci and uv sync --frozen.
• Set build.strategy explicitly when a repository contains several auto-detection signals.
• Verify that run starts the MCP process and that port and transport match the server.
• Select compute resources with the deploy-time server profile.

Related

• Deployment Strategies — package, Git, and image flows
• The mcpl CLI — flags that override yaml
• Agent Guide — Git flow examples for agents
• Server Profiles — deploy-time CPU and memory sizing
• Getting Started — first deploy

Marketing deep-dive: Production-ready MCP with mcplambda.yaml (learn guide).