mcp: remote server {env:...} header credentials resolve empty until service restart (global config cached forever) #54205

Summary

Remote MCP server header credentials using {env:VAR} substitution send an empty token when the background service has been running since before the variable was available: global config is cached forever (infinite TTL) inside the service, so external config edits / newly-set env vars are never picked up — GitHub's remote MCP endpoint then rejects the request with HTTP 400: Authorization header is badly formatted. A missing {env:...} variable is also silently substituted with an empty string instead of producing a diagnostic.

Environment

• opencode version: 2.0.26
• OS: Windows 10.0.26200 (win32 x64)
• Terminal: VSCode integrated terminal (TERM_PROGRAM=vscode, COLORTERM=truecolor)
• Shell: C:\WINDOWS\system32\cmd.exe
• Install/channel: latest
• Active plugins: none found in config

Reproduction

1. Add a remote MCP server to the global config (~/.config/opencode/opencode.json), e.g. the GitHub remote MCP server, using header auth with env substitution:

   {
     "mcp": {
       "servers": {
         "github": {
           "type": "remote",
           "url": "https://api.githubcopilot.com/mcp/",
           "oauth": false,
           "headers": {
             "Authorization": "Bearer {env:GITHUB_PERSONAL_ACCESS_TOKEN}"
           }
         }
       }
     }
   }

2. Start the background service (opencode serve --service); at this point the env var is not yet set in the machine/user environment.
3. Set the env var persistently (e.g. via setx GITHUB_PERSONAL_ACCESS_TOKEN ... or the Windows environment dialog) and verify the token is valid — a direct POST to the endpoint with Authorization: Bearer <token> returns HTTP 200.
4. Restart the OpenCode client (or start a new session) and attempt to connect the github MCP server (e.g. /mcps, or a new session that auto-connects).

Expected Behavior

• After the env var is set (step 3), the running service should either pick up the change (re-substitute / re-load config on file change), or clearly report that the service must be restarted so the header resolves correctly.
• If {env:VAR} resolves to an unset variable, config loading should emit a visible warning/diagnostic naming the variable (e.g. environment variable GITHUB_PERSONAL_ACCESS_TOKEN not found while loading config) instead of silently substituting an empty string that later surfaces as a confusing upstream 400 from the MCP endpoint.

Actual Behavior

The github MCP server fails on every connect attempt with:

Error POSTing to endpoint: bad request: Authorization header is badly formatted
 (HTTP 400)

opencode api get /api/config shows the header the service actually uses — the placeholder is gone but the value is empty:

"github":{"type":"remote","url":"https://api.githubcopilot.com/mcp/","headers":{"Authorization":"Bearer "}

Re-connecting via /mcps does not help; only opencode service restart (so the freshly started process inherits the new user environment and re-loads config) resolves it. A direct probe with an empty Bearer token reproduces the exact 400 from GitHub's endpoint, and a direct probe with the real token returns HTTP 200 — confirming the config syntax, endpoint, and token are all fine.

Additional Context

Relevant log lines (~/.local/share/opencode/log/opencode.log), failing in both the home directory and a project directory:

timestamp=2026-10-09T21:00:00.389Z level=WARN server=github message="mcp transport error" error="Error POSTing to endpoint: bad request: Authorization header is badly formatted\n (HTTP 400)"
timestamp=2026-10-09T21:00:00.597Z level=WARN server=github message="mcp connect failed" status.status=failed status.error="Error POSTing to endpoint: bad request: Authorization header is badly formatted\n (HTTP 400)"

Suspect source locations (from sst/opencode):

• packages/opencode/src/config/config.ts: global config is loaded once and cached with an infinite TTL — Effect.cachedInvalidateWithTTL(loadGlobal(), Duration.infinity) — and invalidate is only invoked from updateGlobal (config writes made through OpenCode itself), so external config file edits and newly-set env vars are never reflected in the running service.
• packages/opencode/src/config/variable.ts: substitution is (input.env?.[varName] ?? process.env[varName]) || "" — an unset variable silently becomes an empty string. The SubstituteInput already supports missing?: "error" | "empty", so surfacing missing variables (or at least logging a warning) seems feasible.

Frequency: consistent — fails every connect attempt until the service is restarted. Workaround: opencode service restart (from a terminal that has the env var), then reconnect.

Secrets: none included; the config file contains only the {env:...} placeholder.