Skip to main content

🤖 Agents and the MCP

AI assistants and scripts need passwords and keys too. Instead of pasting a value into a chat or an .env file, connect the assistant to Sneakers-PAM's MCP server. It then asks the vault for what it needs, with its own token, under your rules, and everything it does is audited.

MCP stands for Model Context Protocol: the way AI assistants talk to tools. You don't need to know how it works to use it; this page is what to set up and what to type.

🔌 Connect an assistant​

Before you start​

  • Your administrator has turned the MCP server on. When it's on, Connect an agent fills its address in for you; when it isn't set, the page says your administrator has the address.
  • You can sign in to Sneakers-PAM with your second factor.

Steps​

In Sneakers-PAM, open your account menu, choose My tokens, and follow Connect an agent:

  1. Add this server to your MCP client. The page has the setup for Claude's CLI, Claude Desktop, VS Code, and a generic JSON shape for other clients, with the address filled in. For example, for Claude's CLI:

    claude mcp add --transport http sneakers https://sneakers.example.org/mcp

  2. Allow it in the browser. The first time the assistant connects it opens a consent page. Name the token and allow it. You're asked for your second factor only if you signed in longer ago than your step-up window.

  3. Use your secrets. Ask in plain words (below).

The token acts as you, with your current access: if you lose access to a folder, so does the token. Tokens don't expire on their own; My tokens lists them, and you can revoke one at any time, which stops that assistant at once without touching the others. A revoked token can then be deleted from the list.

💬 Things you can ask​

Find a secret​

"Find the database password for the billing service."

The assistant searches the secrets you can read, by name, folder or type, and sees names and metadata only, never values.

Look around​

"What secrets are in the staging folder?"

This lists names, not values. It's a safe way to explore.

Run something with a secret, without seeing it​

"Run the migration with the billing database password, but don't show me the password."

This is the safest way to use a secret with an assistant: it uses sneakers-run, and the value goes straight to the command.

Reveal a value​

"Reveal the API key for the weather service so I can test it."

The one that needs the most care. A reveal to an agent is audited and flagged as one made to an agent. For a secret you can read it just works. If the secret is set to need an approval, the assistant opens the approval page in your browser, and an owner or approver decides (never you), or, when nobody else can, you confirm the task once (Approvals).

Store and organise​

"Generate a new password for the build user and store it in the CI folder."

The assistant can create and generate secrets, rename, move and retype them, make folders, attach a secret to its target, check a stored credential against its target, and turn rotation and heartbeat on or off for a secret, all within your access. A secret that names you goes into your personal folder unless you ask for another.

"Make a new Ed25519 SSH key called deploy-bot in the staging folder."

An SSH key is made and stored on the Sneakers-PAM side, so the assistant gets only the public key and its fingerprint, never the private key. Ed25519, RSA 4096, RSA 2048 and ECDSA P-256 are offered.

"Create a folder called agents."

With no parent named, the assistant makes a top-level folder that belongs to you, unless a site admin restricted top-level folders to admins. It can't share the folder, and no token sees a new top-level folder until you share it in the web app (Top-level folders).

A field that only takes one of a fixed set of choices — a key's format, say, or a database engine — is listed in the assistant's own tool description, so it picks one of the type's actual options rather than guessing; anything else is refused, naming the field and the allowed values.

🏃 sneakers-run​

sneakers-run runs one command with one secret field handed to it, so the value never passes through the assistant or your shell history:

export SNEAKERS_URL=https://sneakers.example.org
sneakers-run -secret <id> -- ssh admin@router-01                     # value on stdin
sneakers-run -secret <id> -inject file -- tool --key {secret_file}   # value in a private temp file

It supplies the secret's password field unless -field names another.

  • The use is bound to that exact command, and the value is released once.
  • The command's output has the value masked, including its base64, hex and URL encodings.
  • A temp file is readable only by you and removed when the command exits. Your token is never passed to the command.
  • When the use needs an approval, the approval link opens in your browser (-no-open only prints it). Several commands with the same -run-id share one approval page.

📥 sneakers-put​

sneakers-put stores a value that's already in a file, so it never goes through an agent session:

sneakers-put -folder <folder id> -type <type id> -name "router-01 admin" \
  -field username=admin -field password=@./router-01.pw
sneakers-put -id <secret id> -field password=@./new.pw

A secret field only takes a value from a file (key=@path) or stdin (key=-), never from the command line. It prints the secret's id, name and what changed, never a value.

Both commands act as you, with your personal token, and need an https:// address in SNEAKERS_URL. Sign in once with sneakers-put login (or sneakers-run login), which gets the token in your browser and keeps it on your machine, so you never copy it by hand. SNEAKERS_TOKEN, when it's set, is used instead. For a new appliance that still has its own certificate, SNEAKERS_CA_FILE or -ca-file points the commands at it. Install them with Go:

go install github.com/Sneakers-PAM/sneakers-mcp/cmd/sneakers-put@v0.1.0-rc.7
go install github.com/Sneakers-PAM/sneakers-mcp/cmd/sneakers-run@v0.1.0-rc.7

Signing in from the command line has the full sign-in, including a box with no browser.

🛑 What an agent can't do​

  • 🚫 No break-glass. Agents, the MCP server and every API token are refused by the server.
  • 💻 No SSH sessions. Brokered SSH sessions are started by a person in the web app only; no MCP tool reaches the SSH broker.
  • 🔒 No super-sensitive fields (card numbers, PINs, private keys and the like) unless an admin allows API access to them.
  • 🙅 No approving. An agent can ask, never decide; approvals happen in the browser with a person's second factor.
  • 📌 No changing pinned SSH host keys. A person does that in the web app: a site admin for a shared target, or the owner of a personal target. No token can, not even an admin's.
  • 🤝 No sharing. No token can change a folder's sharing; a person does that in the web app.
Folders an agent can and can't make

An assistant with your personal token can make a top-level folder, unless a site admin turned on Restrict top-level folders to admins, and a subfolder of any folder it can write to. A service account can't make a top-level folder, because it has no user to own it.

💡 Good habits​

  • Prefer running a command with the secret over revealing it.
  • Keep each assistant's token in an environment variable or your MCP client's secure store, never in a committed file.
  • Give an assistant that runs on its own (a nightly job) a service account from your admin rather than your personal token (MCP and agent tokens).

For a whole set-up built around agents, see the agent vault use case.