Secrets

Workspace secrets store sensitive credentials — API keys, tokens, webhook URLs — that MCP servers need to operate. Secrets are encrypted at rest using AES-GCM and decrypted only at the moment a tool call is made.

---

How Secrets Work

1. You create a secret with a key name and value (for example, GITHUB_TOKEN = ghp_abc123...)
2. Aerostack encrypts the value with AES-GCM and stores only the ciphertext
3. When you add a server to the workspace, you specify which secrets it needs via inject_secrets
4. At call time, the gateway decrypts the relevant secrets and injects them into the upstream request

---

Injection Methods

Secrets are injected differently depending on the server’s auth type:

Server Auth Type	How Secrets Are Injected
secret-headers (default)	As X-Mcp-Secret-{KEY} HTTP headers
bearer	As Authorization: Bearer {value} header
Skills (function-backed)	In the request body as { secrets: { KEY: value } }

Note

The X-Mcp-Secret- header key format converts underscores to hyphens. For example, GITHUB_TOKEN becomes X-Mcp-Secret-GITHUB-TOKEN.

---

Create or Update a Secret

Secrets use upsert semantics — if a secret with the same key name already exists, the value is overwritten.

Dashboard

Open your workspace, go to the Secrets tab, and click Add Secret. Enter the key name and value. If a secret with that key already exists, the value is replaced.

CLI

aerostack workspace secret set my-workspace GITHUB_TOKEN ghp_abc123def456...

Key Name Normalization

Secret key names are automatically normalized:

• Converted to uppercase
• Non-alphanumeric characters (except underscore) replaced with _

Examples:

• github-token becomes GITHUB_TOKEN
• my.api.key becomes MY_API_KEY
• SlackWebhook becomes SLACKWEBHOOK

---

List Secrets

View all secret key names in a workspace. Secret values are never returned — only names and metadata.

Dashboard

Open your workspace and click the Secrets tab. You will see a list of all secret key names with their creation dates.

CLI

aerostack workspace secret list my-workspace

  KEY                  CREATED
  GITHUB_TOKEN         2026-03-15
  SLACK_BOT_TOKEN      2026-03-15
  LINEAR_API_KEY       2026-03-16

Caution

Secret values are write-only. Once stored, the plaintext value cannot be retrieved through the API or dashboard. If you need to change a value, create a new secret with the same key name to overwrite it.

---

Delete a Secret

Dashboard

Open the workspace, go to Secrets, find the secret, and click Delete.

CLI

aerostack workspace secret delete my-workspace GITHUB_TOKEN

Note

Deleting a secret does not automatically update server inject_secrets configurations. Servers that reference a deleted secret will simply not receive it — they will not error, but the server may fail if it requires the credential.

---

Connecting Secrets to Servers

When you add a server to your workspace, you specify which secrets it should receive via the inject_secrets configuration.

Dashboard

When adding or editing a server in the workspace, select the secrets to inject from a dropdown of available workspace secrets.

CLI

# Add a server with secret injection
aerostack workspace server add my-workspace @aerostack/github --secrets GITHUB_TOKEN

# Update which secrets a server receives
aerostack workspace server update my-workspace github --secrets GITHUB_TOKEN,GITHUB_WEBHOOK_SECRET

Only the secrets listed in inject_secrets are sent to that server. A server never receives secrets not explicitly assigned to it.

---

Per-Server Scoping

Each server in a workspace can receive a different set of secrets. This is the recommended pattern:

Workspace: dev-tools
  Secrets: GITHUB_TOKEN, LINEAR_API_KEY, SLACK_BOT_TOKEN

  Server: GitHub MCP     → inject_secrets: [GITHUB_TOKEN]
  Server: Linear MCP     → inject_secrets: [LINEAR_API_KEY]
  Server: Slack MCP      → inject_secrets: [SLACK_BOT_TOKEN]

The GitHub server only receives GITHUB_TOKEN. It never sees the Linear or Slack credentials. This follows the principle of least privilege.

---

Security

• Encrypted at rest — secrets are encrypted with AES-GCM before storage
• Decrypted only at call time — the plaintext value exists in memory only during the upstream request
• Never cached in plaintext — the gateway decrypts on every call
• Scoped to a workspace — secrets are not shared across workspaces
• Write-only — once stored, the value cannot be retrieved through any API

---

Common Patterns

Multi-Service Workspace

A workspace with multiple servers, each needing different credentials:

# Create secrets
aerostack workspace secret set dev-tools GITHUB_TOKEN ghp_abc...
aerostack workspace secret set dev-tools LINEAR_API_KEY lin_abc...
aerostack workspace secret set dev-tools SLACK_BOT_TOKEN xoxb-abc...

# Each server gets only the secrets it needs
# GitHub → GITHUB_TOKEN
# Linear → LINEAR_API_KEY
# Slack → SLACK_BOT_TOKEN

Shared Secrets

Multiple servers can reference the same secret. For example, if two servers both need a database URL:

aerostack workspace secret set my-workspace DATABASE_URL postgres://...
# Both Server A and Server B inject DATABASE_URL

Rotating Secrets

To rotate a secret, overwrite it with a new value. The change takes effect immediately for all servers that inject it:

aerostack workspace secret set my-workspace GITHUB_TOKEN ghp_new_value...

No restarts needed — the gateway decrypts secrets fresh on every call.

---

Plan Limits

Plan	Secrets per Workspace
Free	10
Starter	50
Pro	200
Business	1,000
Enterprise	Unlimited