[james-crowley]

Description

First of the two PRs for #1706 (the second adds ${file:} and builds on this one). Adds MCPPROXY_API_KEY_FILE, the *_FILE form used by Docker Compose/Swarm secrets, Kubernetes secret volumes and systemd LoadCredential=, so the proxy's own key need not sit in the process environment (docker inspect, /proc/<pid>/environ, crash dumps) or in mcp_config.json.

• One helper. config.ResolveEnvAPIKey is now the only reader of the environment's key. The loader (Validate), EnsureAPIKey, the CLI client (resolveAPIKey), status, the tray and the core it launches all go through it.
• Hard fail. A named file that cannot be used (missing, unreadable, relative path, over 64 KiB, empty after removing the trailing newline) stops startup with an error naming the variable and path, never the content. There is no fallback to MCPPROXY_API_KEY, the config file or a generated key, and nothing is saved. A real run with a missing file exits 4 and leaves the config byte-identical.
• Never written back. The key from the file is a process-only override, like the env key.
• Tray. When the key is in a file, the tray does not inject it into the core as MCPPROXY_API_KEY (that would put it back in the core's environment); the core inherits MCPPROXY_API_KEY_FILE and reads the file itself. The tray exits on an unusable file instead of generating a key.
• secret.ReadFile holds the read rules (absolute path, regular file after following symlinks, 64 KiB cap, exactly one trailing LF or CRLF removed, no NUL, errors never include content) so the ${file:} provider in the follow-up behaves identically.
• Config.EnsureAPIKey now also returns an error (it is internal; the five callers are updated).
• Spec 111 FR-014, FR-030 and US7 are amended so the spec covers the proxy's own key. Docs and CHANGELOG updated.

@Dumbris, one question on precedence. When both MCPPROXY_API_KEY and MCPPROXY_API_KEY_FILE are set I made the file win and log a warning, since an explicit file is the more deliberate choice and keeps the key out of the environment. The alternatives are to prefer the env var (the order the issue first described) or to refuse to start with both set, which is what some official images do. Happy to switch; it is one condition in ResolveEnvAPIKey plus its tests.

Testing

• I have tested these changes locally
• I have added/updated tests that prove my fix is effective or my feature works
• All existing tests pass

go test ./internal/config ./internal/secret ./cmd/mcpproxy ./internal/httpapi pass. By hand with a built binary: key from the file authenticates (200, no key 401), the key is absent from /proc/<pid>/environ and the config, a missing file exits 4 with the config unchanged, mcpproxy status finds the key.

Not run here: the tray is built only for macOS/Windows. It compiles for Windows; the new TestBuildCoreEnvironmentAPIKey in cmd/mcpproxy-tray/main_test.go is darwin-only and I could not compile or run it on this Linux host. The macOS native app's CoreProcessManager.swift is untouched (it removes MCPPROXY_API_KEY and passes its own key).

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 79.56989% with 19 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cmd/mcpproxy/status_cmd.go	0.00%	7 Missing ⚠️
internal/secret/file_read.go	80.55%	4 Missing and 3 partials ⚠️
cmd/mcpproxy/main.go	0.00%	3 Missing ⚠️
internal/config/config.go	89.47%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Dumbris]

Thanks, this is nicely done, especially the tray part. On precedence: please refuse to start when both MCPPROXY_API_KEY and MCPPROXY_API_KEY_FILE are set, with an error naming both variables. One unambiguous rule is easier to document than a warning somebody will miss, and it matches what the official images do. The env-over-config order you kept in #1717 (an env key wins over a ${file:} reference in api_key) is the right one there, since that is how every other env override in the config works. Review is next on my side.

[james-crowley]

Done: setting both MCPPROXY_API_KEY and MCPPROXY_API_KEY_FILE (both non-empty) now refuses to start. The error is MCPPROXY_API_KEY and MCPPROXY_API_KEY_FILE are both set; set only one of them. It is fixed text, never contains a key or file contents, and is raised without opening the file. The loader (even when the config has its own api_key), EnsureAPIKey, the CLI client, status and the tray all stop on it; the file-wins warning is gone. Tests: TestResolveEnvAPIKey_BothSetIsAnError, TestEnsureAPIKey_BothSetIsAnErrorAndNeverGeneratesAKey, TestLoad_BothSetFailsTheLoad, and the "both variables set" case in TestResolveAPIKey_Precedence. Docs, CHANGELOG and spec 111 FR-014 describe the single rule. Head is 28730ef; all checks green.

[Dumbris]

Thanks for the quick turnaround on the both-set rule. I verified the branch on a merge with main (build, the CI lint config, race tests for config, secret, tray and both binaries) and cross-reviewed it; one thing came out of that, and I pushed it on top of your branch rather than send you back for a ten-line change (77ee89e):

• secret.ReadFile called os.Open before the regular-file check. open(2) on a FIFO blocks until a writer appears, so a mis-pointed MCPPROXY_API_KEY_FILE hung startup instead of returning the documented error. It now stats the path first (the check on the open descriptor stays, for a path swapped in between), with a FIFO regression test under the unix build tag.

The CLI behaviour (warn and take the no-daemon path when the resolver errors, rather than exit) is fine by me: the core itself refuses to start, which was the ask. Merging once CI is green on the new head.

[Dumbris]

Verified on a merge with main: build, CI lint config, race tests for config, secret, tray and both binaries; cross-reviewed. The FIFO guard is on the branch; the CLI warn-and-continue behaviour is accepted.

[Dumbris]

Verified on a merge with main: build, CI lint config, race tests for config, secret, tray and both binaries; cross-reviewed. The FIFO guard is on the branch; the CLI warn-and-continue behaviour is accepted.

[Dumbris]

Merged. Thank you, @james-crowley! MCPPROXY_API_KEY_FILE through one shared helper, with a hard fail on an unusable file and a refusal when both variables are set, is exactly how container and systemd deployments want to receive the key, and the tray part was the hard half. Rebase #1717 whenever you like and I will take it next.

Contributions like this are what keep MCPProxy moving, and they matter a lot to the project.

One small ask, only if you feel like it: a short public note about your change (a tweet, a LinkedIn post, a line in a community you are part of) helps more people discover MCPProxy. No pressure at all, and I would be glad to repost it.