MCP server secrets management: Vault, AWS Secrets Manager, and the .env anti-pattern

Why .env files are the wrong answer

The .env convention emerged from the twelve-factor app methodology, where it was never intended as a security control — it was a developer ergonomics tool to keep local config out of version control. Somewhere along the way, the ecosystem conflated "not checked in by default" with "secure." It is not. A .env file sitting on a production server is a plaintext credential store with five distinct exposure vectors.

The SkillAudit scanner checks for all five vectors. The three secrets it finds most often in community MCP server repositories are AWS_ACCESS_KEY_ID, DATABASE_URL, and OPENAI_API_KEY — all high-value targets that would allow an attacker to access cloud infrastructure, production data, or AI API billing accounts.

The runtime fetch pattern

The correct alternative to dotenv is to fetch secrets from a secrets manager at server startup, hold them in a sealed in-memory object, and never write them back to process.env. This breaks the exposure vectors above: there is no file on disk to commit, nothing in process.env to inspect or serialize, and the secret value is a single in-memory string whose lifecycle you control.

WRONG — dotenv loaded into process.env at startup

// WRONG: secrets land in process.env — a shared, mutable, globally-accessible object.
// Any require()'d module, any error reporter, any docker inspect call can read them.
import 'dotenv/config';

const db = new DatabaseClient({
  connectionString: process.env.DATABASE_URL,  // WRONG: read from global env
  apiKey: process.env.OPENAI_API_KEY,          // WRONG: any module can mutate this
});

// WRONG: process.env is mutable — a buggy module can accidentally overwrite it
// process.env.DATABASE_URL = 'corrupted-value'; // silently accepted by Node.js

RIGHT — fetch from AWS Secrets Manager at startup, store in a frozen object

// RIGHT: fetch secrets once at startup from a managed store.
// Store in a sealed object — never in process.env.
import {
  SecretsManagerClient,
  GetSecretValueCommand,
} from '@aws-sdk/client-secrets-manager';

const smClient = new SecretsManagerClient({ region: process.env.AWS_REGION ?? 'us-east-1' });
// Note: AWS_REGION is configuration, not a secret. It is fine in env.
// Credentials come from the EC2/ECS instance metadata service — NOT from env vars.

async function loadSecrets() {
  const [dbSecret, openaiSecret] = await Promise.all([
    smClient.send(new GetSecretValueCommand({ SecretId: 'prod/mcp-server/database' })),
    smClient.send(new GetSecretValueCommand({ SecretId: 'prod/mcp-server/openai' })),
  ]);

  const db = JSON.parse(dbSecret.SecretString);
  const ai = JSON.parse(openaiSecret.SecretString);

  // RIGHT: store in a frozen object — Object.freeze prevents accidental mutation
  // and makes it immediately obvious to code reviewers that this is sealed config.
  return Object.freeze({
    databaseUrl: db.connection_string,
    openaiApiKey: ai.api_key,
  });
}

// RIGHT: await secrets before registering any MCP tool handlers
const secrets = await loadSecrets();

// RIGHT: pass secrets explicitly to the components that need them
const db = new DatabaseClient({ connectionString: secrets.databaseUrl });
const aiClient = new OpenAIClient({ apiKey: secrets.openaiApiKey });

Scoping secrets to the narrowest context

process.env is a process-wide mutable object. Every module in your Node.js process — including every transitive dependency — can read from and write to it. When you store your OPENAI_API_KEY in process.env, you are sharing it with every npm package your server has ever installed, including ones you've never audited.

The correct pattern is dependency injection: pass secrets as constructor arguments or function parameters to the specific component that needs them, and nowhere else. This also makes secrets easy to mock in tests, and makes your security surface immediately legible from the function signature.

WRONG — module reads from process.env directly

// WRONG: openai-client.js reads from process.env directly.
// This means the secret must be in process.env for the module to work,
// which forces you to store it there — and gives every other module access to it too.

// openai-client.js
export class OpenAIClient {
  constructor() {
    // WRONG: reads from a global — invisible dependency, untestable, globally exposed
    this.apiKey = process.env.OPENAI_API_KEY;
    if (!this.apiKey) throw new Error('OPENAI_API_KEY not set');
  }

  async complete(prompt) {
    // uses this.apiKey
  }
}

// main.js — the caller has no idea where the secret comes from
const client = new OpenAIClient(); // WRONG: magic dependency on process.env

RIGHT — API key injected via constructor argument

// RIGHT: openai-client.js receives its API key as a constructor argument.
// The secret never touches process.env. The caller controls the secret's lifetime.
// Tests can inject a mock key without any environment manipulation.

// openai-client.js
export class OpenAIClient {
  #apiKey; // RIGHT: private field — not accessible from outside the class

  constructor({ apiKey }) {
    if (typeof apiKey !== 'string' || apiKey.length === 0) {
      throw new TypeError('OpenAIClient requires a non-empty apiKey');
    }
    this.#apiKey = apiKey;
  }

  async complete(prompt) {
    const response = await fetch('https://api.openai.com/v1/chat/completions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.#apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ model: 'gpt-4o', messages: [{ role: 'user', content: prompt }] }),
    });
    return response.json();
  }
}

// main.js — the secret's provenance is explicit and auditable
const secrets = await loadSecrets(); // from Vault or AWS Secrets Manager
const client = new OpenAIClient({ apiKey: secrets.openaiApiKey }); // RIGHT: injected

This pattern extends naturally to MCP tool handlers. Rather than accessing a module-level process.env variable inside a server.tool() handler, close over the injected secret in the handler factory. This also makes it trivial to swap in a refreshed secret when rotation occurs — which brings us to the next pattern.

Secret rotation without restart

Secrets expire. AWS Secrets Manager can be configured to rotate a database password on a 30-day schedule; Vault leases have TTLs measured in hours. A server that reads secrets once at startup and caches them for its lifetime will fail on the next request after a rotation event. The naive fix — restarting the server — creates downtime and requires operational coordination every time a secret rotates.

The correct pattern is a refreshing cache: an in-memory store that tracks the age of each cached secret and re-fetches transparently when the TTL expires. The cache returns the cached value for most calls (fast path), and re-fetches asynchronously or synchronously only when the TTL is exceeded. Tool handlers call secretCache.get('secret-name') — they are never aware of rotation happening underneath.

RIGHT — SecretCache class with TTL-based refresh

// secret-cache.js
import {
  SecretsManagerClient,
  GetSecretValueCommand,
} from '@aws-sdk/client-secrets-manager';

const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes — re-fetch well before rotation window

export class SecretCache {
  #client;
  #ttlMs;
  #store = new Map(); // secretId -> { value, fetchedAt, inflightPromise }

  constructor({ region, ttlMs = DEFAULT_TTL_MS } = {}) {
    this.#client = new SecretsManagerClient({ region: region ?? 'us-east-1' });
    this.#ttlMs = ttlMs;
  }

  async get(secretId) {
    const entry = this.#store.get(secretId);
    const now = Date.now();

    // Return cached value if still fresh
    if (entry && !entry.inflightPromise && now - entry.fetchedAt < this.#ttlMs) {
      return entry.value;
    }

    // If a fetch is already in flight for this secret, reuse the same promise
    // to avoid thundering-herd fetches when multiple tool handlers call get() concurrently
    if (entry?.inflightPromise) {
      return entry.inflightPromise;
    }

    // Kick off a new fetch
    const inflightPromise = this.#fetch(secretId).then((value) => {
      // Atomic swap: replace the stale entry with the fresh value
      this.#store.set(secretId, { value, fetchedAt: Date.now(), inflightPromise: null });
      return value;
    }).catch((err) => {
      // On fetch failure: clear inflight, return stale value if available, else throw
      this.#store.set(secretId, entry ? { ...entry, inflightPromise: null } : undefined);
      if (entry) {
        console.warn({ secretId, err }, 'Secret refresh failed — using stale value');
        return entry.value;
      }
      throw err;
    });

    // Record the inflight promise so concurrent callers reuse it
    this.#store.set(secretId, { ...(entry ?? {}), inflightPromise });
    return inflightPromise;
  }

  async #fetch(secretId) {
    const cmd = new GetSecretValueCommand({ SecretId: secretId });
    const resp = await this.#client.send(cmd);
    // SecretString for JSON/plaintext secrets; SecretBinary for binary blobs
    const raw = resp.SecretString ?? Buffer.from(resp.SecretBinary).toString('utf-8');
    return JSON.parse(raw);
  }
}

// Usage in your MCP server entrypoint:
const secretCache = new SecretCache({ region: 'us-east-1', ttlMs: 4 * 60 * 1000 });

// Tool handler — fetches fresh secret on each call if TTL exceeded, cached otherwise
server.tool('query-database', async ({ sql }) => {
  const { connection_string } = await secretCache.get('prod/mcp-server/database');
  const db = await getPooledConnection(connection_string);
  return db.query(sql);
});

HashiCorp Vault integration for MCP servers

Vault is a popular choice for organizations that run their own infrastructure or want more control over the secrets management lifecycle than cloud-managed services provide. The key auth mechanism for automated workloads is AppRole: a machine-identity auth method that issues a Vault token in exchange for a RoleID and a SecretID. The RoleID is effectively a username — it identifies which application is authenticating. The SecretID is a one-time-use password that wraps a short-lived token.

The operational challenge is the bootstrapping problem: you need a secret (the SecretID) to get your secrets. The naive solution — storing the SecretID in a .env file — recreates the problem you were trying to solve. The correct pattern is Vault's Response Wrapping: a Vault agent or init container fetches a wrapped token for the SecretID and delivers it to the application's filesystem via a tmpfs mount. The wrapped token is single-use and short-lived, so exposure after delivery is harmless.

WRONG — SecretID hardcoded in environment variable

// WRONG: SecretID in environment variable recreates the .env problem.
// Anyone with docker inspect access or /proc access can retrieve it.
// A leaked SecretID can be used to impersonate your application to Vault.

import 'dotenv/config';

const vaultToken = await fetchVaultToken({
  roleId: process.env.VAULT_ROLE_ID,       // WRONG: leaked via process.env
  secretId: process.env.VAULT_SECRET_ID,   // WRONG: plaintext credential in env
  vaultAddr: process.env.VAULT_ADDR,
});

// Now all your real secrets are accessible — but the credential to fetch them
// is sitting in a place every module, error reporter, and sidecar can read.

RIGHT — SecretID delivered via wrapped token from Vault agent, read from tmpfs

// WRONG: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in environment variables.
// These are long-lived credentials that don't rotate automatically.
// They are leaked by docker inspect, /proc/PID/environ, error reporters, and CI logs.
// The SkillAudit scanner flags this pattern as a Critical finding.

import 'dotenv/config';

const smClient = new SecretsManagerClient({
  region: 'us-east-1',
  credentials: {
    // WRONG: static credentials in process.env — exposed to every module
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
});

// audit-logger.js — structured log emitter for secret access events

export function logSecretAccess({ secretId, requestor, source, success, durationMs }) {
  // RIGHT: structured JSON log — parseable by any SIEM or log aggregator
  // RIGHT: logs the secret *identifier*, never the secret *value*
  const event = {
    event: 'secret.access',
    timestamp: new Date().toISOString(),
    secret_id: secretId,        // RIGHT: name/ARN only
    requestor,                  // which tool handler or component fetched this
    source,                     // 'cache' | 'live-fetch'
    success,                    // false if fetch threw an error
    duration_ms: durationMs,    // slow fetches indicate Vault/SM availability issues
    // WRONG would be: secret_value: actualSecret  <-- never do this
  };

  // Emit to stdout — let the logging infrastructure handle routing
  // In production, this goes to CloudWatch Logs, Datadog, or your SIEM
  process.stdout.write(JSON.stringify(event) + '\n');
}

// Wrap SecretCache.get() to emit audit events automatically
export class AuditedSecretCache extends SecretCache {
  async get(secretId, { requestor = 'unknown' } = {}) {
    const start = Date.now();
    const cachedEntry = this._peekCache?.(secretId); // check without fetching
    try {
      const value = await super.get(secretId);
      logSecretAccess({
        secretId,
        requestor,
        source: cachedEntry ? 'cache' : 'live-fetch',
        success: true,
        durationMs: Date.now() - start,
      });
      return value;
    } catch (err) {
      logSecretAccess({ secretId, requestor, source: 'live-fetch', success: false, durationMs: Date.now() - start });
      throw err;
    }
  }
}

// config.js — single validated accessor for all environment-sourced config
// This is the ONLY file that should read from process.env.
// All other modules receive config as constructor arguments or function parameters.

function requireEnv(key) {
  const value = process.env[key];
  if (value === undefined || value === '') {
    // Fail at startup — don't let the server start with missing config.
    // This surfaces misconfiguration immediately rather than on the first request.
    throw new Error(
      `Required environment variable "${key}" is not set. ` +
      `Check your deployment config or secrets manager integration.`
    );
  }
  return value;
}

// RIGHT: all process.env reads are here and only here
export const config = Object.freeze({
  // Non-sensitive configuration — fine in env vars
  awsRegion: requireEnv('AWS_REGION'),
  vaultAddr: process.env.VAULT_ADDR ?? 'https://vault.internal.example.com',
  port: parseInt(process.env.PORT ?? '3000', 10),
  nodeEnv: process.env.NODE_ENV ?? 'production',

  // Secrets are NOT here — they come from the secrets manager at runtime.
  // This makes it structurally impossible to accidentally log or expose them
  // via config.toString() or JSON.stringify(config).
});

// Usage elsewhere — import config, not process.env
import { config } from './config.js';
const secretCache = new SecretCache({ region: config.awsRegion });