Keeper Secrets Manager MCP server

keeper-mcp

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.

Upstream pin: v2.5.0 (MIT), built from source. See Bumping the upstream pin.

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 KSMCONFIGBASE64 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:

1. Listens on :8080 with POST /mcp and GET /health.
2. 401-gates every /mcp request 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.
3. Lazily spawns one ksm-mcp serve --batch child per credential (keyed by a hash), with the tenant's KSMCONFIGBASE64 set, and connects an MCP client to it over stdio.
4. 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.
5. Filters the child's surface through a read-only allowlist in both directions.
6. Evicts idle children after 15 minutes (IDLEEVICTMS).

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 --secret ; 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 KSMMCPBATCH_MODE=true, and this bridge does. What that actually changes:

Shortened. The full README is on GitHub.