> ## Documentation Index
> Fetch the complete documentation index at: https://milford.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> The milford.config.yaml file.

The server reads one YAML file. Pass its path as the first argument or set `MILFORD_CONFIG`. The default is `milford.config.yaml`.

```yaml theme={null}
# yaml-language-server: $schema=./node_modules/@milfordai/config/milford.config.schema.json
providers:
  - { id: main-llm, type: anthropic, apiKey: "${ANTHROPIC_API_KEY}", model: claude-sonnet-5 }
  - { id: fast-llm, type: openai, baseUrl: https://api.groq.com/openai/v1, apiKey: "${GROQ_API_KEY}", model: llama-3.3-70b-versatile }
flows:
  - { file: ./flows/triage.json }
server:
  port: 8080
  auth: { tokens: ["${MILFORD_TOKEN}"] }
  maxBodyBytes: 500000
run:
  timeoutMs: 30000
  maxConcurrentRuns: 32
```

## Environment variables

`${NAME}` inside any string is replaced from the environment, so the file holds no secrets. The server refuses to start and lists every variable that is not set.

<Warning>
  Quote strings that contain `${...}` inside flow collections such as `[...]` and `{...}`. YAML treats braces in unquoted values as syntax.
</Warning>

## Keys

<ParamField body="providers" type="object[]">List of [providers](/providers/overview). Each needs `id` and `type`. Other keys depend on the type.</ParamField>
<ParamField body="flows" type="object[]">List of `{ file, id? }`. `file` is a flow JSON path relative to the config file. `id` overrides the id inside the file.</ParamField>
<ParamField body="channels" type="object[]">List of [channels](/guides/channels). Each needs `id`, `type` (`slack`, `telegram` or `webhook`) and `flow`. Slack and Telegram channels also need an `allow` list. Webhook channels need a `secret`.</ParamField>
<ParamField body="mcpServers" type="object[]">Other MCP servers that [`mcp` nodes](/guides/mcp) can call over Streamable HTTP. Each has `id`, `url` and optional `headers`.</ParamField>

<ParamField body="mcp" type="object">
  The [MCP server](/guides/mcp) (`milford-mcp`). Keys: `expose` (flow ids exposed as tools, empty by default), `transport` (`stdio` or `http`, default `stdio`), `host` (default `0.0.0.0`), `port` (default `8090`), `auth.tokens` (required for `http` beyond localhost).
</ParamField>

<ParamField body="server.port" type="number" default="8080">Listen port.</ParamField>
<ParamField body="server.auth.tokens" type="string[]" default="[]">Accepted bearer tokens. With none configured, the API is open and the server logs a warning.</ParamField>
<ParamField body="run.timeoutMs" type="number" default="60000">Per-run timeout in milliseconds. The timeout aborts every in-flight `fetch` and provider call of the run.</ParamField>
<ParamField body="run.maxConcurrentRuns" type="number" default="64">Runs allowed at once, across the API, the MCP server and the channels. Further runs are rejected: the API answers `503` with `Retry-After: 1`, an MCP tool returns an error result, a webhook answers `503`, and a chat channel replies "Busy, try again shortly."</ParamField>
<ParamField body="server.idempotencyTtlMs" type="number" default="600000">How long a successful run is kept for `Idempotency-Key` replays. See [enterprise integration](/guides/enterprise-integration).</ParamField>
<ParamField body="server.maxBodyBytes" type="number" default="1000000">Largest accepted request body. Larger requests get `413`.</ParamField>

## Validation at startup

The server compiles every flow before it listens. It reports unknown providers, providers that lack a needed capability, invalid node configs, cycles and unknown node types, and exits without serving.

## Logging and shutdown

The server writes one JSON line to stdout for each finished run, with the flow id, `ok`, `runId` and duration in milliseconds. On `SIGTERM` or `SIGINT` it stops accepting connections and lets in-flight runs finish. It exits after 10 seconds even if a run is still going.

## JSON Schema

The package `@milfordai/config` ships the JSON Schema of the config file as `milford.config.schema.json`. Point your editor's YAML language server at it for completion. See [installation](/installation).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.