Configuration¶
mcpdev loads a versioned TOML file so you can reuse named stdio, HTTP, and custom connector targets without putting secrets on the command line. Flags and the CLI still win for a single process. Redaction of credential-shaped fields is in Diagnostics.
File locations¶
| Layer | Path |
|---|---|
| Project | mcpdev.toml (preferred) or .mcpdev.toml, walking from the current working directory toward the filesystem root. The nearest file wins. |
| User | $MCPDEV_CONFIG if set (error if the file is missing). Otherwise $XDG_CONFIG_HOME/mcpdev/config.toml. On Windows, %APPDATA%\mcpdev\config.toml when XDG_CONFIG_HOME is unset. Otherwise ~/.config/mcpdev/config.toml. |
A missing default user file is skipped. A missing project file is skipped. MCPDEV_CONFIG pointing at a missing path is a usage error and names that path.
Precedence (highest wins)¶
- Command-line flags for the current process
- Process environment (
MCPDEV_*) - Project config file (nearest)
- User config file
- Built-in defaults (
protocol=auto,format=human, insecure and HTTP+SSE off)
A flag that is present with an empty value is still a flag. Unset environment variables do not override config files. Boolean env values: 1, true, TRUE, yes are true; 0, false, FALSE, no, empty are false. Any other string is a usage error.
Project profiles replace a user profile of the same name entirely (they are not field-merged).
Document shape¶
version = 1 is required when version is present. Other versions are usage errors that name the version field. A document without version is treated as version 1.
version = 1
protocol = "auto"
timeout = "10s"
connect_timeout = "15s"
format = "human"
sensitive = ["X-Lab-Token"]
[profiles.local]
command = ["go", "run", "."]
cwd = "./server"
[profiles.http]
url = "https://mcp.example.com/mcp"
[profiles.http.header_env]
Authorization = "MCPDEV_TOKEN"
[profiles.http.tls]
ca_file = "/etc/ssl/certs/ca.pem"
[profiles.custom]
connector = "fake"
command is an argv array only. A shell string is a usage error on that profile's command field.
Exactly one of command, url, or connector is required on each profile. Combining them is a usage error that names profiles.<name>. connector = "grpc" is refused (gRPC is not a standard MCP transport).
Environment interpolation¶
String fields may contain ${NAME}, ${NAME:?}, or ${NAME:-default}. $$ is a literal $.
| Form | Missing or empty value |
|---|---|
${NAME} or ${NAME:?} |
Usage error naming the profile field and the variable |
${NAME:-default} |
Substitutes default |
Interpolation runs after files and MCPDEV_* scalars are merged, using the process environment. header_env values are variable names, not interpolated strings.
Auth and TLS references¶
Do not put bearer tokens, passwords, or PEM blobs in the file.
| Mechanism | Role |
|---|---|
[profiles.name.header_env] |
Header name to environment variable. The variable must be set and non-empty when the profile is used. |
[profiles.name.headers] with ${NAME:?} |
Same idea inline. Literal values on credential-shaped names (Authorization, token, password, names in sensitive, …) are refused. |
[profiles.name.tls] ca_file / cert_file / key_file |
Paths (interpolated). cert_file and key_file must be set together. Inline PEM is refused. |
url userinfo (https://user:pass@host) |
Refused. Use header_env. |
Flags --header / --env overlay profile maps (the flag wins per key).
Insecure combinations¶
Loopback http is allowed. Non-loopback http and skipped TLS verification need an explicit opt-in:
--insecureMCPDEV_INSECURE(true values above)insecure = truein a config file (file or profile ortls.insecure)
File and environment opt-ins append a warning on the loaded settings. They never turn on from --url alone. allow_http_sse = true is accepted as an explicit key but mcpdev still reports that HTTP+SSE is not implemented.
Errors¶
Usage errors (exit class 2) name the file path, profile, and field when those are known:
config: /path/mcpdev.toml: profiles.http.headers.Authorization: inline secret refused; use header_env or ${NAME:?}
Secret values are not copied into the message.
Redaction¶
sensitive and credential-shaped header/env keys feed the same redaction pass used by inspect JSON, traces, snapshots, scenario reports, and replay fixtures. Renderers substitute [REDACTED]. See Diagnostics.
mcpdev --profile http --format json inspect tools