Skip to content
Aerostack v1.0-beta

Secrets & Security

Every MCP server connected to Aerostack — whether hosted, proxied, or installed from the Hub — can have secrets (API keys, tokens, credentials) that are needed to call external APIs. Aerostack encrypts these secrets at rest and injects them at request time. Team members who connect via workspace tokens never see the raw values.

How Secrets Work

Section titled “How Secrets Work”

At Request Time

Team member calls
github__create_issue

Gateway decrypts secret

Injects as HTTP header
Authorization: Bearer ghp_xxx

Forwards to MCP server

At Rest

You set a secret
aerostack secrets set github GITHUB_TOKEN ghp_xxx

AES-256-GCM
Encrypted + stored in
mcp_workspace_secrets table

Encryption Details

Section titled “Encryption Details”
PropertyValue
AlgorithmAES-256-GCM
Storagemcp_workspace_secrets table in the database
Encryption keyPer-project WORKFLOW_SECRETS_KEY (never stored in the database)
IVUnique random IV per secret value
Auth tag128-bit GCM authentication tag (integrity + authenticity)

Secrets are encrypted before they reach the database. The encryption key (WORKFLOW_SECRETS_KEY) is stored as a Cloudflare Worker secret, separate from the database.

Per-Server Scoping

Section titled “Per-Server Scoping”

Secrets are scoped to a specific MCP server within your workspace. This means:

  • Secrets set for github-mcp are only sent to the GitHub MCP server
  • They are never sent to slack-mcp, stripe-mcp, or any other server in the same workspace
  • Even if an MCP server is compromised, it cannot access secrets belonging to other servers

The scoping is enforced by the inject_secrets configuration, which maps secret names to specific MCP server slugs.

Terminal window
# These secrets are isolated from each other
aerostack secrets set github-mcp GITHUB_TOKEN "ghp_xxx"     # Only sent to github-mcp
aerostack secrets set stripe-mcp STRIPE_KEY "sk_live_xxx"    # Only sent to stripe-mcp
aerostack secrets set slack-mcp  SLACK_TOKEN "xoxb-xxx"      # Only sent to slack-mcp

Setting Secrets

Section titled “Setting Secrets”

Via CLI

Section titled “Via CLI”
Terminal window
# Basic usage
aerostack secrets set <mcp-slug> <SECRET_NAME> "<value>"


# Examples
aerostack secrets set github-mcp GITHUB_TOKEN "ghp_xxxxxxxxxxxx"
aerostack secrets set postgres-mcp DATABASE_URL "postgres://user:pass@host:5432/db"
aerostack secrets set openai-mcp OPENAI_API_KEY "sk-proj-xxxxxxxxxxxx"

Via Admin Dashboard

Section titled “Via Admin Dashboard”
  1. Navigate to MCP Servers > select your server > Secrets
  2. Click Add Secret
  3. Enter the name and value
  4. Click Save

The value is encrypted immediately. After saving, the dashboard shows the secret name but never the raw value.

Via API

Section titled “Via API”
Terminal window
curl -X POST https://api.aerostack.dev/api/v1/admin/mcp-servers/{serverSlug}/secrets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "GITHUB_TOKEN", "value": "ghp_xxxxxxxxxxxx"}'

Secret Injection

Section titled “Secret Injection”

When a tool call reaches the gateway, secrets are decrypted and injected into the outbound request to the MCP server. You control how each secret is injected.

As HTTP Headers (Default)

Section titled “As HTTP Headers (Default)”

By default, each secret is injected as an HTTP header with the secret name as the header key:

Secret: GITHUB_TOKEN = "ghp_xxx"
Injected as: GITHUB_TOKEN: ghp_xxx

As a Custom Header

Section titled “As a Custom Header”

Map a secret to a specific header name:

Terminal window
aerostack secrets inject github-mcp GITHUB_TOKEN --header "Authorization"
# Injected as: Authorization: ghp_xxx


aerostack secrets inject my-api API_KEY --header "X-API-Key"
# Injected as: X-API-Key: sk-xxx

As Bearer Auth

Section titled “As Bearer Auth”

A shorthand for injecting as Authorization: Bearer <value>:

Terminal window
aerostack secrets inject github-mcp GITHUB_TOKEN --bearer
# Injected as: Authorization: Bearer ghp_xxx

Viewing Injection Rules

Section titled “Viewing Injection Rules”
Terminal window
aerostack secrets list github-mcp
# SECRET NAME      INJECTION           LAST UPDATED
# GITHUB_TOKEN     Authorization       2026-03-15
# WEBHOOK_SECRET   X-Webhook-Secret    2026-03-10

Key Rotation

Section titled “Key Rotation”

Rotating a secret is a single command. Every team member gets the new key automatically on their next tool call — no notification, no .env file updates, no downtime.

  1. Update the secret

    Terminal window
    aerostack secrets set github-mcp GITHUB_TOKEN "ghp_new_token_here"
    # -> Secret updated. Takes effect on next tool call.

  2. Verify (optional)

    Make a tool call through the gateway and confirm it works with the new key. The old key is overwritten and cannot be recovered.

That is the entire process. Compare this to rotating a key shared with 30 engineers via .env files.

Deleting Secrets

Section titled “Deleting Secrets”
Terminal window
# Delete a specific secret
aerostack secrets delete github-mcp GITHUB_TOKEN


# Delete all secrets for an MCP server (e.g., when removing the server)
aerostack secrets delete github-mcp --all

Deleting a secret removes it from the encrypted store. The MCP server will no longer receive it in subsequent requests.

Security Model

Section titled “Security Model”

What team members can see

Section titled “What team members can see”
InformationVisible to team members?
Workspace gateway URLYes
Their own mwt_ tokenYes (shown once at creation)
Secret names (e.g., GITHUB_TOKEN)No
Secret values (e.g., ghp_xxx)No
Tool call resultsYes (their own calls only)
Analytics (who called what)Workspace admins only

What workspace admins can see

Section titled “What workspace admins can see”
InformationVisible to admins?
Secret namesYes
Secret valuesNo (encrypted, no retrieval API)
All team members’ analyticsYes
Token list and statusYes

Attack surface

Section titled “Attack surface”
ThreatMitigation
Compromised developer laptopRevoke their mwt_ token. Production keys untouched.
Database breachSecrets are AES-256-GCM encrypted. Attacker gets ciphertext only.
MCP server compromisePer-server scoping. Compromised server only has its own secrets.
Stolen workspace tokenRevoke the token. Issue a new one. No key rotation needed.
Insider threat (admin)Admins cannot retrieve raw secret values. Only set/overwrite.

Best Practices

Section titled “Best Practices”

  1. Use per-server secrets. Do not reuse the same API key across multiple MCP servers. If one server is compromised, only its secrets are exposed.

  2. Rotate keys periodically. Aerostack makes rotation painless — update once, effective everywhere.

  3. Use least-privilege API keys. When creating API keys for MCP servers, grant only the permissions the server needs. A GitHub MCP server does not need admin access — repo scope is usually sufficient.

  4. Monitor analytics. Review per-user tool call logs regularly. Unusual patterns (e.g., a user making 10,000 API calls overnight) may indicate a compromised token.

  5. Revoke tokens promptly. When a team member leaves or changes roles, revoke their workspace token immediately.

  6. Separate workspaces by trust level. Create different workspaces for different access levels. Senior engineers get the workspace with deploy tools. Junior engineers get the read-only workspace.

Next Steps

Section titled “Next Steps”