shh. from an agent

Two MCP tools. The encryption happens on your machine, so an agent using shh gets the same guarantee a browser does.

Tool	What it does
shh_create	Encrypts a secret locally, stores the ciphertext, returns a link that works exactly once
shh_reveal	Opens a link from this deployment and destroys it

It is a local binary rather than an endpoint on this server for one reason: if the server did the encrypting, the server could read every secret an agent created, and shh's claim would hold for browser users while quietly not holding for you. shh-mcp is a peer of the browser — it mints the AES-256 key, encrypts, posts only ciphertext, and assembles the #fragment link itself.

1. Install it from a checkout

The shh repository is private, so there is no go install …@latest: ask its owner for access, then from the checkout's root:

make mcp-install

That builds ~/.local/bin/shh-mcp, proves the MCP handshake before wiring anything, and sets mcpServers.shh in omp's ~/.omp/agent/mcp.json — backing the file up and leaving every other server alone. For any other client, build only the binary:

go build -o ~/.local/bin/shh-mcp ./cmd/shh-mcp

Needs Go 1.27 or newer. Most clients do not expand ~, so use the absolute path (echo ~/.local/bin/shh-mcp) everywhere below.

2. Register it with your client

Every client here launches the same binary over stdio. The JSON shape is the portable part; only VS Code spells the wrapper key differently.

Claude Code

claude mcp add shh -e SHH_BASE_URL=https://shh.jx12n.com \
  -- /Users/you/.local/bin/shh-mcp

The -- is load-bearing: everything after it is the command to launch. Add -s user to get the server in every project rather than this one. claude mcp list then prints shh: … ✔ Connected.

Codex CLI

codex mcp add shh --env SHH_BASE_URL=https://shh.jx12n.com \
  -- /Users/you/.local/bin/shh-mcp

That writes ~/.codex/config.toml. The same thing by hand:

[mcp_servers.shh]
command = "/Users/you/.local/bin/shh-mcp"
env = { "SHH_BASE_URL" = "https://shh.jx12n.com" }

Gemini CLI

gemini mcp add shh /Users/you/.local/bin/shh-mcp \
  -e SHH_BASE_URL=https://shh.jx12n.com -s user

VS Code

In .vscode/mcp.json, or the user-level mcp.json that MCP: Open User Configuration opens — its wrapper key is servers, not mcpServers:

{
  "servers": {
    "shh": {
      "type": "stdio",
      "command": "/Users/you/.local/bin/shh-mcp",
      "env": { "SHH_BASE_URL": "https://shh.jx12n.com" }
    }
  }
}

Claude Desktop, Cursor, omp, anything else

{
  "mcpServers": {
    "shh": {
      "type": "stdio",
      "command": "/Users/you/.local/bin/shh-mcp",
      "env": { "SHH_BASE_URL": "https://shh.jx12n.com" }
    }
  }
}

Client	File
Claude Desktop	macOS ~/Library/Application Support/Claude/claude_desktop_config.json — then quit the app completely and reopen it
Cursor	~/.cursor/mcp.json for every project, .cursor/mcp.json for one
omp	~/.omp/agent/mcp.json (what make mcp-install writes)

3. Prove it before you trust it

A misconfigured stdio server reaches you as an opaque “server disconnected”. Run the handshake yourself instead, where the error is legible:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | /Users/you/.local/bin/shh-mcp

Two JSON lines come back: the first names the server shh, the second lists shh_create and shh_reveal.

4. Use it

Ask in words; the agent picks the tool.

• “Put this in a shh link so I can send it: <the credential>”
• “Open this shh link: https://shh.jx12n.com/s/…#…”

Behaviours worth knowing before an agent calls either tool:

• shh_reveal destroys the link. After it returns, the intended recipient cannot open it. An agent that reveals a link “just to check” has burned it.
• The link is shown once. shh cannot rebuild it, because the key it carries was never sent to the server.
• The #fragment is the key. Chat clients and mail rewriters truncate fragments, and a link without one carries no key. The tool says exactly that, without touching the secret.
• Only this deployment's links. shh_reveal refuses a link whose origin is not SHH_BASE_URL without sending anything, so a link cannot steer the agent into posting to another host.

Configuration

Variable	Meaning
SHH_BASE_URL	The deployment both tools talk to. Defaults to https://shh.jx12n.com
SHH_CREATE_TOKEN	Only for a deployment that has closed anonymous create. Sent on create, never on reveal. Unset is the normal case

When a client will not connect

• Use the absolute path: most clients do not expand ~.
• Restart the client. Claude Desktop needs a full quit, not a window close.
• Check the wrapper key — servers in VS Code, mcpServers everywhere else.
• A gone error is not a connection fault: that link was already opened, expired, or never existed. If you did not open it, assume someone else did and rotate the secret.