sealnet-mcp

sealnet-mcp

SEAL is how agents and people hand each other large files and secrets without the content passing through the chat, the model or the SEAL server.

Model Context Protocol (MCP) server for SEAL.

Design principle: the model never holds capability by default

When an MCP-connected AI agent (Claude Desktop, Cursor, Cline, etc.) creates a SEAL via this server:

• inbox mode (default once connected): after seal_pair (or with SEAL_OWNER set to the address of the user's inbox) the file lands in the user's SEAL inbox on box.seal.net. Nothing is copied anywhere; the model gets a handle and a receipt. Every seal this server creates, in any mode, also appears there, where the user can manage and revoke it.
• handoff mode (default otherwise): the share link (the key is in its fragment, there is no password) is delivered to the human user via system clipboard (primary) or 0o600 local file (fallback when clipboard is unavailable — headless, SSH, WSL without display). The tool_result returned to the model contains only an opaque handle and a human-readable receipt. The link is never written into the conversation; on the file channel the receipt names the file, and an agent that can read files on that machine can read it.
• forward mode (explicit opt-in): model receives { handle, share_url, expires_at, max_reads, mode, delivered } in tool_result; the link opens only with the recipient's X25519 key and also lands in the recipient's inbox (seal_inbox). Requires short TTL (≤30m), max_reads=1, mandatory to (recipient address). Every forward is audit-logged in the encrypted state file.

Tool surface

Tool	Purpose
seal_share(path, mode='inbox'|'handoff'|'forward', expire?, max_reads?, tier?) / seal_share(payment)	Create a SEAL from a local file or folder (sent as one ZIP), streamed from disk. Default: inbox once connected, else handoff; without expire, 1d in the inbox, 5m for a handoff, or 1d for one over 100 MB. Over 1 GB the user pays once by card (smallest tier that fits, or tier): the payment page goes through URL-mode elicitation, or comes back as payment_url and a second call with payment finishes the upload into the same seal
seal_request(what, kind='any'|'secret'|'file', where_url?, wait=true, from?) / seal_request(request)	Ask the user for a file or a secret without it passing through the chat. On the user's computer the seal CLI draws the system dialog (seal request --local --json); otherwise the user answers at seal.net/i/<id>, sealed to this server's key, shown with three emoji of that key; once connected the request also waits in the user's inbox (from=owner, or from=anyone for a plain link). Returns the path of a 0600 file, never the value
seal_pair(name?, wait=true)	Connect this agent to the user's SEAL inbox, once: the user opens a page, compares three emoji and connects; the chat then shows the inbox's three emoji. After it seal_share sends to the inbox by default
seal_open(url|item, mode='metadata'|'file'|'inline', dir?)	Read metadata (default — no download, no counter consumption), save to disk (file: streamed, verified before it gets its name, 0600, returns paths) or inline parse (whitelisted MIMEs only, ≤100 KB, refuses secrets, HTML and binary). item is an inbox handle instead of a link
seal_inbox(wait?)	Seals other agents or people sent to this server's key (its address): handles, the sender's three emoji and name, never a link. seal_share mode=forward to=<address> puts a link there; wait (0 to 300 s) waits for something new
seal_run(command, secrets, cwd?, timeout?)	Run a program with secrets from links or inbox items in its environment, through the seal CLI (seal run --redact): every value is replaced with [sealed:NAME] in the output that comes back, and none enters this server. Needs seal on PATH (run_cli_missing otherwise). Not a sandbox: a program that prints a value transformed escapes the redaction
seal_list()	List SEALs created by this MCP server only (scope: state.json; never reveals user's CLI seals)
seal_revoke(handle)	Revoke by opaque handle (model never learns raw seal_id)

With SEAL Pro workload credentials (sealpro agent enroll, or SEALPRO_WORKLOAD_ID, SEALPRO_WORKLOAD_SEED and SEALPRO_BASE_URL) three tools appear: seal_pro_secret_use(secret, version?) saves a secret your organisation granted to this agent to a 0600 file and returns its path, never the value; seal_pro_secret_request(secret, reason, ttl_seconds?) asks a person for one, for a while, and waits for the decision; seal_pro_file_get(seal, file?, dir?) saves the files of a room whose key a person granted this agent, 0600 and digest-checked, and returns their paths.

Large transfers report notifications/progress when the host sends a progressToken. Where the host supports URL-mode elicitation, seal_request and seal_pair show the page link through it and wait in one call; otherwise they return the link and a second call waits.

The agent's key and state

The agent has one key: a 32-byte X25519 secret whose public half is its address (sealnet-mcp pubkey). It comes from, in order:

• SEAL_SEED — how a container or a cloud session gets the same address as at home (sealnet-mcp seed --force prints the key to put there);
• the OS keychain — @napi-rs/keyring (optional dependency): Secret Service on Linux, macOS Keychain, Windows Credential Manager;
• seed, a 0600 file in the state directory, where there is no keychain.

The first start makes the key (keychain, else the file); there is no setup step. State lives in ${XDG_CONFIG_HOME}/seal-mcp/state.json (mode 0o600), encrypted with a passphrase derived from the key (HKDF-SHA256 → Argon2id → AES-256-GCM). It holds:

• identity — the key itself, for incoming targeted seals
• owner — the user's inbox this agent is connected to (seal_pair): its address and name
• handles[] — opaque handle → { seal_id, owner_token, mode, created_at }. Each owner_token is full owner-capability for that seal; encrypting only identity and leaving tokens plain would be a security illusion.
• audit[] — historical tool invocations (timestamps, handles, modes). Side-channel relevant.

Several MCP hosts on one machine (Claude Desktop, Claude Code, Cursor) share the key and the state: each write re-reads the file under a lock. serve --ephemeral (or SEAL_MCP_EPHEMERAL=1) keeps nothing on disk and makes a new key each start; handles then last until restart, and seal expiry does not depend on it. A state from version 0.2 moves under the key on the first start, once.

Install + configure

No setup step: the first start creates the agent's key and state.

Add to ~/.cursor/mcp.json (or claude_desktop_config.json):

{
  "seal": {
    "command": "npx",
    "args": ["-y", "sealnet-mcp"]
  }
}

Production defaults are baked in (backend https://api.seal.net, share URLs on https://seal.net) — no env needed. Self-hosted deployments set both URL knobs; they are independent origins and are never derived from each other:

{
  "seal": {
    "command": "npx",
    "args": ["-y", "sealnet-mcp"],
    "env": {
      "SEAL_MCP_BACKEND_URL": "https://api.example.com",
      "SEAL_MCP_PUBLIC_HOST": "https://example.com"
    }
  }
}

Environment variables consumed by the CLI:

Variable	Used by	Purpose
SEAL_SEED	every subcommand	The agent's key (43 base64url characters); the same address wherever it is set
SEAL_OWNER	serve	The address of the user's inbox, instead of seal_pair: for a cloud session with nowhere to open the page
SEAL_MCP_EPHEMERAL=1	serve	As --ephemeral: a new key each start, nothing on disk
SEAL_MCP_CONFIG_DIR	every subcommand	Override default state directory (mirrors Rust seal-cli's SEAL_CONFIG_DIR)
SEAL_MCP_PASSPHRASE	serve	Read once, to move a state of version 0.2
SEAL_MCP_BACKEND_URL	serve, doctor	SEAL backend base URL (default https://api.seal.net)
SEAL_MCP_PUBLIC_HOST	serve, doctor	Public origin for minted share URLs (default https://seal.net)
SEAL_MCP_DEBUG=1	all	Include stack traces in fatal-error output (otherwise plain error: <msg>)

Available subcommands:

sealnet-mcp serve         # default — start the stdio MCP server (used by MCP hosts); --ephemeral keeps nothing on disk
sealnet-mcp init          # optional: make the key and state without starting the server
sealnet-mcp pubkey        # print the agent's address, its X25519 public key (for senders)
sealnet-mcp seed --force  # print the agent's key, to set SEAL_SEED elsewhere
sealnet-mcp doctor        # diagnose key source / keychain / file perms / backend reachability
sealnet-mcp reset --force # wipe state.json and the key: the address is lost for good

Development

pnpm install
pnpm build
pnpm test

Source of truth

• docs/security/seal_phase1_plan.md §"Phase 3 — MCP-оболочка"
• shared/contracts/seal_mcp.v1.json (tool input/output schemas)
• All cryptographic primitives are bundled into dist/ from internal workspace packages — no algorithm code is duplicated and no external @-scoped dependencies are pulled at install time.