MCP Server

Give AI assistants direct access to your secrets vault. Sirr's MCP server lets tools like Claude push, read, and manage ephemeral secrets without leaving the conversation.

What is MCP

The Model Context Protocol (MCP) is an open standard that allows AI assistants to interact with external tools and data sources. Instead of copy-pasting secrets between your terminal and an AI chat, MCP lets the assistant call Sirr directly.

Sirr's MCP server exposes a suite of tools that map to the core Sirr operations. When an AI assistant reads a secret through MCP, the same rules apply — read counters increment, TTLs are enforced, and one-time secrets burn after a single read.

MCP does not bypass any security constraints. Every tool call goes through the same authenticated HTTP API with the same TTL and read-limit enforcement.

Installation

Install the MCP server globally via npm.

Install

npm install -g @sirr/mcp

After installation, the sirr-mcp binary is available on your PATH.

Configuration

Add Sirr to your MCP configuration file. Most AI tools look for .mcp.json in your project root or home directory.

.mcp.json

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

Environment variables

  • Name
    SIRR_SERVER
    Type
    string
    Description

    URL of the Sirr server. Defaults to http://localhost:39999.

  • Name
    SIRR_TOKEN
    Type
    string
    Description

    Bearer token for authentication. Must match the server's SIRR_MASTER_KEY exactly.

CLI flags

  • Name
    --version
    Description

    Print the installed sirr-mcp version and exit.

  • Name
    --health
    Description

    Check that the MCP server can reach Sirr and exit with code 0 on success or 1 on failure. Safe to use in scripts and CI.

Verify the MCP server

# Test that the MCP server can reach Sirr
SIRR_SERVER=http://localhost:39999 \
SIRR_TOKEN=your-token \
sirr-mcp --health

Print installed version

sirr-mcp --version
# sirr-mcp 0.1.0

Available tools

The MCP server exposes thirteen tools across four groups.

Secrets

push_secret

Push a secret to the vault.

  • Name
    key
    Type
    string
    Description

    The secret key name.

  • Name
    value
    Type
    string
    Description

    The secret value.

  • Name
    ttl_seconds
    Type
    number
    Description

    Time-to-live in seconds. Optional.

  • Name
    max_reads
    Type
    number
    Description

    Maximum read count before the secret is burned. Optional.

get_secret

Retrieve a secret value. Increments the read counter; burns the secret if max_reads is reached.

  • Name
    key
    Type
    string
    Description

    The secret key to retrieve. Accepts bare names, sirr:KEYNAME, or KEYNAME#id format.

delete_secret

Delete a secret immediately, regardless of TTL or read count.

  • Name
    key
    Type
    string
    Description

    The secret key to delete.

list_secrets

List all secret metadata. Returns keys, TTLs, and read counts. No values are returned.

No parameters.

prune_secrets

Delete all expired secrets from the vault.

No parameters.

health_check

Check that the Sirr server is reachable and healthy.

No parameters.

Audit

sirr_audit

Query the audit log. Returns recent events such as secret creates, reads, deletes, and API key operations. Useful for security monitoring and debugging access patterns.

  • Name
    since
    Type
    number
    Description

    Only return events after this Unix timestamp. Optional.

  • Name
    action
    Type
    string
    Description

    Filter by action type, e.g. secret.create, secret.read, key.create. Optional.

  • Name
    limit
    Type
    number
    Description

    Maximum number of events to return. Defaults to 50. Optional.

Webhooks

sirr_webhook_create

Register a webhook URL to receive Sirr event notifications. Returns the webhook ID and a signing secret — the secret is shown once, save it immediately.

  • Name
    url
    Type
    string
    Description

    Webhook endpoint URL (must start with http:// or https://).

  • Name
    events
    Type
    string[]
    Description

    Event types to subscribe to. Defaults to all events. Examples: secret.created, secret.burned. Optional.

sirr_webhook_list

List all registered webhooks. Signing secrets are redacted.

No parameters.

sirr_webhook_delete

Remove a webhook registration by its ID.

  • Name
    id
    Type
    string
    Description

    The webhook ID to delete.

API keys

sirr_key_create

Create a scoped API key with specific permissions. The raw key value is returned once — save it immediately. Permissions: read, write, delete, admin. An optional prefix scope limits access to secrets whose key starts with the given prefix.

  • Name
    label
    Type
    string
    Description

    Human-readable label for the key.

  • Name
    permissions
    Type
    string[]
    Description

    Permissions to grant: read, write, delete, admin.

  • Name
    prefix
    Type
    string
    Description

    Optional prefix scope — the key can only access secrets starting with this prefix.

sirr_key_list

List all scoped API keys. Key hashes are never returned.

No parameters.

sirr_key_delete

Delete a scoped API key by its ID.

  • Name
    id
    Type
    string
    Description

    The API key ID to delete.

Conversation examples

Here is what it looks like when Claude uses Sirr through MCP.

Burn after read — across sessions

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 (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 was burned the moment it was first read — by the vault (max_reads=1), not by convention. The get_secret tool description also instructs Claude not to memorize or repeat secret values. Two independent layers: server-side destruction and agent-level instruction.

Storing with a TTL

Conversation

User:  Store this API key in Sirr with a 2-hour TTL: sk-live-abc123

AI:    [Calls push_secret(key: "API_KEY", value: "sk-live-abc123", ttl_seconds: 7200)]

       Done. API_KEY is stored and will self-destruct in 2 hours.

Listing secrets before cleanup

Conversation

User:  What secrets do we have stored right now?

AI:    [Calls list_secrets()]

       2 active secrets:
       - DB_URL    — expires in 58 minutes — 0/1 reads
       - API_KEY   — expires in 1h 42m     — no read limit

       Would you like me to prune any expired ones?

User:  Yes.

AI:    [Calls prune_secrets()]

       Pruned 1 expired secret. 2 active secrets remain.

Claude never caches secret values between sessions. Each retrieval is a live call to the Sirr server with full TTL and read-limit enforcement.

Troubleshooting

Token mismatch (401)

SIRR_TOKEN in your .mcp.json must equal SIRR_MASTER_KEY on the Sirr server exactly. A single extra character or newline will cause every authenticated tool call to fail.

Diagnose: sirr-mcp --health will show a 401 error if the token is wrong. See sirr.dev/errors#401.

Free-tier limit (402)

If push_secret fails with a 402 error, your instance has reached 100 active secrets. Delete or let expire the secrets you no longer need, or set SIRR_LICENSE_KEY to unlock unlimited usage. See sirr.dev/errors#402.

Permission denied (403)

A scoped API key was used but lacks the permission for the operation — for example, a read-only key trying to push or delete. Re-create the key with the needed permissions. See sirr.dev/errors#403.

Server unreachable

If tool calls time out after 10 seconds:

  1. Run sirr-mcp --health to confirm connectivity outside of an AI session
  2. Check that SIRR_SERVER in .mcp.json matches the address Sirr is listening on
  3. If Sirr is on a remote host, verify network access and that the server is running

SIRR_TOKEN missing

On startup, if SIRR_TOKEN is absent, sirr-mcp logs a warning to stderr. Tool calls will all return 401 until the token is added to the env block in .mcp.json. See sirr.dev/errors#401.

Plain HTTP on a remote host

If SIRR_SERVER is a non-local http:// URL, sirr-mcp warns that secrets will be transmitted unencrypted. Switch to https:// or secure the connection at the network level.

Was this page helpful?