---
title: mcplambda.yaml (Git Deploy Config)
description: Declare build strategy, install, build, run, and transport for Git deployments so MCPLambda can build and start your MCP server without repeating CLI flags.
---

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

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

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

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

### Python with uv

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

### Python with Poetry

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

### Dockerfile-based build

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

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

### Override precedence

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

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

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

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

---

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