mcplambda.yaml (Git Deploy Config)

When you deploy from Git, MCPLambda’s Image Builder clones your repository, builds a container image, and starts your MCP server. You can pass build settings on every deploy (--build-strategy, --run, …) — or commit them once in a mcplambda.yaml file at the repository root.

That file is the production-friendly way to encode “how this MCP server is built and started” next to your code.

What is `mcplambda.yaml`?

mcplambda.yaml is an optional repo-root config for Git deployments only. If present, MCPLambda reads build and run configuration from it so you (or the CLI / agent / dashboard) do not need to re-specify install, build, and start commands on every deploy.

Concern	Without yaml	With `mcplambda.yaml`
How to install deps	Flags / form each time	`install_command`
How to compile	Flags / form each time	`build_command`
How to start the server	`--run` required if no yaml	`run`
Build strategy	Flags / auto-detect	`build_strategy`
Transport preference	Flags / form	`transport`

Package and pre-built image deploys do not use this file (there is no source tree to read).

Where it lives

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

If the file is missing, Git deploy still works: use auto detection where possible, and provide at least a run command (and usually strategy / install / build for compiled projects).

Supported fields

Fields mirror the Git deployment API. Names use snake_case in the yaml (same as the API).

Field	Type	Description
`build_strategy`	string	One of: `auto`, `dockerfile`, `pip`, `uv`, `poetry`, `npm`, `pnpm`, `go`. Default behavior when omitted is effectively auto (detect from repo files).
`install_command`	string	Overrides the default install step for the strategy (e.g. `npm ci`, `uv sync`). Ignored when strategy is `auto` or `dockerfile`.
`build_command`	string	Post-install command before the process entrypoint (e.g. `npm run build`, `tsc`).
`run`	string	Command that starts the MCP server inside the container (e.g. `node dist/index.js`). Required if the file is absent and not supplied via CLI/API.
`transport`	string	Preferred MCP transport: `stdio`, `streamable-http`, or `sse`. MCPLambda still exposes a Deployment URL for clients; for `stdio`, the platform proxies to a web-native endpoint.

Not stored in mcplambda.yaml (set at deploy time instead): deployment name, project, branch, env vars, secrets, auth type, server profile, storage, tools allowlist. Those are environment- and tenancy-specific.

Examples

TypeScript / Node (npm)

# mcplambda.yaml
build_strategy: npm
install_command: npm ci
build_command: npm run build
run: node dist/index.js
transport: streamable-http

Node with pnpm

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

Python with uv

build_strategy: uv
install_command: uv sync
run: uv run mcp-server
transport: streamable-http

Python with Poetry

build_strategy: poetry
install_command: poetry install --no-dev
run: poetry run python -m mcp_server
transport: streamable-http

Dockerfile-based build

build_strategy: dockerfile
# install_command / build_command are ignored for dockerfile strategy
# Ensure the image CMD/ENTRYPOINT starts the MCP server, or set run if your pipeline expects it
transport: streamable-http

For Dockerfile strategy, MCPLambda builds the image from your repo’s Dockerfile. Prefer a correct ENTRYPOINT/CMD that launches the MCP process.

How MCPLambda processes it

At a high level, for a Git deployment:

Clone the repository at the selected branch (dashboard, mcpl deploy <git-url>, or agent tool).
Read mcplambda.yaml from the repo root if present.
Merge configuration:
- Base: yaml values (if any)
- Override: explicit CLI flags / API body fields always win when both are set
Resolve build strategy — auto inspects files such as package.json, pyproject.toml, go.mod, Dockerfile.
Install dependencies (install_command or strategy default).
Build if build_command is set (compile TypeScript, etc.).
Package into a secure container image (Image Builder).
Run using run (or image entrypoint for dockerfile) with your env vars, secrets, auth, and profile.
Expose a Deployment URL; proxy as needed so clients can use Streamable HTTP / SSE even when the process speaks stdio.

Override precedence

API / CLI flags  >  mcplambda.yaml  >  auto-detection defaults

Examples:

Yaml says run: node dist/index.js but you pass --run "node dist/debug.js" → CLI wins.
Yaml missing run and no --run → deploy fails or cannot start (provide one of them).
Yaml has build_strategy: npm and CLI passes --build-strategy pnpm → CLI wins.

Deploy with the file in place

Once mcplambda.yaml is committed, a minimal deploy is enough:

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

You can still attach secrets and env 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

Dashboard Git flow and the MCPLambda MCP server / agent tools use the same merge rules.

Best practices

Commit the file for any server you re-deploy often — it documents production start for humans and agents.
Prefer streamable-http for remote clients unless you intentionally use stdio + platform proxy.
Keep secrets out of yaml — use project secrets / deploy -e / secret IDs.
Pin install commands to reproducible installs (npm ci, lockfiles, uv sync).
Verify locally that run starts a process that answers MCP (tools/list) on the transport you chose.
For monorepos, keep a dedicated MCP package repo or ensure the yaml run/build paths match the subdirectory layout the builder expects (root-relative commands).

Deployment Strategies — package, Git, and image flows
The mcpl CLI — flags that override yaml
Agent Guide — Git flow examples for agents
Getting Started — first deploy

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

What is mcplambda.yaml?