MCP Server Parameter Store — AWS SSM Parameter Store hierarchical config, SecureString, GetParametersByPath

Parameter hierarchy and ECS injection

// AWS CLI: create parameters with hierarchy
aws ssm put-parameter \
  --name "/mcp-server/prod/DATABASE_URL" \
  --value "postgresql://user:pass@host:5432/db" \
  --type SecureString   # encrypted with aws/ssm KMS key (free)

aws ssm put-parameter \
  --name "/mcp-server/prod/QUEUE_URL" \
  --value "https://sqs.us-east-1.amazonaws.com/123456789/mcp-jobs" \
  --type String

aws ssm put-parameter \
  --name "/mcp-server/prod/LOG_LEVEL" \
  --value "info" \
  --type String

// CDK: ECS task definition with SSM parameter injection
import * as ssm from "aws-cdk-lib/aws-ssm";

// Reference existing SSM parameters (created outside CDK or by another stack)
const dbUrl = ssm.StringParameter.fromSecureStringParameterAttributes(this, "DbUrl", {
  parameterName: "/mcp-server/prod/DATABASE_URL",
  version: 1,   // pin to a specific version; omit for "latest"
});

const queueUrl = ssm.StringParameter.valueForStringParameter(
  this, "/mcp-server/prod/QUEUE_URL"
);

// Inject into ECS container — ECS agent fetches at task start, not at synth time
const container = taskDef.addContainer("app", {
  image: ecs.ContainerImage.fromEcrRepository(repository, imageTag),
  secrets: {
    DATABASE_URL: ecs.Secret.fromSsmParameter(dbUrl),
    // ^ Execution role automatically granted ssm:GetParameters on this ARN
  },
  environment: {
    // Non-secret values can go in environment directly
    QUEUE_URL: queueUrl,    // resolved at synth time via SSM lookup
    LOG_LEVEL: "info",
  },
});

// IAM: execution role needs GetParameters (plural) for all injected params
// CDK's ecs.Secret.fromSsmParameter() handles this automatically.
// If using raw task definition JSON (not CDK), add this manually:
executionRole.addToPolicy(new iam.PolicyStatement({
  actions: ["ssm:GetParameters"],   // PLURAL — ECS uses batch API
  resources: [
    `arn:aws:ssm:${this.region}:${this.account}:parameter/mcp-server/prod/*`,
  ],
}));

Loading all config at startup with GetParametersByPath

For MCP servers that need many configuration values, GetParametersByPath loads all parameters under a path prefix in a single (paginated) API call at application startup — far more efficient than individual GetParameter calls.

import { SSMClient, GetParametersByPathCommand } from "@aws-sdk/client-ssm";

const ssm = new SSMClient({ region: process.env.AWS_REGION ?? "us-east-1" });

interface Config {
  DATABASE_URL: string;
  QUEUE_URL: string;
  LOG_LEVEL: string;
}

async function loadConfig(path: string): Promise {
  const params: Record = {};
  let nextToken: string | undefined;

  // GetParametersByPath returns max 10 per call — paginate with NextToken
  do {
    const response = await ssm.send(new GetParametersByPathCommand({
      Path: path,           // e.g. "/mcp-server/prod/"
      Recursive: true,      // include sub-paths
      WithDecryption: true, // decrypt SecureString values
      MaxResults: 10,       // max allowed per call
      NextToken: nextToken,
    }));

    for (const param of response.Parameters ?? []) {
      if (!param.Name || !param.Value) continue;
      // Strip the path prefix to get the env var name
      // "/mcp-server/prod/DATABASE_URL" -> "DATABASE_URL"
      const key = param.Name.replace(`${path}/`, "");
      params[key] = param.Value;
    }

    nextToken = response.NextToken;
  } while (nextToken);

  // Validate required keys are present
  const required = ["DATABASE_URL", "QUEUE_URL", "LOG_LEVEL"] as const;
  for (const key of required) {
    if (!params[key]) throw new Error(`Missing required config: ${key}`);
  }

  return params as unknown as Config;
}

// Call once at startup — cache for the lifetime of the process
// For long-running processes: refresh on a timer (e.g., every 5 minutes)
const config = await loadConfig("/mcp-server/prod");
console.log(JSON.stringify({ level: "INFO", event: "config.loaded", keyCount: Object.keys(config).length }));

For ECS deployments, prefer injecting via the task definition secrets array over calling SSM at runtime — the ECS agent handles the API calls during task startup, and you don't need SSM IAM permissions on the task role. Runtime SSM calls are more appropriate for parameters that change frequently (feature flags, runtime thresholds) and need to be refreshed without a task restart.

Tier selection and cost

Standard tier is correct for MCP servers with <10,000 config parameters. Upgrade to Advanced only if you need parameter policies (e.g., auto-expiring API keys with TTL notifications via EventBridge) or value sizes over 4 KB. Switching an existing parameter from Standard to Advanced requires deleting and recreating it — the tier cannot be downgraded.

Common failure modes