---
title: mcplambda.yaml (Git Deploy Config)
description: Reference for the repository-owned build and runtime settings supported by mcplambda.yaml Git deployments.
---

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`

```text
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`.

```yaml
# 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](#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

```yaml
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

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

### Python with uv

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

### Custom Dockerfile and build context

```yaml
# 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.

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

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

```bash
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](/docs/deployment-strategies/) — package, Git, and image flows
- [The mcpl CLI](/docs/cli/) — flags that override yaml
- [Agent Guide](/docs/agents/) — Git flow examples for agents
- [Server Profiles](/docs/profiles/) — deploy-time CPU and memory sizing
- [Getting Started](/docs/getting-started/) — first deploy

Marketing deep-dive: [Production-ready MCP with mcplambda.yaml](https://mcplambda.io/learn/production-ready-mcp-with-mcplambda-yaml) (learn guide).