@sirr/mcp — Sirr MCP Server

Gives AI assistants like Claude direct access to your Sirr secret vault. Push, read, and manage ephemeral secrets without leaving a conversation.

Demo

Session 1 — store the secret

❯ set the BITBUCKET_TOKEN to 123asdzxc

⏺ sirr-mcp - push_secret (MCP)(key: "BITBUCKET_TOKEN", value: "123asdzxc", max_reads: 1)
  ⎿  Stored secret 'BITBUCKET_TOKEN'. Burns after 1 read.

⏺ Stored. Burns after first read.

Session 2 — Claude retrieves and uses it (the vault burns it)

❯ deploy to staging using sirr:BITBUCKET_TOKEN

⏺ sirr-mcp - get_secret (MCP)(key: "BITBUCKET_TOKEN")
  ⎿  123asdzxc

⏺ Got it. Deploying to staging with the token. Done.

Session 3 — secret is already gone

❯ what is the BITBUCKET_TOKEN?

⏺ sirr-mcp - get_secret (MCP)(key: "BITBUCKET_TOKEN")
  ⎿  Secret 'BITBUCKET_TOKEN' not found, expired, or already burned.

⏺ The secret no longer exists on the server.

The secret existed just long enough to be used once. The vault enforces it server-side (max_reads=1). Claude is instructed by the tool description not to memorize or repeat the value. Even if a different agent, session, or attacker asks — there is nothing left to return.

Install

npm install -g @sirr/mcp

Or use npx without a global install — see the configuration block below.

Quick start

1. Start Sirr — run the Sirr server and note the SIRR_MASTER_KEY you set (or the one it printed on first launch).
2. Set your token — SIRR_TOKEN in your MCP config must equal that SIRR_MASTER_KEY value exactly.
3. Add to .mcp.json — paste the config block below, substituting your server URL and key.
4. Verify — run sirr-mcp --health to confirm the connection before starting your AI session.

Configuration

Add Sirr to your project's .mcp.json or ~/.claude/settings.json:

{
  "mcpServers": {
    "sirr": {
      "command": "sirr-mcp",
      "env": {
        "SIRR_SERVER": "http://localhost:39999",
        "SIRR_TOKEN": "your-sirr-master-key"
      }
    }
  }
}

Using npx without a global install:

{
  "mcpServers": {
    "sirr": {
      "command": "npx",
      "args": ["-y", "@sirr/mcp"],
      "env": {
        "SIRR_SERVER": "http://localhost:39999",
        "SIRR_TOKEN": "your-sirr-master-key"
      }
    }
  }
}

What is SIRR_TOKEN? It is the value of SIRR_MASTER_KEY that you set (or that was generated) when you started the Sirr server. These two values must match exactly — a mismatch is the most common cause of 401 errors. See sirr.dev/errors#401.

Environment variables

Variable	Default	Description
SIRR_SERVER	http://localhost:39999	Sirr server URL
SIRR_TOKEN	—	Bearer token — must equal SIRR_MASTER_KEY on the server

CLI flags

# Print the installed version and exit
sirr-mcp --version

# Check that the MCP server can reach Sirr and exit
SIRR_SERVER=http://localhost:39999 SIRR_TOKEN=mykey sirr-mcp --health

--health exits with code 0 on success and 1 on failure, making it safe to use in scripts and CI.

Available tools

Secrets

Tool	Description
get_secret(key)	Retrieve a secret value (increments read counter; burns if max_reads reached)
push_secret(key, value, ttl_seconds?, max_reads?)	Store a secret with optional expiry and read limit
list_secrets()	List all active secrets — metadata only, values never returned
delete_secret(key)	Burn a secret immediately, regardless of TTL or read count
prune_secrets()	Delete all expired secrets in one sweep
health_check()	Verify the Sirr server is reachable and healthy

Audit

Tool	Description
sirr_audit(since?, action?, limit?)	Query the audit log — secret creates, reads, deletes, and key events

Webhooks

Tool	Description
sirr_webhook_create(url, events?)	Register a webhook URL; returns ID and signing secret (shown once)
sirr_webhook_list()	List all registered webhooks (signing secrets redacted)
sirr_webhook_delete(id)	Remove a webhook by ID

API keys

Tool	Description
sirr_key_create(label, permissions, prefix?)	Create a scoped API key; raw key returned once — save it
sirr_key_list()	List all scoped API keys (key hashes never returned)
sirr_key_delete(id)	Delete an API key by ID

Inline secret references

You can reference secrets inline in any prompt:

"Use sirr:DATABASE_URL to run a migration"
"Deploy with sirr:DEPLOY_TOKEN"

The sirr:KEYNAME prefix tells Claude to fetch from the vault automatically.

Security notes

• Claude only sees secret values when you explicitly ask it to fetch via get_secret
• list_secrets returns metadata only — values are never included
• Set max_reads=1 on any secret shared for a single AI session
• The MCP server never logs secret values
• SIRR_TOKEN lives in your MCP config's env block — it is never passed as a tool argument or in prompts
• Use HTTPS (https://) when SIRR_SERVER points to a remote host — plain HTTP transmits secrets unencrypted

Troubleshooting

Symptom	Cause	Fix
Error: Sirr 401	SIRR_TOKEN doesn't match SIRR_MASTER_KEY	Verify both values match exactly — no extra spaces or newlines. sirr.dev/errors#401
Error: Sirr 402	Free-tier limit of 100 secrets reached	Delete unused secrets or add a SIRR_LICENSE_KEY. sirr.dev/errors#402
Error: Sirr 403	Scoped API key lacks the required permission	Re-create the key with the needed permissions. sirr.dev/errors#403
Secret '…' not found	Secret expired, was burned, or key was mistyped	Re-push the secret if you still need it. sirr.dev/errors#404
did not respond within 10s	Sirr server is unreachable	Check SIRR_SERVER URL and confirm Sirr is running (sirr-mcp --health).
[sirr-mcp] Warning: SIRR_TOKEN is not set	Token missing from MCP config	Add SIRR_TOKEN to the env block in .mcp.json.
MCP server not found by Claude	sirr-mcp not on PATH	Install globally (npm install -g @sirr/mcp) or use the npx config variant.