Skip to main content

MCPX_CONFIG_MISSING_SECRET

Severity: error Domain: Config

What happened​

The upstream config references a secret (typically via ${keyring:NAME} in env or headers), but the secret was not found in the active secret store when mcpproxy tried to start that server.

HTTP upstreams: nothing is sent​

When the missing reference is in a remote server's url, headers or oauth settings, mcpproxy does not connect, sign in or refresh a token for that server, so the raw ${keyring:NAME} text never reaches the upstream. The server shows Missing secret with the reference name, and the error names the field, for example:

unresolved secret reference ${keyring:my_api_key} in Headers[Authorization]: the secret is not available, so nothing was sent to the upstream. Add it with: mcpproxy secrets set my_api_key, then restart the server (mcpproxy upstream restart my-server)

Other servers are not affected. A missing reference in a local (stdio) server's env, args or working_dir is logged and the value is used as written; a stdio server never sends its headers, url or oauth values, so a reference there does not stop it either.

This also applies to ${env:NAME} references and to any text in those fields that has the ${type:name} form: earlier versions sent them literally when they could not be resolved, and mcpproxy now refuses instead. A ${env:NAME} reference reads mcpproxy's own environment, so set the variable and restart mcpproxy (or its service) rather than the server.

How to fix​

List what's defined​

mcpproxy secrets list

If the name you referenced isn't there, add it.

Secrets are resolved when the server's connection is created. Storing a secret through the Web UI or REST API restarts the enabled servers that use it; after mcpproxy secrets set, restart the server:

mcpproxy upstream restart <server>

Add the missing secret​

mcpproxy secrets set <NAME> # prompts; typed characters are echoed in the terminal

Secrets are stored in the OS keychain on macOS / Windows and in an encrypted file on Linux.

Check the reference syntax​

{
// env values support ${keyring:NAME} expansion:
"env": { "GITHUB_TOKEN": "${keyring:github_personal_token}" },

// headers do too:
"headers": { "Authorization": "Bearer ${keyring:my_api_key}" }
}

Plain string values are used as-is (no expansion).

Migration from inline secrets​

If you previously stored secrets inline and want to move them into the secret store:

mcpproxy secrets set github_personal_token
# Enter the value at the prompt (terminal input is echoed).
# Then update the config to use ${keyring:github_personal_token}