npm package: @securecode/mcp-server
Description: SecureCodeHQ MCP Server - Let Claude Code access your secrets securely
Latest version: 0.15.3

# @securecode/mcp-server

MCP Server for [SecureCodeHQ](https://securecodehq.com). Lets Claude Code access your secrets securely — **without ever seeing them**.

## Get Started in 2 Minutes

The fastest way to set up SecureCodeHQ is from Claude Code itself. Just say:

```
You: "Set up SecureCode for this project"
```

The `onboard` tool walks you through everything — account creation, secret import, and MCP configuration — without leaving the terminal.

### What happens during onboarding

```
Step 1: "Create your account"  → Opens signup in your browser (one click)
Step 2: "Import your .env"     → Drag-and-drop in a secure web window (zero-knowledge)
Step 3: API key + MCP config   → Auto-created and configured by Claude
Step 4: Choose your secrets    → Select which project/env to use
Step 5: SDK setup (optional)   → Generates runtime code for your framework
```

After onboarding, a `.securecoderc` file is created in your project root with the API key and project/env config. The SDK and MCP server read it automatically.

### Already have an account?

If you already have an account and API key, add this to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "securecode": {
      "command": "npx",
      "args": ["@securecode/mcp-server"],
      "env": {
        "SECURECODE_API_KEY": "sc_your_key_here"
      }
    }
  }
}
```

Or add it globally in `~/.claude.json`. Then restart Claude Code.

## Zero-Knowledge AI Access

By default, secret values are **never shown to the AI**. When Claude reads a secret, the value is written to a local file on your machine. The AI gets the file path but never sees the actual value.

```
You: "Get my Stripe API key"
Claude: ✓ STRIPE_KEY injected → ~/.securecode/.session/a1b2c3d4.env

The value is NOT in this conversation.
```

This is **inject mode** — the default. If you explicitly need the AI to work with the value, use `reveal: true` (every reveal is audited).

## What Claude Can Do

Once connected, Claude Code can:

```
"Get my Stripe API key"              → injects to local file (AI never sees value)
"Get my DB_URL with reveal"          → reveals value to AI (audited)
"List my production secrets"         → shows names and tags, never values
"Save this API key as OPENAI_KEY"    → creates a new secret
"Import my .env.production file"     → opens secure web import (zero-knowledge)
"Lock my session"                    → blocks all access until you wake it
"Set up SecureCode"                  → guided onboarding (see above)
"Add staging environment"            → import secrets for another env
"Set up the SDK for this project"    → generates loadEnv/getSecret code
"byebye"                            → locks session + cleans secrets from disk
```

## Available Tools

| Tool | Description |
|------|-------------|
| `onboard` | Guided setup: signup, import, API key, MCP config, SDK setup — all from Claude Code |
| `get-secret` | Get a secret — inject to file by default, `reveal: true` to show to AI |
| `list-secrets` | List all secrets with tags, expiry status, and descriptions |
| `create-secret` | Create a new secret with tags, TTL, and domain |
| `update-secret` | Update value, description, tags, or domain |
| `delete-secret` | Soft-delete a secret |
| `renew-secret` | Renew expired secrets or change TTL |
| `import-env` | Import from .env — opens a secure web window (values never pass through AI) |
| `export-env` | Export secrets as .env or CSV format |
| `get-status` | Check plan, usage limits, secrets count, and MCP server version |
| `wake-session` | Unlock session with optional tag scope and auto-sleep timer |
| `sleep-session` | Lock session, block all access, clean injected files |
| `session-status` | Check session status, scope, and time remaining |
| `byebye` | End session: lock + clean all injected secrets from disk |
| `get-active-rules` | List active MCP access rules (read-only) |
| `help` | Get SecureCode docs: tools, SDK setup, sessions, rules, troubleshooting |

## SDK Setup from Claude Code

After onboarding, you can ask Claude to set up the SDK for your project:

```
You: "Set up the SecureCode SDK for this Next.js project"
```

The `onboard(action: "setup-sdk")` tool:
1. Lists your imported secrets grouped by project/env
2. Lets you choose between `loadEnv()` (bulk) or `getSecret()` (granular)
3. Generates the correct code for your framework (Next.js, Express, plain Node.js)
4. Handles framework-specific quirks (e.g., Next.js `instrumentation.ts` with `NEXT_RUNTIME` guard)

### Adding more environments

Already set up but need to add staging or production secrets? Just say:

```
You: "Add staging secrets to this project"
```

The `onboard(action: "add-environment")` tool opens the secure import window for a new environment without repeating the full onboarding.

## MCP Access Rules

Control how AI agents access your secrets with tag-based policies. Rules are created from the [dashboard](https://securecodehq.com) and enforced server-side.

| Action | Effect |
|--------|--------|
| **Block Always** | Secret is only accessible from the dashboard |
| **Require Confirmation** | Agent must acknowledge before accessing |
| **Require Session** | Requires an active session (wake-session) |
| **Block Models** | Only allows specific AI models |
| **Notify** | Sends email notification on access (non-blocking) |

```
You: "Read my STRIPE_LIVE_KEY"
Claude: [MCP Rule: "Block production secrets"]
        Access blocked. This secret is only accessible from the dashboard.
```

Rules are evaluated by priority: Block Always > Require Session > Block Models > Require Confirmation > Notify.

## Session Lock

Control access to your secrets per session:

```
You: "Wake my session for the acme project staging"
Claude: Session unlocked. Only acme/staging secrets accessible.

You: "Lock my session"
Claude: Session locked. All access blocked. Injected files cleaned.

You: "byebye"
Claude: Session locked & secrets cleaned from disk. See you next time!
```

Sessions auto-sleep after configurable inactivity (default: 2 hours).

## Security Tips (Tip Engine)

The MCP server includes an adaptive Tip Engine that shows security best practices:

- **First session**: Welcome message with best practices
- **Production access**: Warning when accessing production-tagged secrets
- **Stale secrets**: Reminder to rotate credentials older than 90 days
- **Generic names**: Suggestion to use descriptive secret names
- **No TTL**: Recommendation to set expiration on frequently-used secrets

Tips are throttled (max 3 per session, 1-week cooldown per secret) so they inform without annoying.

## Auto-Update Check

The MCP server checks for updates on first use. If your version is outdated, you'll see a warning:

```
⚠ Your SecureCode MCP server is outdated (v0.13.0 → v0.14.0).
To update, restart Claude Code — it will fetch the latest version automatically if you use npx.
```

## How It Works

- **Zero-knowledge by default**: Secret values are written to a local file — the AI never sees them
- **Reveal mode**: Explicit `reveal: true` returns value to AI (audited as conscious action)
- **Auto-cleanup**: Injected files are removed on sleep, byebye, process exit, or next inject
- **Parallel sessions**: Multiple Claude Code instances don't collide (file hash based on API key + PID)
- Secrets are encrypted with AES-256-GCM using envelope encryption (Cloud KMS)
- Every access is logged with AI model, IP, machine identity, access mode, and timestamp
- API keys are scoped to your account with `sc_` prefix
- The MCP server runs locally via stdio transport — secrets never pass through third parties
- Device approval required on first use from each machine
- MCP Access Rules enforce tag-based policies server-side before secret delivery

## Requirements

- Node.js >= 18
- A SecureCodeHQ account (create one during onboarding)

## License

MIT