Skip to content

Design FAQ: MCP/provider secrets belong on the gateway, not in the agent runtime #523

Open

Description

@vgmartinez

Why this exists

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

  1. Upstream MCP and provider secrets stay on the gateway (or a vault the gateway reads).
  2. Agents get a consumer identity with a short TTL, scoped to the tools that identity is allowed to call.
  3. Audit the decision (allow/deny + consumer id) and the upstream call, not just the model prompt.

That is the same plane as consumers + registries: https://neuraltrust-victor.hashnode.dev/consumers-and-registries-the-mcp-aggregation-plane-agents-actually-need

Open questions

  1. Where do your MCP server tokens live today (agent env, secrets manager, gateway)?
  2. How do you rotate them without bouncing every agent?

Docs PRs that turn this into a short FAQ under docs/ are welcome (link the PR here). Related open docs: #520 (never merge from this lane).


Disclosure: Building TrustGate at NeuralTrust (CTO).

Activity

  1. cainapinel commented on Nov 6, 2026

    @cainapinel
  2. cainapinel commented on Nov 6, 2026

    @cainapinel

    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:

    • 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/:

    1. Where should MCP/provider secrets live? (the table above)
    2. Why isn't a sandbox enough?
    3. 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)
    4. How do I rotate upstream keys without bouncing every agent?
    5. 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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationhelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions