You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Design FAQ: MCP/provider secrets belong on the gateway, not in the agent runtime #523
A common shortcut: dump MCP server URLs plus long-lived API keys into every agent runtime (.env, Cursor config, a shared secret in the orchestrator). That is convenient for a demo and a liability in production. This note is about where secrets live, not about middleware vs gateway (#519) and not about tools/list vs egress (#521).
The cut
Where the MCP/provider secret lives
What actually happens
Agent process / laptop / CI job
Every replica, fork, log dump, and crash dump is a copy of production credentials. Rotation means touching every agent.
Per-server OAuth in each MCP config
Agents still hold refresh tokens; a compromised runtime talks to the server as the org.
Gateway-held upstream + short-lived consumer credential to the agent
Agent proves who it is. Gateway mints/expires access, applies policy, and is the only component that sees upstream MCP/provider keys.
Docker (or any sandbox) does not fix this. It contains execution. It does not stop a process from using a secret that was copied into its environment.
Practical rule
Upstream MCP and provider secrets stay on the gateway (or a vault the gateway reads).
Agents get a consumer identity with a short TTL, scoped to the tools that identity is allowed to call.
Audit the decision (allow/deny + consumer id) and the upstream call, not just the model prompt.
One angle I'd like to fold in: the issue frames agent-held secrets as convenient for a demo and a liability in production. I'd argue the FAQ should make the rule environment-agnostic. If dev, staging or demo setups keep keys in the agent runtime while prod uses gateway-held secrets:
staging stops exercising the auth path prod depends on (consumer identity, TTL, tool scoping), so a misconfigured policy only surfaces in prod;
non-prod credentials tend to be handled more loosely (shared .env files, CI logs, demo screenshots), and they often still reach real upstreams or real data;
the agent code itself diverges per environment, which is the opposite of what the gateway is supposed to buy you.
With the secret on the gateway, environments differ only in values (which upstream keys the gateway holds, consumer TTLs, rate limits), not in mechanism. The agent ships unchanged from local to prod.
Proposed outline for docs/:
Where should MCP/provider secrets live? (the table above)
Why isn't a sandbox enough?
Does this apply to dev and staging too? (the parity point, plus a minimal local setup with the gateway in Docker Compose, since local friction is the real reason people take the shortcut)
How do I rotate upstream keys without bouncing every agent?
What should be audited?
I'd also like to include a config example, tested locally, of a consumer credential with a short TTL scoped to specific tools.
QQ before I start: I saw the note on #520. Is there a convention I should follow so this PR lands in the right lane?
Activity
cainapinel commentedon Nov 6, 2026
cainapinel commentedon Nov 6, 2026
I'd like to pick this up as a docs PR.
One angle I'd like to fold in: the issue frames agent-held secrets as convenient for a demo and a liability in production. I'd argue the FAQ should make the rule environment-agnostic. If dev, staging or demo setups keep keys in the agent runtime while prod uses gateway-held secrets:
With the secret on the gateway, environments differ only in values (which upstream keys the gateway holds, consumer TTLs, rate limits), not in mechanism. The agent ships unchanged from local to prod.
Proposed outline for
docs/:I'd also like to include a config example, tested locally, of a consumer credential with a short TTL scoped to specific tools.
QQ before I start: I saw the note on #520. Is there a convention I should follow so this PR lands in the right lane?