Amplify Environment Variables and Secrets for MCP Server Dashboards — Build-Time, Runtime, and SSM Integration

App-level vs branch-level variable scoping

Amplify has a two-level variable hierarchy. App-level variables apply to every branch, including auto-created branches and PR previews. Branch-level variables override app-level values for a specific branch. Variables are merged at build time — if a variable exists at both levels, the branch-level value wins.

# Set app-level variables (all branches inherit)
aws amplify update-app \
  --app-id $APP_ID \
  --environment-variables \
    REACT_APP_SUPPORT_EMAIL=support@alivemcp.com,\
    REACT_APP_VERSION=1.0.0,\
    NODE_OPTIONS=--max-old-space-size=4096

# Override for the main (production) branch
aws amplify update-branch \
  --app-id $APP_ID \
  --branch-name main \
  --environment-variables \
    REACT_APP_API_URL=https://api.alivemcp.com,\
    REACT_APP_ENV=production

# Override for develop (staging) branch
aws amplify update-branch \
  --app-id $APP_ID \
  --branch-name develop \
  --environment-variables \
    REACT_APP_API_URL=https://staging-api.alivemcp.com,\
    REACT_APP_ENV=staging

# IMPORTANT: updating variables does NOT trigger a rebuild
# Always start a new job after variable changes:
aws amplify start-job \
  --app-id $APP_ID \
  --branch-name main \
  --job-type RELEASE

Branch-level --environment-variables is a complete replacement, not a merge — if you call update-branch with only one variable, you lose all previously set branch-level variables. Always include all branch-level variables in each update-branch call, or use the console to add individual variables. The app-level variables are unaffected by branch-level updates.

Secret variables and masked values

Variables marked as secrets in Amplify are stored encrypted and masked in build logs. Once saved, the value cannot be retrieved via the Amplify console or API — only the variable name is visible. This is appropriate for API keys, webhook secrets, and OAuth client secrets used during the build process.

# The Amplify console marks variables as secret via the UI toggle.
# Via CLI, pass the value via a shell variable (not plaintext in the command):

# Fetch from an existing secret store (e.g., 1Password, Vault):
STRIPE_KEY=$(op item get "Amplify Stripe Key" --fields credential)

# Set as branch-level variable — the value won't appear in shell history
# if passed via a variable (not a literal string):
aws amplify update-branch \
  --app-id $APP_ID \
  --branch-name main \
  --environment-variables \
    REACT_APP_STRIPE_PUBLISHABLE_KEY=$STRIPE_KEY

# For truly sensitive values (private keys, DB passwords):
# Do NOT store in Amplify env vars — use SSM Parameter Store instead (see below)

# Verify the variable exists (name only — value is masked):
aws amplify get-branch \
  --app-id $APP_ID \
  --branch-name main \
  --query 'branch.environmentVariables' \
  --output json
# Output: { "REACT_APP_API_URL": "...", "REACT_APP_STRIPE_PUBLISHABLE_KEY": "*****" }

Amplify secret variables are masked in build logs — the string ***** replaces the value if it's printed via echo or logged during the build. However, masking is value-based — if your build script uses the value as part of a URL or other string, the composed string may not be masked. Never log environment variable values directly in your build scripts.

Build-time vs runtime variable access (Next.js)

In Next.js, variables fall into three categories based on their prefix and how they're used. Understanding this distinction prevents the common mistake of deploying a Next.js app with undefined variables at runtime.

# Category 1: NEXT_PUBLIC_ — build-time embedded, client-visible
# Available in browser and server components, embedded in bundle
NEXT_PUBLIC_API_URL=https://api.alivemcp.com
NEXT_PUBLIC_POSTHOG_KEY=phc_abc123

# In code:
const apiUrl = process.env.NEXT_PUBLIC_API_URL;  // works in browser AND server

# Category 2: No prefix — runtime-only, server-side
# Available in API routes, Server Actions, and server components
# NOT available in client components or browser
DATABASE_URL=postgres://...
INTERNAL_API_SECRET=secret-value

# In code (server-side only):
// pages/api/sessions.ts or app/api/sessions/route.ts
export async function GET() {
  const db = await connect(process.env.DATABASE_URL);  // works server-side
  // process.env.DATABASE_URL is undefined in browser — correct behavior
}

# Category 3: Variables read at build time via next.config.ts
// next.config.ts
const nextConfig = {
  env: {
    BUILD_TIME_COMMIT: process.env.AWS_JOB_ID,  // injected by Amplify
    AMPLIFY_BRANCH: process.env.AWS_BRANCH
  }
};
// These are embedded in the bundle as literals at build time

For SSR in Amplify, runtime variables (no NEXT_PUBLIC_ prefix) must be set on the Amplify App (not just the branch), because the Lambda@Edge function environment is populated from app-level variables. Branch-level variables without NEXT_PUBLIC_ prefix do NOT flow to the Lambda@Edge runtime — this is the most common source of "environment variable undefined in production" bugs with Amplify SSR.

SSM Parameter Store integration for secrets

For secrets that must not be stored in Amplify's variable store — database connection strings, private keys, third-party API secrets — use AWS SSM Parameter Store SecureString values. Fetch them during the preBuild phase and export them as environment variables for the rest of the build.

# Store secrets in SSM Parameter Store (done once, outside Amplify):
aws ssm put-parameter \
  --name /alivemcp/prod/db-url \
  --value "postgres://user:pass@db.alivemcp.com/mcpdb" \
  --type SecureString \
  --key-id alias/aws/ssm   # use AWS managed key (or your own CMK)

aws ssm put-parameter \
  --name /alivemcp/prod/stripe-secret-key \
  --value "sk_live_..." \
  --type SecureString

# amplify.yml — fetch secrets in preBuild
version: 1
frontend:
  phases:
    preBuild:
      commands:
        - nvm use 20
        - npm ci
        - |
          # Fetch from SSM and export as env vars
          export DATABASE_URL=$(aws ssm get-parameter \
            --name /alivemcp/prod/db-url \
            --with-decryption \
            --query Parameter.Value \
            --output text)
          export STRIPE_SECRET_KEY=$(aws ssm get-parameter \
            --name /alivemcp/prod/stripe-secret-key \
            --with-decryption \
            --query Parameter.Value \
            --output text)
    build:
      commands:
        - npm run build   # DATABASE_URL and STRIPE_SECRET_KEY are available here
  artifacts:
    baseDirectory: dist
    files:
      - '**/*'

The Amplify build container runs with an IAM role that you can extend. To allow the build to call ssm:GetParameter on your parameters, add an IAM policy to the Amplify service role. In the Amplify console, go to App settings → General → Service role and attach a policy with ssm:GetParameter and kms:Decrypt (for SecureString values encrypted with a customer-managed KMS key).

Amplify-injected build variables

Amplify automatically injects several variables into the build container that you can use in build scripts and embed into the bundle for debugging and telemetry.

# Variables automatically injected by Amplify into every build:
AWS_APP_ID           # Amplify App ID (e.g., d1abc23def456)
AWS_BRANCH           # Branch being built (e.g., main, develop, pr-47)
AWS_REGION           # AWS region of the Amplify app
AWS_JOB_ID           # Build job ID (unique per build)
AWS_COMMIT_ID        # Git commit SHA that triggered the build

# Use in amplify.yml build phase:
# build:
#   commands:
#     - echo "Building branch $AWS_BRANCH at commit $AWS_COMMIT_ID"
#     - VITE_BUILD_ID=$AWS_JOB_ID npm run build

# Embed in the React app for runtime debugging:
# In vite.config.ts:
import { defineConfig } from 'vite';
export default defineConfig({
  define: {
    __BUILD_BRANCH__: JSON.stringify(process.env.AWS_BRANCH),
    __BUILD_COMMIT__: JSON.stringify(process.env.AWS_COMMIT_ID),
    __BUILD_JOB__: JSON.stringify(process.env.AWS_JOB_ID)
  }
});

Embedding AWS_BRANCH in the bundle is useful for debugging PR preview environments — you can display the branch name in the UI so testers know which PR they're reviewing. Embedding AWS_COMMIT_ID enables linking a production bug to the exact commit that introduced it. Both are non-sensitive values that are safe to expose to the browser.

Failure modes reference