Zephr MCP Server

Use Zephr as a native tool in any MCP-compatible agent runtime — Claude Desktop, Cursor, Windsurf, and others.

"Store this database password as a one-time secret with a 15-minute expiry and hint DB_PROD."

The agent calls zephr_create_secret, the secret is encrypted client-side, only ciphertext reaches the server, and a one-time link is returned. Zero-knowledge. One command to install.

Sprint 2: Webhook callbacks (callbackUrl + callbackSecret) for async pipeline coordination. Idempotency keys auto-generated on every create for safe retries.

Install

Requires Node.js 22 or later.

npx zephr-mcp

Configure

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zephr": {
      "command": "npx",
      "args": ["zephr-mcp"],
      "env": {
        "ZEPHR_API_KEY": "zeph_..."
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "zephr": {
      "command": "npx",
      "args": ["zephr-mcp"],
      "env": {
        "ZEPHR_API_KEY": "zeph_..."
      }
    }
  }
}

Windsurf

Add to your MCP configuration file:

{
  "mcpServers": {
    "zephr": {
      "command": "npx",
      "args": ["zephr-mcp"],
      "env": {
        "ZEPHR_API_KEY": "zeph_..."
      }
    }
  }
}

The API key is optional. Without one, anonymous limits apply (3/day, 1h expiry, 6KB). Create a key at zephr.io/account.

Environment Variables

| Variable | Description | |----------|-------------| | ZEPHR_API_KEY | API key for authenticated requests (higher limits, sub-hour expiry) |

Tools

zephr_create_secret

Encrypt a secret client-side and store only ciphertext on Zephr. Returns a one-time link.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | secret | string | Yes | Plaintext to encrypt (max 2,048 UTF-8 bytes) | | expiry | integer | | Minutes until expiration: 5, 15, 30, 60, 1440, 10080, 43200. Default: 60 | | hint | string | | Plaintext label for routing/audit (1-128 printable ASCII 0x20-0x7E, not encrypted) | | split | boolean | | Return URL and key separately. Default: false | | callbackUrl | string | | HTTPS webhook URL — receive a signed event on consumption. Requires authentication (API key) and callbackSecret. | | callbackSecret | string | | HMAC-SHA256 signing secret for the webhook. Required when callbackUrl is set. 1-256 chars. | | idempotencyKey | string | | Caller-provided idempotency key (1-64 alphanumeric + hyphens). If omitted, auto-generated per request. |

zephr_retrieve_secret

Retrieve and decrypt a one-time secret. The record is permanently destroyed on first access.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | link | string | | Full Zephr link with key in fragment. If provided, url and key are ignored. | | url | string | | Secret URL without key (split mode, requires key) | | key | string | | Encryption key (split mode, requires url) |

Returns newline-delimited text: the decrypted plaintext on the first line, followed by Hint: <label> and Purge at: <timestamp> when present.

Tier Limits

| Tier | Creates | Expiry options | Max secret | |------|---------|----------------|------------| | Anonymous | 3/day | 1h | 6 KB | | Free | 50/month | 1h, 24h, 7d, 30d | 20 KB | | Dev ($15/mo) | 2,000/month | 5m, 15m, 30m, 1h, 24h, 7d, 30d | 200 KB | | Pro ($39/mo) | 50,000/month | 5m, 15m, 30m, 1h, 24h, 7d, 30d | 1 MB |

Webhook payload

When a secret with callbackUrl is consumed, Zephr POSTs a signed JSON event:

{
  "event":       "secret.consumed",
  "event_id":    "550e8400-e29b-41d4-a716-446655440000",
  "secret_id":   "Ht7kR2mNqP3wXvYz8aB4cD",
  "occurred_at": "2026-03-22T14:32:00.000Z",
  "hint":        "STRIPE_KEY_PROD"
}

Verify the X-Zephr-Signature header — HMAC-SHA256 hex digest of the raw JSON body, signed with your callbackSecret. Use timing-safe comparison. See examples/webhook-receiver for runnable Node.js and Python receivers.

Fire-and-forget in v1 — no retries. 5-second timeout. Redirects blocked.

Idempotency

The MCP server auto-generates an Idempotency-Key on every zephr_create_secret call via the underlying JS SDK. If a request is replayed at the infrastructure level, the server returns the cached response without creating a duplicate secret. Cache TTL: 24 hours. Advanced callers can pass idempotencyKey for application-level retry safety.

Security

• Encryption happens in the MCP server process using the Web Crypto API — plaintext never reaches the Zephr server
• The encryption key travels in the URL fragment, which is never sent in HTTP requests
• The server stores only ciphertext and destroys records after one retrieval
• API keys are read from environment variables, not passed through tool arguments in production

Host logging notice: MCP tool responses contain the shareable link (create) and decrypted plaintext (retrieve). If your MCP host logs tool outputs, secrets will be written to the host's log storage. This is inherent to any secret-handling MCP tool — the agent needs the data to use it. Review your MCP host's logging configuration and retention policy before using Zephr with sensitive credentials.

License

MIT