# vaultshell MCP server

> Injects secrets into shell commands at execution time while ensuring plaintext never reaches the LLM context through mandatory redaction.

- Repository: https://github.com/SoWhatI/vaultshell
- Page: https://hostedmcp.org/servers/sowhati/vaultshell
- Transport: stdio
- Stars: 1
- License: MIT
- Latest version: 0.1.2

## Install

### Claude Code

```sh
claude mcp add vaultshell -- docker run -i --rm ghcr.io/sowhati/vaultshell:0.1.2
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "vaultshell": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/sowhati/vaultshell:0.1.2"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "vaultshell": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/sowhati/vaultshell:0.1.2"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"vaultshell","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/sowhati/vaultshell:0.1.2"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "vaultshell": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/sowhati/vaultshell:0.1.2"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add vaultshell -- docker run -i --rm ghcr.io/sowhati/vaultshell:0.1.2
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.vaultshell]
command = "docker"
args = ["run", "-i", "--rm", "ghcr.io/sowhati/vaultshell:0.1.2"]
```

### Gemini CLI

```sh
gemini mcp add -s user vaultshell docker -- run -i --rm ghcr.io/sowhati/vaultshell:0.1.2
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "vaultshell": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/sowhati/vaultshell:0.1.2"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `MASTER_KEY` | no | no |  |

## Tools (16)

- `shell_exec`: Execute a one-shot shell command with secrets injected per matching rule. Output is redacted: injected secret values never appear in the response. Dangerous commands (env, printenv, export -p, /proc/*/environ, ...) are hard-blocked. There is no free-form env parameter; secrets are only injected by reference via rules.
- `secret_list`: List registered secret names with metadata (backend ref, resolvable). Never returns values.
- `secret_set`: Store a secret value into the configured backend. The value is persisted, never echoed back, and the name is registered in rules.yaml (ref only).
- `secret_delete`: Delete a secret from the backend and unregister it from rules.yaml.
- `secret_probe`: Check whether a secret ref can be resolved. Returns only {ok, masked}; masked never contains value fragments unless defaults.maskTail > 0.
- `rule_list`: List injection rules with static warnings (e.g. rules matching every directory → potential unintended full injection).
- `audit_query`: Query recent audit entries (newest last). Entries contain names and redacted commands only, never values.
- `shell_session_open`: Open a persistent shell session (PTY when node-pty is available, plain child_process otherwise — the response's `pty` field says which). Secrets are injected once at creation per matching rule; idle sessions are killed after ttlSeconds (rule ttlSeconds overrides defaults.sessionTtlSeconds).
- `shell_session_send`: Send a command to a persistent session. Output (merged stdout/stderr) is redacted before returning. Dangerous commands are blocked per security.dangerousCommands. Returns {output, exitCode}.
- `shell_session_close`: Close a session: kill the process; injected secrets die with it.
- `shell_session_list`: List live sessions (metadata only: id, cwd, injected names, pty, ttl, timestamps).
- `shell_session_revoke`: Immediately kill a session and rebuild a fresh one WITHOUT any injected secrets. Use when a session may have been compromised. Returns the new sessionId.
- `rule_validate`: Statically validate rules.yaml and return findings: unknown secret refs, unreachable rules (shadowed by earlier ones), inject-everywhere rules (high severity), requireConfirm capability notes, union mergeStrategy risk notes.
- `shell_proxy_start`: Start a credential-injecting reverse proxy on 127.0.0.1 (random port) for a `proxies` entry in config.yaml. Point commands at http://127.0.0.1:<port> instead of the real API host; the proxy injects the secret into the configured header in memory only. Auto-stops after its TTL (default defaults.proxyTtlSeconds=300s). The secret value is never returned anywhere.
- `shell_proxy_stop`: Stop a running credential proxy.
- `shell_proxy_list`: List running credential proxies (metadata only: id, port, upstreamHost, secret NAME, expiry, request count). Never includes values.

## FAQ

### Does the LLM see my secret values?

No, the server guarantees that secret plaintext never reaches the model context, tool responses, logs, or audit records.

### How are secrets injected into commands?

Secrets are injected into shell child processes at exec time based on rules, and values go straight into the child process env without passing through the tool layer.

### What happens if the redactor fails to hide a secret?

The system is designed to fail-closed, meaning the output is discarded rather than being returned in its raw form.
