# envseal MCP Server

> AI-agent-friendly interface to the envseal secret vault.

The MCP server gives AI agents structured tools for secret management. Instead of agents trying to `cat .env` or guessing CLI commands, they get proper tools like `envseal_request_key` and `envseal_inject`.

**All operations still go through the GUI popup** — the MCP server is a thin wrapper around the CLI. The human always approves.

## Quick Setup

```bash
cargo build -p envseal-mcp --release
```

For agent-specific configuration, see the [setup docs](../docs/setup/).

## Available Tools

| Tool | Description |
|------|-------------|
| `envseal_request_key` | **Primary workflow** — Agent requests user to store a key via GUI popup. Secret never enters agent context. |
| `envseal_inject` | Inject secrets into a child process as env vars |
| `envseal_inject_file` | Inject from `.envseal` file (dotenv replacement) |
| `envseal_run` | Run a command using explicit `.envseal` mappings |
| `envseal_pipe` | Pipe a secret value to command stdin |
| `envseal_supervised` | Supervised execution flow with strict validation |
| `envseal_list` | List stored secret names (never values) |
| `envseal_store` | Programmatic store (prefers `request_key` for user-pasted secrets) |
| `envseal_import` | Migrate from `.env` file |
| `envseal_revoke` | Delete a secret from vault |
| `envseal_policy_show` | View binary access rules |
| `envseal_policy_revoke_binary` | Revoke binary access |
| `envseal_status` | Vault status and environment summary |
| `envseal_check` | Validate mappings against vault contents |
| `envseal_env` | Inspect resolved envseal mappings |
| `envseal_health` | Secret health/compliance diagnostics |
| `envseal_doctor` | System security diagnostics |
| `envseal_audit` | Read structured audit log entries |

## Example Workflows

### Storing a secret (zero-friction)

```
Agent: "I need your Cloudflare API token to deploy"

1. Agent calls envseal_request_key("cloudflare-api", "Cloudflare API Token")
2. GUI popup appears: "Paste your Cloudflare API Token: [________] [Store]"
3. User pastes token, clicks Store
4. Agent receives confirmation — never the value
```

### Using a secret

```
Agent: "Running tests with database credentials"

1. Agent calls envseal_list → sees "postgres-url" is stored
2. Agent calls envseal_inject:
   - mappings: [{ secret: "postgres-url", env_var: "DATABASE_URL" }]
   - command: ["npm", "run", "test"]
3. GUI popup: "Allow npm to access postgres-url? [Allow Once] [Always Allow] [Deny]"
4. Human clicks Allow Once
5. Tests run with DATABASE_URL set
6. Agent receives test output (never the secret)
```

## MCP Configuration Examples

### Cursor (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "envseal": {
      "command": "/path/to/envseal/target/release/envseal-mcp"
    }
  }
}
```

### VS Code / Antigravity (`.vscode/mcp.json`)
```json
{
  "mcpServers": {
    "envseal": {
      "command": "/path/to/envseal/target/release/envseal-mcp"
    }
  }
}
```

### Gemini CLI (`~/.gemini/settings.json`)
```json
{
  "mcpServers": {
    "envseal": {
      "command": "/home/user/.envseal-src/target/release/envseal-mcp"
    }
  }
}
```

### Claude Code
```bash
claude mcp add envseal /path/to/envseal/target/release/envseal-mcp
```

## Security Model

- **Agent NEVER receives secret values** — only names and status
- **Every access requires GUI approval** from a physically present human (or, if your vault is configured for it, approval via a **relay** to a paired device — same human gate, different channel)
- **The MCP server is a convenience layer**, not a bypass
- **All CLI security invariants** are preserved through the MCP layer
- **Relay mode** (optional): if you use a relay URL, the HTTPS request carries metadata (which binary, which secret name) visible to the relay; secret values are never in that request. See `docs/relay-protocol.md` in this repo and `core/src/relay.rs` for the exact JSON contract, including the required `device_id` field for server routing
