set_secret
[secrets] Create or overwrite a single secret value, optionally with TTL/decay, per-env superposition, description, tags, and rotation hints.
Instructions
[secrets] Create or overwrite a single secret value, optionally with TTL/decay, per-env superposition, description, tags, and rotation hints. Use to add or update one key at a time; prefer import_dotenv for bulk .env ingest, generate_secret (with saveAs) to generate-and-store in one step, and entangle_secrets instead of duplicating the same value under two keys. Mutates the keyring (overwrites any existing value at the same key/scope), writes a 'write' event to the audit log, and triggers any matching hooks. Subject to tool policy. Returns a short confirmation text like '[scope] KEY saved' (or '[scope] KEY set for env:NAME' when env is provided).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | If set, writes this value to the named per-env state (superposition) instead of the default slot. Existing default value is preserved as state 'default'. Example: 'prod'. | |
| key | Yes | Secret key name (UPPER_SNAKE_CASE recommended). Example: 'STRIPE_SECRET_KEY'. | |
| tags | No | Tag list for filtering and hook matching. Example: ['production', 'payments']. | |
| orgId | No | Organization identifier for org-scoped secrets. Required only when scope='org'. Example: 'acme-corp'. | |
| scope | No | Where the secret lives. 'global' = user keyring (default if omitted on reads), 'project' = scoped to projectPath, 'team' = team-shared (needs teamId), 'org' = org-shared (needs orgId). | global |
| value | Yes | The secret value to store. Stored as-is; never logged or echoed. May be empty only when `env` is provided to register a new env without a default. | |
| teamId | No | Team identifier for team-scoped secrets. Required only when scope='team'. Example: 'acme-platform'. | |
| ttlSeconds | No | Quantum decay window in seconds. After this many seconds the secret is marked expired (still readable, but `has_secret` returns false and `health_check` flags it). Omit for no decay. | |
| description | No | Free-text human-readable description shown in `inspect_secret` and the dashboard. | |
| projectPath | No | Absolute path to the project root for project-scoped secrets and policy resolution. Defaults to the MCP server's current working directory when omitted. | |
| rotationFormat | No | Format used by `agent_scan --autoRotate` and `rotate_secret` when this secret expires. Pick the format that matches the upstream service's accepted shape. | |
| rotationPrefix | No | Literal prefix prepended on auto-rotation (only used with rotationFormat 'api-key' or 'token'). Example: 'sk-'. |