Skip to main content
Glama

Manage secrets

manage_secrets

Create or change secrets; previous values always stay in the version history and no value is ever echoed back. Deleting a secret is delete_item. action set: create one key or replace its value in one environment; kind and note are kept unless passed, and expectedVersion (from list_project_items item secrets) writes only if nobody changed the key since. action import: create or update many keys in one environment from dotenv text (KEY=value lines); existing keys are kept unless overwrite is true, and protected, sealed, invalid or out-of-limit keys are skipped and named. action copy: copy keys from one environment to another without the values passing through you (the server re-encrypts them); run find_secret_keys action diff first; existing target keys are kept unless overwrite. action restore: make an earlier version (from find_secret_keys action history) the new current value; the replaced value stays in history, so a restore can be undone. Protected and sealed keys are refused for set and restore, skipped and named for import and copy. Audited. Requires secrets:write and the editor role; copy also needs secrets:read on the source and restore secrets:read on the key.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>",
      "project": "<project>"
    },
    "name": "manage_secrets"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNocopy only: the target environment
keyNoset, restore: the key
fromNocopy only: the source environment
keysNocopy only: only these keys (default: all)
kindNoset, import: secret (masked, the default for a new key) or plain (shown unmasked, for non-sensitive settings). Omit it to keep a key's current kind
noteNoset only: short note shown next to the key, up to 500 characters. Omit it to keep the current note
textNoimport only: dotenv text, KEY=value per line, up to 256 KB; comments and blank lines are ignored
valueNoset only: the value to store, up to 64 KB, encrypted at rest
actionYesWhat to do
projectYesProject slug or id
versionNorestore only: the version number to bring back, as find_secret_keys action history lists it; must be older than the current one
overwriteNoimport, copy: replace existing values (each replaced value stays in the version history). Default false
environmentNoset, import, restore: the environment written
expectedVersionNoset only: update only if the key is still at this version; a changed, renamed or deleted key fails instead of being written over or created

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses version-history retention, non-echo of values, optimistic concurrency via expectedVersion, import skip behavior, copy re-encryption, restore reversibility, protected/sealed key handling, audit logging, and permission requirements. These are meaningful behavioral traits an agent needs for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but front-loaded and organized by action labels ('action set', 'action import', etc.). It contains little wasted wording, though the semicolon-heavy prose is harder to scan than a more structured layout would be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 14-parameter, four-action mutation tool, the description covers invocation rules, concurrency, skip behavior, versioning, permissions, and sibling routing. It does not describe success response shapes or error payloads, which leaves a minor gap because there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already defines each parameter. The description still adds action-specific semantics and cross-parameter constraints, such as expectedVersion avoiding overwrites after concurrent changes, copy not passing values through the agent, and import/copy skip/overwrite behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Create or change secrets') and immediately explains the action set. It explicitly distinguishes deletion by naming delete_item, so an agent can separate this tool from delete_secret/delete_item without inspecting another schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use routing: deletion is delete_item, copy should be preceded by find_secret_keys action diff, and restore uses versions from find_secret_keys action history. It also states the conditions for each action and the authorization prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources