feat(mcp): HTTP header support and runtime deps for stdio MCPs (#16)

Two related features for remote/local MCP server support:

1. HTTP headers for MCP HTTP upstreams
   - Add `Headers map[string]string` to MCPUpstreamRow/Opts/UpstreamConfig
   - New DB migration adds nullable `headers` JSON column to mcp_upstreams
   - HTTPUpstream applies configured headers on every request (Send + Stop)
   - CLI: `sluice mcp add --header "KEY=VAL"` (repeatable via flag.Func)
   - Reject --header on non-HTTP transports to fail loud on misuse

2. Vault template substitution in env/header values
   - New `{vault:<name>}` substring template form, alongside the existing
     whole-value `vault:<name>` prefix form
   - Shared via resolveVaultMap helper for both env and header values
   - Enables e.g. `--header "Authorization=Bearer {vault:github_pat}"`
   - Binding templates keep their `{value}` syntax (binding has an
     implicit single credential); doc comment explains the difference

3. Runtime dependencies in Docker image
   - Install nodejs + npm (npx) and python3 to the alpine image
   - Download uv/uvx as static musl binaries from astral.sh (pipx on
     alpine installs to /root/.local/bin which the sluice user cannot
     access; direct binary install avoids that)
   - Enables stdio MCP servers distributed via npx or uvx to run inside
     the sluice container without a separate sidecar

Image size grows from ~30MB to ~220MB (nodejs+python+uv).

Tests cover: whole-value form, template form, multiple substitutions,
missing credential errors, for both env and headers.

Author: nnemirovsky

Dockerfile

@@ -7,7 +7,24 @@ COPY . .
 RUN go build -ldflags='-s -w -linkmode external -extldflags "-static"' -o /sluice ./cmd/sluice/
 
 FROM alpine:3.21
-RUN apk add --no-cache ca-certificates wget && \
+# Runtimes installed so sluice can spawn common stdio MCP servers:
+#   nodejs + npm -> npx for JavaScript/TypeScript MCPs
+#   python3 + uv -> uvx for Python MCPs
+# uv is downloaded as a static binary from astral.sh to avoid Python
+# packaging headaches on Alpine (musl + PEP 668).
+# ca-certificates/wget are for sluice itself.
+RUN apk add --no-cache ca-certificates wget nodejs npm python3 && \
+    ARCH=$(uname -m) && \
+    case "$ARCH" in \
+        x86_64)  UV_ARCH=x86_64-unknown-linux-musl ;; \
+        aarch64) UV_ARCH=aarch64-unknown-linux-musl ;; \
+        *) echo "unsupported arch for uv: $ARCH" && exit 1 ;; \
+    esac && \
+    wget -qO- "https://github.com/astral-sh/uv/releases/latest/download/uv-${UV_ARCH}.tar.gz" | \
+        tar xz -C /tmp && \
+    mv "/tmp/uv-${UV_ARCH}/uv" /usr/local/bin/uv && \
+    mv "/tmp/uv-${UV_ARCH}/uvx" /usr/local/bin/uvx && \
+    rm -rf "/tmp/uv-${UV_ARCH}" && \
     adduser -D -h /home/sluice sluice && \
     mkdir -p /home/sluice/ca /home/sluice/.sluice /home/sluice/data /home/sluice/mcp /var/log/sluice /etc/sluice && \
     chown sluice:sluice /home/sluice/ca /home/sluice/.sluice /home/sluice/data /home/sluice/mcp /var/log/sluice /etc/sluice

cmd/sluice/main.go

@@ -525,6 +525,7 @@ func main() {
 				Command:    r.Command,
 				Args:       r.Args,
 				Env:        r.Env,
+				Headers:    r.Headers,
 				TimeoutSec: r.TimeoutSec,
 				Transport:  r.Transport,
 			}

cmd/sluice/mcp.go

@@ -104,6 +104,7 @@ func handleMCPGateway(args []string) error {
 			Command:    r.Command,
 			Args:       r.Args,
 			Env:        r.Env,
+			Headers:    r.Headers,
 			TimeoutSec: r.TimeoutSec,
 			Transport:  r.Transport,
 		}
@@ -251,15 +252,24 @@ func handleMCPAdd(args []string) error {
 	dbPath := fs.String("db", "data/sluice.db", "path to SQLite database")
 	command := fs.String("command", "", "command to run (stdio) or URL (http/websocket)")
 	argsStr := fs.String("args", "", "comma-separated arguments for the command")
-	envStr := fs.String("env", "", "comma-separated KEY=VAL environment variables")
+	envStr := fs.String("env", "", "comma-separated KEY=VAL environment variables (VAL may be vault:<name> for the whole value, or contain {vault:<name>} substrings for templated substitution)")
 	timeout := fs.Int("timeout", 120, "upstream timeout in seconds")
 	transport := fs.String("transport", "stdio", "transport type: stdio, http, or websocket")
+	headers := make(map[string]string)
+	fs.Func("header", "HTTP header to send on every request to an http upstream (repeatable, format: KEY=VAL; VAL may be vault:<name> for the whole value, or contain {vault:<name>} substrings for templated substitution, e.g. \"Authorization=Bearer {vault:github_pat}\")", func(s string) error {
+		parts := strings.SplitN(s, "=", 2)
+		if len(parts) != 2 {
+			return fmt.Errorf("invalid header format %q (expected KEY=VAL)", s)
+		}
+		headers[parts[0]] = parts[1]
+		return nil
+	})
 	if err := fs.Parse(args); err != nil {
 		return err
 	}
 
 	if fs.NArg() == 0 || *command == "" {
-		return fmt.Errorf("usage: sluice mcp add <name> --command <cmd> [--transport stdio|http|websocket] [--args \"arg1,arg2\"] [--env \"KEY=VAL,...\"] [--timeout 120]")
+		return fmt.Errorf("usage: sluice mcp add <name> --command <cmd> [--transport stdio|http|websocket] [--args \"arg1,arg2\"] [--env \"KEY=VAL,...\"] [--header \"KEY=VAL\" ...] [--timeout 120]")
 	}
 	name := fs.Arg(0)
 
@@ -271,6 +281,10 @@ func handleMCPAdd(args []string) error {
 		return fmt.Errorf("invalid transport %q: must be stdio, http, or websocket", *transport)
 	}
 
+	if len(headers) > 0 && *transport != "http" {
+		return fmt.Errorf("--header is only valid for --transport http")
+	}
+
 	var cmdArgs []string
 	if *argsStr != "" {
 		cmdArgs = strings.Split(*argsStr, ",")
@@ -296,6 +310,7 @@ func handleMCPAdd(args []string) error {
 	id, err := db.AddMCPUpstream(name, *command, store.MCPUpstreamOpts{
 		Args:       cmdArgs,
 		Env:        env,
+		Headers:    headers,
 		TimeoutSec: *timeout,
 		Transport:  *transport,
 	})
@@ -363,11 +378,24 @@ func handleMCPList(args []string) error {
 			}
 			envStr = " env=" + strings.Join(pairs, ",")
 		}
+		headersStr := ""
+		if len(u.Headers) > 0 {
+			keys := make([]string, 0, len(u.Headers))
+			for k := range u.Headers {
+				keys = append(keys, k)
+			}
+			sort.Strings(keys)
+			pairs := make([]string, 0, len(u.Headers))
+			for _, k := range keys {
+				pairs = append(pairs, k+"="+u.Headers[k])
+			}
+			headersStr = " headers=" + strings.Join(pairs, ",")
+		}
 		timeoutStr := ""
 		if u.TimeoutSec != 120 {
 			timeoutStr = fmt.Sprintf(" timeout=%ds", u.TimeoutSec)
 		}
-		fmt.Printf("[%d] %s command=%s%s%s%s%s\n", u.ID, u.Name, u.Command, transportStr, argsStr, envStr, timeoutStr)
+		fmt.Printf("[%d] %s command=%s%s%s%s%s%s\n", u.ID, u.Name, u.Command, transportStr, argsStr, envStr, headersStr, timeoutStr)
 	}
 	return nil
 }

internal/mcp/gateway.go

@@ -86,15 +86,21 @@ func NewGateway(cfg GatewayConfig) (*Gateway, error) {
 		// Store the original config (with vault: prefixes intact) for restart.
 		gw.upstreamCfgs[ucfg.Name] = ucfg
 
-		// Resolve vault: prefixed env values before spawning.
+		// Resolve vault: prefixed env and header values before spawning.
 		spawnCfg := ucfg
 		if gw.credResolver != nil {
-			resolved, err := resolveVaultEnv(ucfg.Env, gw.credResolver)
+			resolvedEnv, err := resolveVaultEnv(ucfg.Env, gw.credResolver)
 			if err != nil {
 				gw.Stop()
 				return nil, fmt.Errorf("upstream %s: %w", ucfg.Name, err)
 			}
-			spawnCfg.Env = resolved
+			spawnCfg.Env = resolvedEnv
+			resolvedHeaders, err := resolveVaultHeaders(ucfg.Headers, gw.credResolver)
+			if err != nil {
+				gw.Stop()
+				return nil, fmt.Errorf("upstream %s: %w", ucfg.Name, err)
+			}
+			spawnCfg.Headers = resolvedHeaders
 		}
 
 		u, err := StartUpstreamForTransport(spawnCfg)
@@ -300,14 +306,19 @@ func (gw *Gateway) RestartUpstream(name string) error {
 	log.Printf("restarting upstream %s for credential rotation", name)
 	_ = u.Stop()
 
-	// Re-resolve vault: prefixed env values to pick up rotated credentials.
+	// Re-resolve vault: prefixed env and header values to pick up rotated credentials.
 	spawnCfg := cfg
 	if gw.credResolver != nil {
-		resolved, err := resolveVaultEnv(cfg.Env, gw.credResolver)
+		resolvedEnv, err := resolveVaultEnv(cfg.Env, gw.credResolver)
+		if err != nil {
+			return fmt.Errorf("upstream %s: %w", name, err)
+		}
+		spawnCfg.Env = resolvedEnv
+		resolvedHeaders, err := resolveVaultHeaders(cfg.Headers, gw.credResolver)
 		if err != nil {
 			return fmt.Errorf("upstream %s: %w", name, err)
 		}
-		spawnCfg.Env = resolved
+		spawnCfg.Headers = resolvedHeaders
 	}
 
 	newU, err := StartUpstreamForTransport(spawnCfg)

internal/mcp/transport_http.go

@@ -20,22 +20,26 @@ import (
 type HTTPUpstream struct {
 	name      string
 	url       string
+	headers   map[string]string
 	client    *http.Client
 	sessionID string
 	mu        sync.Mutex
 	nextID    atomic.Int64
 }
 
-// NewHTTPUpstream creates an HTTPUpstream for the given URL and timeout.
-func NewHTTPUpstream(name, url string, timeoutSec int) *HTTPUpstream {
+// NewHTTPUpstream creates an HTTPUpstream for the given URL, headers, and timeout.
+// Headers are sent on every outbound request (e.g. Authorization for remote
+// MCP servers requiring auth).
+func NewHTTPUpstream(name, url string, headers map[string]string, timeoutSec int) *HTTPUpstream {
 	timeout := defaultUpstreamTimeout
 	if timeoutSec > 0 {
 		timeout = time.Duration(timeoutSec) * time.Second
 	}
 	return &HTTPUpstream{
-		name:   name,
-		url:    url,
-		client: &http.Client{Timeout: timeout},
+		name:    name,
+		url:     url,
+		headers: headers,
+		client:  &http.Client{Timeout: timeout},
 	}
 }
 
@@ -52,6 +56,11 @@ func (h *HTTPUpstream) Send(req JSONRPCRequest) (*JSONRPCResponse, error) {
 	if err != nil {
 		return nil, fmt.Errorf("create request: %w", err)
 	}
+	// Apply configured headers first so Content-Type and Accept below
+	// override any user-supplied values for protocol correctness.
+	for k, v := range h.headers {
+		httpReq.Header.Set(k, v)
+	}
 	httpReq.Header.Set("Content-Type", "application/json")
 	httpReq.Header.Set("Accept", "application/json, text/event-stream")
 
@@ -273,6 +282,9 @@ func (h *HTTPUpstream) Stop() error {
 	if err != nil {
 		return fmt.Errorf("upstream %s: create DELETE request: %w", h.name, err)
 	}
+	for k, v := range h.headers {
+		req.Header.Set(k, v)
+	}
 	req.Header.Set("Mcp-Session-Id", sid)
 
 	resp, err := h.client.Do(req)

internal/mcp/transport_http_test.go

@@ -112,7 +112,7 @@ func TestHTTPUpstreamInitialize(t *testing.T) {
 	srv := mockHTTPMCPServer(t)
 	defer srv.Close()
 
-	h := NewHTTPUpstream("remote", srv.URL, 0)
+	h := NewHTTPUpstream("remote", srv.URL, nil, 0)
 
 	if err := h.Initialize(); err != nil {
 		t.Fatalf("Initialize: %v", err)
@@ -127,7 +127,7 @@ func TestHTTPUpstreamDiscoverTools(t *testing.T) {
 	srv := mockHTTPMCPServer(t)
 	defer srv.Close()
 
-	h := NewHTTPUpstream("remote", srv.URL, 0)
+	h := NewHTTPUpstream("remote", srv.URL, nil, 0)
 
 	if err := h.Initialize(); err != nil {
 		t.Fatalf("Initialize: %v", err)
@@ -157,7 +157,7 @@ func TestHTTPUpstreamCallTool(t *testing.T) {
 	srv := mockHTTPMCPServer(t)
 	defer srv.Close()
 
-	h := NewHTTPUpstream("remote", srv.URL, 0)
+	h := NewHTTPUpstream("remote", srv.URL, nil, 0)
 
 	if err := h.Initialize(); err != nil {
 		t.Fatalf("Initialize: %v", err)
@@ -186,7 +186,7 @@ func TestHTTPUpstreamSessionIDRequired(t *testing.T) {
 	defer srv.Close()
 
 	// Skip Initialize so no session ID is set.
-	h := NewHTTPUpstream("remote", srv.URL, 0)
+	h := NewHTTPUpstream("remote", srv.URL, nil, 0)
 
 	_, err := h.DiscoverTools()
 	if err == nil {
@@ -198,7 +198,7 @@ func TestHTTPUpstreamSessionIDPersists(t *testing.T) {
 	srv := mockHTTPMCPServer(t)
 	defer srv.Close()
 
-	h := NewHTTPUpstream("remote", srv.URL, 0)
+	h := NewHTTPUpstream("remote", srv.URL, nil, 0)
 
 	if err := h.Initialize(); err != nil {
 		t.Fatalf("Initialize: %v", err)
@@ -219,7 +219,7 @@ func TestHTTPUpstreamStop(t *testing.T) {
 	srv := mockHTTPMCPServer(t)
 	defer srv.Close()
 
-	h := NewHTTPUpstream("remote", srv.URL, 0)
+	h := NewHTTPUpstream("remote", srv.URL, nil, 0)
 
 	if err := h.Initialize(); err != nil {
 		t.Fatalf("Initialize: %v", err)
@@ -234,7 +234,7 @@ func TestHTTPUpstreamStopWithoutSession(t *testing.T) {
 	srv := mockHTTPMCPServer(t)
 	defer srv.Close()
 
-	h := NewHTTPUpstream("remote", srv.URL, 0)
+	h := NewHTTPUpstream("remote", srv.URL, nil, 0)
 
 	// Stop without Initialize should be a no-op.
 	if err := h.Stop(); err != nil {
@@ -246,15 +246,15 @@ func TestHTTPUpstreamCustomTimeout(t *testing.T) {
 	srv := mockHTTPMCPServer(t)
 	defer srv.Close()
 
-	h := NewHTTPUpstream("remote", srv.URL, 30)
+	h := NewHTTPUpstream("remote", srv.URL, nil, 30)
 
 	if h.client.Timeout != 30*time.Second {
 		t.Errorf("expected client timeout 30s, got %v", h.client.Timeout)
 	}
 }
 
 func TestHTTPUpstreamDefaultTimeout(t *testing.T) {
-	h := NewHTTPUpstream("remote", "http://localhost:9999", 0)
+	h := NewHTTPUpstream("remote", "http://localhost:9999", nil, 0)
 
 	if h.client.Timeout != defaultUpstreamTimeout {
 		t.Errorf("expected default timeout %v, got %v", defaultUpstreamTimeout, h.client.Timeout)
@@ -344,7 +344,7 @@ func TestHTTPUpstreamSSEResponse(t *testing.T) {
 	srv := mockSSEMCPServer(t)
 	defer srv.Close()
 
-	h := NewHTTPUpstream("sse-remote", srv.URL, 0)
+	h := NewHTTPUpstream("sse-remote", srv.URL, nil, 0)
 
 	if err := h.Initialize(); err != nil {
 		t.Fatalf("Initialize: %v", err)
@@ -382,7 +382,7 @@ func TestHTTPUpstreamSSESkipsNotifications(t *testing.T) {
 	srv := mockSSEMCPServer(t)
 	defer srv.Close()
 
-	h := NewHTTPUpstream("sse-remote", srv.URL, 0)
+	h := NewHTTPUpstream("sse-remote", srv.URL, nil, 0)
 	if err := h.Initialize(); err != nil {
 		t.Fatalf("Initialize: %v", err)
 	}
@@ -404,7 +404,7 @@ func TestHTTPUpstreamSSESkipsNotifications(t *testing.T) {
 }
 
 func TestHTTPUpstreamConnectionRefused(t *testing.T) {
-	h := NewHTTPUpstream("dead", "http://127.0.0.1:1", 5)
+	h := NewHTTPUpstream("dead", "http://127.0.0.1:1", nil, 5)
 
 	err := h.Initialize()
 	if err == nil {
@@ -418,7 +418,7 @@ func TestHTTPUpstreamServerError(t *testing.T) {
 	}))
 	defer srv.Close()
 
-	h := NewHTTPUpstream("error-srv", srv.URL, 0)
+	h := NewHTTPUpstream("error-srv", srv.URL, nil, 0)
 	err := h.Initialize()
 	if err == nil {
 		t.Fatal("expected error from 500 response")