EnigmAgent MCP is a local encrypted vault server that lets MCP clients list secret metadata and, when explicitly enabled, resolve individual secrets with domain-bound origin checks.
Run as an MCP stdio server with npx enigmagent-mcp; use terminal prompts or ENIGMAGENT_USER/ENIGMAGENT_PASS for headless setup.
enigmagent_list returns secret names, bound domains, and creation timestamps only, never secret values.
enigmagent_resolve decrypts a secret only when raw resolution is explicitly enabled and the request origin matches the secret's domain binding.
Run in REST mode with --mode rest, bound to 127.0.0.1, requiring a 32–256 character Bearer token for /status, /list, and /resolve; /health is unauthenticated.
Vault data is encrypted at rest with Argon2id-derived AES-256-GCM keys; version-1 vaults remain readable, and writes use atomic replacement with backup recovery.
Includes tested MCP client configuration builders for Claude Desktop, Cursor, Continue, Cline, Open WebUI, AnythingLLM, LM Studio, Zed, Goose, and Windsurf.
enigmagent-mcp is a local encrypted vault server for MCP-capable clients. It
stores secret values with an Argon2id-derived AES-256-GCM key and keeps the
vault file encrypted at rest.
Version 2.0.0 makes the security boundary explicit:
MCP starts in metadata-only mode. Raw secret resolution is disabled unless the
operator passes --allow-raw-resolve or sets ENIGMAGENT_ALLOW_RAW_RESOLVE=1.
REST binds to 127.0.0.1 and requires a 32–256 character Bearer token.
REST requests have bounded headers, bodies, and timeouts; responses do not include arbitrary exception messages or permissive browser CORS.
Vault writes use a temporary file, flush, replacement, and a recovery backup.
Version 1 vaults remain readable. New vaults use format version 2 and the
versioned KDF context enigma/v2.
Raw resolution is deliberately an opt-in escape hatch. A caller-declared origin is not proof of the network destination, and a trusted MCP client can still pass returned plaintext to its model. Do not enable raw resolution for an untrusted client or a shared process.
npx enigmagent-mcp@2.0.0 --vault ./my.vault.jsonThe first run prompts for the existing vault credentials when attached to a
terminal. For a trusted headless process, set ENIGMAGENT_USER and
ENIGMAGENT_PASS in its private environment. The server does not print either
value.
Related MCP server: mcp-keyward
The stdio transport implements bounded JSON-RPC MCP initialization, ping,
tools/list, and tools/call. The default tool is:
enigmagent_list: names, domains, and creation timestamps only.
With explicit raw-resolution opt-in, it additionally exposes:
enigmagent_resolve: returns a value only when the requested origin matches
the entry's domain binding.
The origin is normalized and limited to HTTP(S) URLs without embedded user credentials. Notifications, malformed JSON, oversized frames, invalid tool arguments, and calls before initialization are handled without terminating the process.
set ENIGMAGENT_API_TOKEN=use-a-random-32-character-token-or-longer
npx enigmagent-mcp@2.0.0 --mode rest --port 3737 --vault ./my.vault.jsonGET /health is a minimal unauthenticated liveness check. GET /status and
GET /list require Authorization: Bearer <token>. POST /resolve also
requires the token, JSON content type, and the explicit raw-resolution flag.
The service rejects browser-origin requests and binds only to loopback.
integrations.js provides tested configuration builders for Claude Desktop,
Cursor, Continue, Cline, Open WebUI, AnythingLLM, LM Studio, Zed, Goose, and
Windsurf. They are maintained configuration examples using the standard MCP
stdio command; they are not upstream plugins, endorsements, or claims of
adoption by those projects.
npm ci
npm test
npm run check
npm run benchmark
npm pack --dry-runThe tests cover encrypted-at-rest behavior, domain matching, wrong credentials, version-1 migration reads, backup recovery, bounded MCP framing and session ordering, authenticated REST, and all ten configuration adapters. The benchmark uses synthetic data and reports create/add/resolve latency without printing a secret.
The historical 1.0.5 tree is preserved in versions/1.0.5/ with its source
archive and SHA-256 manifest. The 2.0.0 release is represented consistently in
package.json, server.json, and manifest.json; publication remains subject
to the repository's CI and release checks.
This project protects vault contents from ordinary plaintext-at-rest exposure
and from accidental return by the metadata listing tool. It does not protect
against a compromised operating system, a process with access to the unlocked
memory, malicious client code, side channels, swap/core dumps, or an operator
who explicitly enables raw resolution for an untrusted model. Review
SECURITY.md in the main EnigmAgent project for broader ecosystem guidance.
MIT licensed. See LICENSE.
List all secret names and their bound domains. Never returns actual secret values.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses a key behavioral trait: it never returns secret values, which informs the agent about safety and limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with two sentences, front-loaded with the core purpose, and no superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description covers the essential purpose and a critical behavioral constraint, though pagination or ordering details are absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline 4 is appropriate as per instructions; no additional param info needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists secret names and bound domains, and explicitly distinguishes from a value-returning tool by stating 'Never returns actual secret values.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus the sibling 'enigmagent_resolve', but the description's emphasis on listing metadata implies usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a secret placeholder from the EnigmAgent vault. Returns the decrypted value. Domain binding is enforced: the origin must match the secret's bound domain.
| Name | Required | Description | Default |
|---|---|---|---|
| placeholder | Yes | The secret name to resolve. Supports {{NAME}}, {{LOGIN:domain}}, {{DOC:filename}} syntax (pass without the braces). | |
| origin | Yes | The requesting origin URL (e.g. https://api.example.com). Must match the secret's domain binding. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description correctly notes returns decrypted value and domain enforcement, but lacks details on error conditions (e.g., mismatch) or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description mentions return value but omits error handling or detailed result format. Adequate for a simple tool but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds valuable context to both parameters: placeholder syntax variants and origin requirement, going beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Resolve' and the resource 'secret placeholder from the EnigmAgent vault', and distinguishes from sibling 'enigmagent_list' by specifying it returns the decrypted value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the domain binding and placeholder syntax, but does not explicitly state when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0enigmagent_listenigmagent_resolveScored across 2 tools
The two tools have completely distinct purposes: one lists secret names and domains, the other resolves placeholder values. There is no ambiguity between them.
Both tools share a consistent 'enigmagent_' prefix followed by a verb ('list', 'resolve'), following a predictable verb_noun pattern.
With only 2 tools, the set is on the low end of what is reasonable. While each tool is distinct, the total number feels minimal for a secret management server.
The tool surface lacks basic CRUD operations like create, update, or delete secrets. Agents can only list and resolve, which is insufficient for comprehensive secret management.
A secret store for AI agents: the agent never sees the plaintext.
Encrypted secret store and rotation for autonomous agent credentials
Secrets for developers and agents—secure context and workflows without exposing secret values.
Give your AI hands. Identity, credential vault, and API gateway for autonomous agents.
