Multitenant Streamable HTTP bridge over Keeper-Security/keeper-mcp-golang-docker — Keeper's official Secrets Manager MCP server — built so the WYRE conduit gateway can forward per-tenant Keeper credentials as HTTP headers.
v1 is READ-ONLY. See Read-only in v1 — for this vendor that is a security boundary, not a scoping decision.
Why
Keeper's server is stdio-only. There is no HTTP or SSE listener anywhere in its source — the EXPOSE 8080 in its own Dockerfile is vestigial, and its docker-entrypoint.sh is unreachable because the published image is FROM scratch with no shell. It reads its credential from KSM_CONFIG_BASE64 at process start, which makes it single-tenant per process.
Our gateway is multi-tenant: every request carries the calling org's credentials as HTTP headers, and the vendor container has to translate those headers into something the upstream understands.
Because the upstream has no HTTP mode to proxy to, this bridge holds an MCP client session over stdio to each tenant child and re-serves it over Streamable HTTP:
Listens on :8080 with POST /mcp and GET /health. Refuses to start unless CONDUIT_S2S_SECRET is a real secret.
401-gates every /mcp request on X-Gateway-S2S, then on X-Keeper-Config-Base64 — including validating that it decodes to a usable KSM config. Missing/invalid credentials never fall through to environment credentials; that would be a cross-tenant leak. This bridge is gateway mode only.
Lazily spawns one ksm-mcp serve --batch child per credential (keyed by a hash), with the tenant's KSM_CONFIG_BASE64 set, and connects an MCP client to it over stdio.
Serves both protocol eras on /mcp via the v2 SDK's createMcpHandler(factory, { legacy: 'stateless' }) — 2025-era initialize-handshake clients (the conduit gateway today) and modern 2026-07-28 envelope clients.
Filters the child's surface through a read-only allowlist in both directions.
Evicts idle children after 15 minutes (IDLE_EVICT_MS).
Tool names pass through unchanged.
Read-only in v1 — deliberate, and load-bearing
Boundary 1 (the strong one): a read-only KSM application
Provision the Keeper application with non-editable shares. A KSM application's
shared-folder grant is read-only unless explicitly made editable
(secrets-manager share add --app <APP> --secret <FOLDER_UID>; the Vault's Application
Access panel shows Read-Only vs Editable). With a non-editable grant, every write
fails at Keeper's own server — regardless of this bridge, its allowlist, batch mode, or
prompt injection.
This is a provisioning precondition of the credential contract, not a nice-to-have.
The bridge cannot verify it: the Keeper SDK carries IsEditable per record, but
ksm-mcp never reads it, so nothing here can detect an over-granted application. Scope
the application to the narrowest folder set the use case needs, read-only, and treat that
as the real control.
Boundary 2: this bridge's allowlist
Keeper's upstream has no read-only mode — verified against the v2.5.0 pin: serve has six
flags and none restrict the surface, getAvailableTools() returns a hardcoded 19-element
slice that consults no config, and Confirmation.DefaultDeny is hardcoded false with no
plumbing. Nothing upstream can un-register a tool.
On batch mode. Keeper's own Docker documentation tells you to set
KSM_MCP_BATCH_MODE=true, and this bridge does. What that actually changes:
Batch mode
Behaviour
off
get_field + unmask hard-errors (the single Confirmer call site upstream). The other eight confirm-requiring tools return a successful{status: "confirmation_required"} result pointing at the ksm_confirm_action prompt, expecting a two-phase completion.
on
Every confirmation is auto-approved, delete_secret included.
Leaving it off would not buy a confirmation boundary here, because that two-phase flow is
unreachable through this bridge by construction: it is driven by an MCP prompt, and the
bridge never declares the prompts capability — and the tool that completes it,
ksm_execute_confirmed_action, is blocked below. So "off" yields stubs no client here can
satisfy, not safety. We force it on and put the boundary in src/tools.ts instead.
What the allowlist uniquely buys, which a read-only grant does not: blocking
get_all_secrets_unmasked and ksm_execute_confirmed_action. Both are reads-or-worse
that a read-only grant happily permits.
Served (9)
Tool
Conduit tier
Note
list_secrets
read
Record metadata only
list_folders
read
Folder metadata
health_check
read
get_server_version
read
search_secrets
admin
Metadata-shaped result, but matches on notes and login/url/hostname/addressvalues — a confirmation oracle over secrets (CWE-200)
get_secret
admin
Returns a record; unmask honoured
get_field
admin
KSM notation query — the narrowest read
get_totp_code
admin
Live second factor
generate_password
admin
Local generation; record-creating args removed
Conduit classifies credential reads as admin (src/access/tool-classification.ts), which
outranks write. A Keeper read is a credential read by definition.
ksm_execute_confirmed_action — not a peer of the others but the keystone. It takes
original_tool_name plus a user_decision boolean the caller supplies, with no
nonce and no correlation to any prompt, then dispatches straight into the confirmed
executors. Allowing it would collapse every other rule here into one name. Blocked
permanently.
get_all_secrets_unmasked — one call that returns every secret in the application's
scope, unmasked, into the model's context. Blocked permanently.
get_record_type_schema — non-functional upstream at v2.5.0:
LoadRecordTemplates() has no callers and the package has no init(), so every call
returns "record templates not loaded".
download_file — cannot work over MCP. Upstream's DownloadFile(uid, fileUID, savePath) returns only an error and writes bytes to a server-side path; the handler
returns {uid, file_uid, path, message}, never the file. Honouring save_path would let
a tenant write attacker-chosen paths into a container filesystem shared with every other
tenant's child, and removing it leaves nowhere to write.
Argument policy: allowlist, not blocklist
Each served tool declares the exact arguments it accepts (allowArgs in src/tools.ts),
enforced on both the advertised inputSchema and the inbound tools/call. A client
working from a stale or ignored schema therefore cannot reach a write path by passing an
argument anyway.
The default matters more than the current entries: when an upstream bump adds a parameter
to an already-served tool, it fails closed — it vanishes from the surface until
someone reviews it into the table — rather than passing through silently. Today the only
removals are generate_password's save_to_secret and folder_uid, which would turn a
local utility into a record create.
Enabling writes is a reviewed, versioned change to src/tools.ts plus the matching
VENDOR_TOOL_CONFIG rows in conduit. Not a config flip, not an env var.
Credential contract
The gateway forwards this header on every /mcp request. conduit's vendor-config must match exactly.
Header
Child env var
Required
X-Keeper-Config-Base64
KSM_CONFIG_BASE64
yes
The value is the base64 device configuration from Keeper Vault → Secrets Manager → your application → Devices → Add Device (it starts ewog...).
Precondition: the application this device belongs to must hold read-only
(non-editable) shares. See Boundary 1
— it is the strongest control in the system and the bridge cannot verify it for you.
Validity rule: standard base64 that decodes to a flat JSON object of string values containing clientId, privateKey and appKey. hostname is optional — verified against upstream internal/ksm/client.goInitializeWithConfig, which requires exactly those three. Anything else → HTTP 401 with a JSON-RPC error body that never echoes the supplied value back.
The bridge also forces on every child:
KSM_MCP_BATCH_MODE=true # no TTY in a container (see above)
KSM_MCP_LOG_LEVEL=error
argv: ["serve", "--batch"]
KSM_MCP_PROFILE is deliberately not set: with KSM_CONFIG_BASE64 present, upstream builds an in-memory profile and never touches the on-disk profile store, which is what keeps tenants from sharing state through the filesystem.
Configuration
Env var
Default
Notes
CONDUIT_S2S_SECRET
empty (refuses to start)
Service-to-service secret. HTTP logs an error and exits non-zero when this is empty or a known placeholder (changeme, secret, replace-me, your-s2s-secret, and the other example values). Generate one with openssl rand -hex 32. Compose will not start without it. The value is never logged.
MCP_ALLOW_INSECURE_DEV
unset
Set to exactly 1 only for local development to start HTTP without CONDUIT_S2S_SECRET. The process logs a warning, does not enforce X-Gateway-S2S, and binds 127.0.0.1 only. A non-loopback MCP_HTTP_HOST is ignored and the override is logged. A known placeholder secret still refuses to start.
MCP_HTTP_HOST
0.0.0.0 when a real secret is set
Bind address. A configured secret honors this value, including 0.0.0.0. Unset keeps that historical container bind. The image and Compose set 0.0.0.0 inside the container. Without a secret, the dev bypass forces 127.0.0.1 and does not honor this variable.
PORT
8080
Public listen port. MCP_HTTP_PORT is the fallback when PORT is unset.
KSM_MCP_BIN
/usr/local/bin/ksm-mcp
Upstream binary the bridge spawns.
CHILD_HOME
/tmp/ksm-mcp-home
Root under which each tenant gets its ownHOME subdirectory, created at spawn.
IDLE_EVICT_MS
900000
Idle tenant timeout (15 min). Shorter than nutanix-mcp's 60 min on purpose: the Go child restarts in milliseconds, and every minute one stays open is a minute an authenticated KSM session sits in memory.
SPAWN_TIMEOUT_MS
30000
Max wait for a child to answer the MCP handshake.
Copy .env.example. Leave CONDUIT_S2S_SECRET empty in the example; put a real value only in an untracked .env or the process environment.
HTTP authentication
With CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The check is verifyS2sHeader in src/s2s-verify.ts: the header value is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of the literal string t=<unix seconds> keyed with CONDUIT_S2S_SECRET (64 lowercase hex characters). The timestamp must be within 300 seconds of the server clock. A missing or invalid header is HTTP 401, before the Keeper credential header is read.
Gateway mode is the only mode. /mcp also requires X-Keeper-Config-Base64. That header is the only credential source for the request. KSM_CONFIG_BASE64 in the process environment is not a fallback.
/health and /healthz stay unauthenticated and do not read credentials.
Docker
The image listens on 0.0.0.0 inside the container (MCP_HTTP_HOST). Publish the port on loopback and pass a real S2S secret. Keeper credentials arrive on each request as headers; they are not read from the environment.
Compose refuses to start when CONDUIT_S2S_SECRET is unset. The gateway service does not set KSM_CONFIG_BASE64 or env_file, and publishes 127.0.0.1:8080:8080:
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up
Local HTTP without a secret is development-only. It binds 127.0.0.1 and logs a warning. A non-loopback MCP_HTTP_HOST (including 0.0.0.0) is ignored:
MCP_ALLOW_INSECURE_DEV=1 npm start
Endpoints
POST /mcp — Streamable HTTP MCP, dual-era. Requires a valid X-Gateway-S2S header and X-Keeper-Config-Base64.
GET /health and GET /healthz — unauthenticated liveness. Reports mode, served tool count, and live tenant count. Never reads credentials and never spawns a child.
Development
npm install
npm run lint # tsc --noEmit
npm test # vitest
npm run build
HTTP refuses to start until CONDUIT_S2S_SECRET is set. For a local listener without a secret:
MCP_ALLOW_INSECURE_DEV=1 npm start
The test suite covers the allowlist policy, the credential contract, and the 401 gate over the real HTTP stack. None of it needs a Keeper account or a running child — the pool is pointed at a nonexistent binary so any accidental spawn fails loudly.
Bumping the upstream pin
Change KSM_MCP_REF in the Dockerfile.
Rebuild. scripts/check-upstream-tools.mjs runs in the Docker build, re-derives the tool surface from the pinned Go source, and fails the build on any drift — a new tool, a renamed one, or a new argument on an already-served tool. This is enforcement, not a checklist item.
Triage whatever it reports into src/tools.ts and src/__tests__/fixtures.ts. New tools are default-denied by the allowlist, but they still need an explicit decision recorded.
Re-run the build; both build-time smoke tests and the drift check must pass.
Cut a release, then re-pin the digest in conduit's azure/vendor-fleet.conduit-prod.bicepparam.
Never track main, and never pull keeper/keeper-mcp-server:latest — the pin is a reviewed git tag we build ourselves.
License
Apache-2.0 (this bridge). The upstream Keeper server is MIT and is built from source at image build time.