Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration reference

A server built with app::Server is configured entirely with environment variables. This page lists every variable the server itself reads, how values are read, and how they are checked. Your services read their own variables in the same way.

The server checks its configuration at startup and, if anything is wrong, prints every problem it found and exits without starting, so a typo never leaves it half configured. A few checks wait until others pass; see Validation.

How values are read

  • An empty value counts as unset. MCP_AUTH_TOKEN= is the same as not setting it.
  • Any variable can be read from a file by appending _FILE to its name, such as OAUTH_SIGNING_KEY_FILE=/run/secrets/oauth_signing_key. Use it for secrets with Docker or Kubernetes secrets. A value set directly wins over the file. Trailing newlines (\n and \r) are removed from the file’s contents, and an empty file counts as unset. A file that cannot be read is a configuration error: OAUTH_SIGNING_KEY_FILE: cannot read /run/secrets/oauth_signing_key: No such file or directory (os error 2).
  • Booleans accept true, false, 1, 0, yes, no, on and off, in any case. Anything else is an error, such as INSECURE_HTTP must be true or false, got "maybe".
  • Lists are comma separated. Spaces around entries are ignored, and so are empty entries: " a, b ,,c " is a, b and c.
  • Addresses (BIND_ADDR, METRICS_ADDR) are an IP address and a port, such as 0.0.0.0:8443 or [::]:8443. Host names are not accepted.
  • Error messages never contain secret values. A rejected OAUTH_SIGNING_KEY is reported by name and rule, never by its value.

The prefix

Three variables belong to one server and carry its prefix: <PREFIX>_SERVICES, <PREFIX>_COMBINED and <PREFIX>_READ_ONLY. The prefix is MCP unless the server sets another with Server::env_prefix, which removes trailing underscores and converts it to upper case:

#![allow(unused)]
fn main() {
use mcp_server_core::app::Server;

let server = Server::new("mcp-weather", "1.0.0").env_prefix("weather_");
assert_eq!(server.var("SERVICES"), "WEATHER_SERVICES");

let default = Server::new("mcp-weather", "1.0.0");
assert_eq!(default.var("READ_ONLY"), "MCP_READ_ONLY");
}

Every other variable on this page has a fixed name, whatever the prefix. MCP_AUTH_TOKEN is always MCP_AUTH_TOKEN. A server’s own documentation should give its prefix; mcp-icloud uses ICLOUD, for example ICLOUD_SERVICES.

Public address and listening

VariableDefaultExampleMeaning
PUBLIC_URLrequiredhttps://mcp.example.comThe external URL clients use, without a path. It must be https://; http:// is accepted only when the host is localhost, 127.0.0.1 or [::1]. A port is allowed, a trailing / is removed, and a path, query or fragment is an error. It is the OAuth issuer, the prefix of every service’s URL and the host the MCP endpoints accept; see TLS and deployment.
BIND_ADDR0.0.0.0:8443127.0.0.1:8443The address and port to listen on. --healthcheck connects to 127.0.0.1 on this port, so the address must accept loopback connections; 0.0.0.0 does.
TLS_CERT_PATHnone/certs/fullchain.pemA PEM certificate chain, leaf first. Set it together with TLS_KEY_PATH; setting only one is an error. The server checks both files every 30 seconds and reloads them when either changes. Without either, the server generates a self-signed certificate. See TLS and deployment.
TLS_KEY_PATHnone/certs/privkey.pemThe PEM private key for TLS_CERT_PATH.
INSECURE_HTTPfalsetrueServe plain HTTP, for a reverse proxy or tunnel that terminates TLS in front of the server. It wins over TLS_CERT_PATH and TLS_KEY_PATH, which are then ignored. --healthcheck reads it too.
TRUSTED_PROXIESnone10.0.0.2,10.0.0.3Comma-separated IP addresses of reverse proxies you run. A request from one of them is limited by the client address in its X-Forwarded-For header instead of the proxy’s. Single addresses only, not ranges; an invalid entry is an error. See Reverse proxies.
ALLOWED_ORIGINSnonehttp://localhost:6274Comma-separated browser origins, besides PUBLIC_URL’s own, allowed to call the MCP endpoints. Each is scheme://host with an optional :port, or :* for any port. Entries are passed to rmcp as written and not checked at startup: one that does not parse matches nothing. See Host and Origin checks.

Sign-in and tokens

VariableDefaultExampleMeaning
OAUTH_SIGNING_KEYrequiredoutput of openssl rand -hex 32Signs every token the server issues and derives the key that seals people’s credentials into their tokens. At least 32 bytes; the value is used as text, so 64 hex characters are 64 bytes. Changing it signs everyone out and every client must register again. Keep it secret: whoever has it can mint tokens and open sealed credentials.
OAUTH_ADMIN_PASSWORDrequired with SignIn::OwnerPassworda passphraseThe owner’s password for the sign-in page. At least 12 characters and not only spaces; shorter than 15 gets a warning at startup. It is compared exactly as typed, spaces included, and the sign-in page accepts at most 1024 bytes. Changing it ends every grant. Not read with the other sign-in modes. See Sign-in modes.
MCP_AUTH_TOKENnoneoutput of openssl rand -hex 32A fixed bearer token accepted on every path, for clients that cannot sign in with OAuth. It must not have the shape of a JWT (three dot-separated parts), and cannot be used when people sign in with their own credential, or when the verifier accepts credentials as bearer tokens. Shorter than 32 characters gets a warning. Wrong tokens count towards the sign-in limits. See The static token.

Services

VariableDefaultExampleMeaning
<PREFIX>_SERVICESevery registered serviceweather,tidesThe services to run, comma separated. An unknown name, or a list with no names, is an error. A service that is not selected is not mounted and never reads its own variables, so they need not be set. Selected services are built, mounted and listed on /mcp in the order this variable names them.
<PREFIX>_COMBINEDtruefalseServe every selected service’s tools and prompts together at /mcp, as <service>_<name>. With false, /mcp answers 404. See Several services and /mcp.
<PREFIX>_READ_ONLYnonetides or allServices whose write tools are hidden and refused, on their own path and under /mcp. Comma separated, or all for every registered service. An unknown name is an error; a registered service that is not selected is accepted and has no effect. See Read-only mode and the audit log.
AUDIT_LOG_PATHnone/audit/audit.jsonlA file to append one JSON line to for every write tool call, made or refused. It is opened on the first write. On Unix it is created with mode 0600, and an existing file is narrowed to 0600. Audit lines are logged on the audit target whether or not this is set. See The audit file.

Logs, metrics and traces

VariableDefaultExampleMeaning
LOG_LEVELinfoinfo,mcp_weather=debugA tracing filter: a level for everything, then target=level directives. It is not checked with the other variables: an invalid filter stops the server right after them, with an error: line. See Logs.
LOG_FORMATjsonprettyjson for one JSON object per line, or pretty for multi-line, coloured output (without colour when the NO_COLOR environment variable is set and not empty). Any case.
DEBUGfalsetrueDebug logs for your own crates and this one, without content. See DEBUG.
DEBUG_UNSAFE_LOG_CONTENTfalsetrueLets services log content, such as the text people send and read, and turns on DEBUG too. A warning is logged at startup. Never in production. See Content in logs.
METRICS_ADDRnone0.0.0.0:9090Serve Prometheus metrics on a separate plain HTTP listener at this address. Keep it on an internal network. Needs the prometheus feature (on by default); without it the server logs a warning. See Metrics.
OTEL_EXPORTER_OTLP_ENDPOINTnonehttp://otel-collector:4318Export traces over OTLP/HTTP to this collector. Only this variable turns export on: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT on its own does not. The standard OTEL_* variables apply. Needs the otel feature (on by default); without it the server logs a warning. See Traces.

Those are all the variables the server reads while loading its configuration. Two other readers exist:

  • The OpenTelemetry exporter reads the standard OpenTelemetry variables itself when traces are on, such as OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and OTEL_EXPORTER_OTLP_TIMEOUT. It reads them directly from the environment, so they have no _FILE variants. That includes OTEL_EXPORTER_OTLP_ENDPOINT: set it directly, because the _FILE form turns export on but the exporter itself does not see the address.
  • --healthcheck reads BIND_ADDR and INSECURE_HTTP (or their _FILE variants), and nothing else. Run it with the server’s environment.

Services’ own variables

Each service reads its own variables in its factory, through the ServiceEnv it is given. They follow the same rules as the server’s: empty means unset, _FILE variants, the same booleans and lists, and problems recorded rather than returned one at a time. A server’s documentation lists them; Reading configuration with ServiceEnv shows how to write a factory.

Name a service’s variables after the service, such as WEATHER_API_URL, unless two services share one on purpose. A problem with a shared variable is reported once.

Validation

Server::load reads the core variables, then the sign-in settings, then <PREFIX>_SERVICES, <PREFIX>_READ_ONLY, AUDIT_LOG_PATH and <PREFIX>_COMBINED, then each selected service’s variables, all into one list of problems. Each message appears once, even when two services report the same one. When the list is not empty the binary prints each problem on its own line and exits with status 1:

configuration error: PUBLIC_URL must be an https URL (http is only allowed for localhost)
configuration error: OAUTH_SIGNING_KEY must be at least 32 bytes
configuration error: TLS_CERT_PATH and TLS_KEY_PATH must be set together
configuration error: OAUTH_ADMIN_PASSWORD is required
configuration error: WEATHER_API_KEY is required

What is checked:

VariableRule
PUBLIC_URLSet; a URL with a host; https, or http for a loopback host; no path, query or fragment.
OAUTH_SIGNING_KEYSet; at least 32 bytes.
OAUTH_ADMIN_PASSWORDWith SignIn::OwnerPassword: set; at least 12 characters; not only spaces.
MCP_AUTH_TOKENNot shaped like a JWT; not next to a verifier that carries credentials or accepts them as bearer tokens.
TRUSTED_PROXIESEvery entry an IP address.
BIND_ADDRAn IP address and port.
METRICS_ADDRAn IP address and port.
INSECURE_HTTPA boolean.
DEBUGA boolean.
DEBUG_UNSAFE_LOG_CONTENTA boolean.
LOG_FORMATjson or pretty.
TLS_CERT_PATHSet together with TLS_KEY_PATH, unless INSECURE_HTTP is on. The files themselves are read when the server starts serving.
<PREFIX>_SERVICESOnly registered names, at least one.
<PREFIX>_READ_ONLYOnly registered names, or all.
<PREFIX>_COMBINEDA boolean.

The sign-in mode adds rules of its own. With SignIn::ServiceCredential, exactly one enabled service must define how people sign in; see Only one service may define sign-in.

A few checks can only run once others pass, so fixing one round of errors can reveal another:

  • The checks on MCP_AUTH_TOKEN run once PUBLIC_URL, OAUTH_SIGNING_KEY and the other server variables are valid.
  • Services read their variables only once <PREFIX>_SERVICES is valid, since until then the server does not know which services to build.
  • LOG_LEVEL, the OpenTelemetry endpoint’s address, the TLS files and the listening addresses are used when the server starts serving, after the configuration has loaded. A problem with them ends the server with an error: line instead of configuration error:.

Troubleshooting quotes every message with its fix.

Warnings

Some settings work but are weak. The server starts and logs a warning for each, straight after its starting line:

SettingWarning
OAUTH_ADMIN_PASSWORD of 12 to 14 charactersOAUTH_ADMIN_PASSWORD is shorter than 15 characters: a longer passphrase is much harder to guess
MCP_AUTH_TOKEN shorter than 32 charactersMCP_AUTH_TOKEN is shorter than 32 characters: use a long random value

Other warnings at startup describe how the server runs rather than a weak value: plain HTTP, a self-signed certificate, DEBUG_UNSAFE_LOG_CONTENT, an ALLOWED_ORIGINS entry without a port, and METRICS_ADDR or OTEL_EXPORTER_OTLP_ENDPOINT set in a build without the feature. Troubleshooting lists them.

A complete example

A server with the prefix SEA, two services, its secrets in files and a TLS-terminating proxy in front:

PUBLIC_URL=https://sea.example.com
BIND_ADDR=0.0.0.0:8443
INSECURE_HTTP=true
TRUSTED_PROXIES=10.0.0.2
OAUTH_SIGNING_KEY_FILE=/run/secrets/oauth_signing_key
OAUTH_ADMIN_PASSWORD_FILE=/run/secrets/oauth_admin_password
MCP_AUTH_TOKEN_FILE=/run/secrets/mcp_auth_token
SEA_SERVICES=weather,tides
SEA_READ_ONLY=tides
SEA_COMBINED=true
AUDIT_LOG_PATH=/audit/audit.jsonl
LOG_LEVEL=info
LOG_FORMAT=json
METRICS_ADDR=0.0.0.0:9090

To create the secrets:

mkdir -p secrets
openssl rand -hex 32 > secrets/oauth_signing_key
openssl rand -hex 32 > secrets/mcp_auth_token
printf '%s' 'a long passphrase you will remember' > secrets/oauth_admin_password
chmod 600 secrets/*

TLS and deployment shows settings like these in a container, with the secrets mounted as files.