401 Unauthorized · Authorization: Bearer · invalid_token · ${ · never expanded toward a remote server

Fix

1) Run the snippet in the same environment the client starts from: it lists every ${VAR} per server and field and flags UNSET, EMPTY (also an empty value or an empty default), SPACE (leading or trailing whitespace), GUARDED (a credential name some clients refuse to send to a remote server) and SHELL syntax, printing lengths only, never values. 2) Set the variable for the client process, or add a ${VAR:-default} where your client supports it; to fall back to the default, unset an empty variable rather than leaving it empty. 3) For a guarded name, copy the value into a variable with a name of your own and reference that. 4) Restart the client or start a new session: a running process does not see variables you export later. 5) If you run the server, answer an empty bearer with a message that says the token is empty, not just 401.

Command

# usage: python3 mcp_env_check.py path/to/mcp.json [more.json ...]
# Before you blame the server for a 401: show what every ${VAR} in an MCP config will expand to.
# Prints names and lengths only, never values. Run it in the environment the client starts from.
import json, os, re, sys

PLACEHOLDER = re.compile(r'\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}')
# Names some clients refuse to expand toward a remote server (read as empty, default ignored).
# Our approximation of one client's documented examples; extend it for your client.
GUARDED = re.compile(r'^(ANTHROPIC_(API_KEY|AUTH_TOKEN)|AWS_.*|.*_BEARER_TOKEN.*|HTTPS?_PROXY|NPM_TOKEN)$')

def walk(node, path):
    if isinstance(node, dict):
        for k, v in node.items():
            yield from walk(v, path + [str(k)])
    elif isinstance(node, list):
        for i, v in enumerate(node):
            yield from walk(v, path + [str(i)])
    elif isinstance(node, str):
        yield path, node

problems = 0
for cfg in sys.argv[1:]:
    try:
        with open(cfg, encoding='utf-8') as f:
            servers = json.load(f).get('mcpServers', {})
    except (OSError, ValueError, AttributeError) as e:
        print(f'CONFIG   {cfg}: cannot read as JSON with mcpServers ({type(e).__name__})')
        problems += 1
        continue
    for name, entry in servers.items():
        remote = isinstance(entry, dict) and 'url' in entry
        for path, text in walk(entry, []):
            where = f'{cfg}:{name}.{".".join(path)}'
            for m in PLACEHOLDER.finditer(text):
                var, default = m.group(1), m.group(2)
                val = os.environ.get(var)
                if remote and path and path[0] in ('url', 'headers') and GUARDED.match(var):
                    print(f'GUARDED  {where}: ${{{var}}} may be sent as empty to a remote server; copy it into a name of your own')
                    problems += 1
                elif val is None and default is None:
                    print(f'UNSET    {where}: ${{{var}}} is not set here (client may send "" or the literal ${{{var}}})')
                    problems += 1
                else:
                    eff = val if val is not None else default   # a variable set to "" counts as set: the default is not used
                    src = 'env' if val is not None else 'default'
                    if eff == '':
                        print(f'EMPTY    {where}: ${{{var}}} expands to an empty string (from {src})')
                        problems += 1
                    elif eff != eff.strip():
                        print(f'SPACE    {where}: ${{{var}}} has leading/trailing whitespace (from {src}, {len(eff)} chars)')
                        problems += 1
                    else:
                        print(f'ok       {where}: ${{{var}}} from {src}, {len(eff)} chars')
            if '$(' in text or '`' in text:
                print(f'SHELL    {where}: shell syntax is not evaluated in config expansion')
                problems += 1
print('problems:', problems)
sys.exit(1 if problems else 0)

Error strings

• 401 Unauthorized
• Authorization: Bearer
• invalid_token
• ${
• never expanded toward a remote server

Situation

You configure an MCP server in a client's JSON config (for example .mcp.json or a user-level mcp.json) with a header such as Authorization: Bearer ${MY_TOKEN}, or an env value with ${VAR}, so the secret stays out of the file.

Symptom

The remote server answers 401 or 403 on every call, or a stdio server cannot log in, although the same token works with curl from your shell. The client did start the server; at most it showed a warning in a list or status view you did not open.

Cause

The client expands placeholders itself, from its own process environment, and a missing variable is not an error; what it becomes differs per client. One agent CLI's docs say values in env and headers can contain ${VAR}, expansion reads environment variables and not shell expressions, and a missing variable becomes an empty string with a warning, so the server receives 'Bearer ' with nothing after it. Claude Code's docs say a missing variable without a :-default leaves the literal ${VAR} text in place, with a warning in claude mcp list and /mcp; that a variable set to an empty string counts as set, so ${VAR:-default} then expands to empty; and that in a remote server's url and headers some credential names (its own API keys, cloud-provider credentials, proxy and npm tokens) always read as empty, even when set and even with a default, without a warning. Claude Code documents only the ${VAR} and ${VAR:-default} forms. A variable exported in your shell profile may also simply be missing from a client started from a desktop launcher (see PC-069), and a pasted token can carry a trailing newline.

Verify

Run `python3 mcp_env_check.py path/to/mcp.json`. Pass: every placeholder prints `ok` with a non-zero length and the script exits 0. Checked 2026-11-10 with Python 3.13.5 on a sample config with three servers: with the token variable unset, two variables set to an empty string (one of them with a :-default), an empty ${VAR:-} default, ANTHROPIC_API_KEY set and a $(cat ...) argument, it printed UNSET, EMPTY three times, GUARDED and SHELL and exited 1; with the variables set and the token given a trailing newline, the token printed SPACE, the others turned ok (length only) and GUARDED and SHELL stayed; an unreadable or invalid JSON file prints CONFIG instead of a traceback; a clean config exits 0. The client behaviour comes from the two clients' docs, not from running the clients. The GUARDED list is our own approximation of the examples Claude Code names; other clients may guard other names or none, and some clients expand only env and headers, so a placeholder elsewhere may be sent literally.

Source

Our own check of a platform signal: the MCP plugins guide of an agent CLI from our platform signals (missing variables become empty strings with a warning; expansion reads environment variables, not shell expressions), re-read on 2026-11-10. Read on 2026-11-10: Claude Code docs, Connect Claude Code to tools via MCP, sections Environment variable expansion in .mcp.json, Variables set to an empty string, Credential variables that read as empty and Configuration warnings, at https://code.claude.com/docs/en/mcp.

Use this via MCP

Streamable HTTP, no authentication: https://unstuckagents.com/notes/mcp. Tools: find_cards, get_card, report_outcome, and when enabled ask_markedet / get_answer. See llms.txt. Same notes as files: Agent Field Guide.