feat(mcp-server): protect metrics with basic auth

Author: kvz

packages/mcp-server/README.md

@@ -55,6 +55,8 @@ CLI:
 - Prometheus-compatible metrics are exposed at `GET /metrics` by default.
 - Customize the path via `TRANSLOADIT_MCP_METRICS_PATH` or config `metricsPath`.
 - Disable by setting `metricsPath: false` in the config or when creating the server/router.
+- Optional basic auth via `TRANSLOADIT_MCP_METRICS_USER` +
+  `TRANSLOADIT_MCP_METRICS_PASSWORD` or config `metricsAuth`.
 
 ## Input files
 

packages/mcp-server/src/cli.ts

@@ -19,6 +19,8 @@ Environment:
   TRANSLOADIT_MCP_TOKEN
   TRANSLOADIT_ENDPOINT
   TRANSLOADIT_MCP_METRICS_PATH
+  TRANSLOADIT_MCP_METRICS_USER
+  TRANSLOADIT_MCP_METRICS_PASSWORD
 `)
 }
 
@@ -109,6 +111,15 @@ const main = async (): Promise<void> => {
     const path = (fileConfig.path as string | undefined) ?? '/mcp'
     const metricsPath =
       (fileConfig.metricsPath as string | undefined) ?? process.env.TRANSLOADIT_MCP_METRICS_PATH
+    const metricsAuthConfig = fileConfig.metricsAuth as
+      | { username?: string; password?: string }
+      | undefined
+    const metricsUser = (fileConfig.metricsUser ??
+      metricsAuthConfig?.username ??
+      process.env.TRANSLOADIT_MCP_METRICS_USER) as string | undefined
+    const metricsPassword = (fileConfig.metricsPassword ??
+      metricsAuthConfig?.password ??
+      process.env.TRANSLOADIT_MCP_METRICS_PASSWORD) as string | undefined
     const endpoint = (config.endpoint ?? fileConfig.endpoint ?? process.env.TRANSLOADIT_ENDPOINT) as
       | string
       | undefined
@@ -130,6 +141,10 @@ const main = async (): Promise<void> => {
       enableDnsRebindingProtection: fileConfig.enableDnsRebindingProtection as boolean | undefined,
       path,
       metricsPath,
+      metricsAuth:
+        metricsUser && metricsPassword
+          ? { username: metricsUser, password: metricsPassword }
+          : undefined,
       logger,
     })
 

packages/mcp-server/src/express.ts

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
 import express from 'express'
 import type { TransloaditMcpHttpOptions } from './http.ts'
+import { isBasicAuthorized } from './http-helpers.ts'
 import { createMcpRequestHandler } from './http-request-handler.ts'
 import { getMetrics, getMetricsContentType } from './metrics.ts'
 import { createTransloaditMcpServer } from './server.ts'
@@ -27,6 +28,7 @@ export const createTransloaditMcpExpressRouter = async (
   const routePath = options.path ?? '/mcp'
   const metricsPath =
     options.metricsPath === false ? undefined : (options.metricsPath ?? '/metrics')
+  const metricsAuth = options.metricsAuth
   const handler = createMcpRequestHandler(transport, {
     allowedOrigins: options.allowedOrigins,
     mcpToken: options.mcpToken,
@@ -40,11 +42,19 @@ export const createTransloaditMcpExpressRouter = async (
   })
 
   if (metricsPath) {
-    router.get(metricsPath, async (_req, res) => {
+    router.get(metricsPath, async (req, res) => {
+      if (metricsAuth && !isBasicAuthorized(req, metricsAuth)) {
+        res.status(401).setHeader('WWW-Authenticate', 'Basic realm="metrics"').send('Unauthorized')
+        return
+      }
       res.setHeader('Content-Type', getMetricsContentType())
       res.status(200).send(await getMetrics())
     })
-    router.head(metricsPath, (_req, res) => {
+    router.head(metricsPath, (req, res) => {
+      if (metricsAuth && !isBasicAuthorized(req, metricsAuth)) {
+        res.status(401).setHeader('WWW-Authenticate', 'Basic realm="metrics"').end('Unauthorized')
+        return
+      }
       res.setHeader('Content-Type', getMetricsContentType())
       res.status(200).end()
     })

packages/mcp-server/src/http-helpers.ts

@@ -19,13 +19,49 @@ export const extractBearerToken = (header: string | undefined): string | undefin
   return token ? token : undefined
 }
 
+export const extractBasicAuth = (
+  header: string | undefined,
+): { username: string; password: string } | undefined => {
+  if (!header) return undefined
+  const match = header.trim().match(/^Basic\s+(.+)$/i)
+  const token = match?.[1]?.trim()
+  if (!token) return undefined
+  try {
+    const decoded = Buffer.from(token, 'base64').toString('utf8')
+    const separatorIndex = decoded.indexOf(':')
+    if (separatorIndex === -1) return undefined
+    const username = decoded.slice(0, separatorIndex)
+    const password = decoded.slice(separatorIndex + 1)
+    if (!username || !password) return undefined
+    return { username, password }
+  } catch {
+    return undefined
+  }
+}
+
+const timingSafeEqualString = (a: string, b: string): boolean => {
+  const bufferA = Buffer.from(a)
+  const bufferB = Buffer.from(b)
+  if (bufferA.length !== bufferB.length) return false
+  return timingSafeEqual(bufferA, bufferB)
+}
+
 export const isAuthorized = (req: IncomingMessage, token: string): boolean => {
   const provided = extractBearerToken(req.headers.authorization)
   if (!provided) return false
-  const a = Buffer.from(provided)
-  const b = Buffer.from(token)
-  if (a.length !== b.length) return false
-  return timingSafeEqual(a, b)
+  return timingSafeEqualString(provided, token)
+}
+
+export const isBasicAuthorized = (
+  req: IncomingMessage,
+  expected: { username: string; password: string },
+): boolean => {
+  const provided = extractBasicAuth(req.headers.authorization)
+  if (!provided) return false
+  return (
+    timingSafeEqualString(provided.username, expected.username) &&
+    timingSafeEqualString(provided.password, expected.password)
+  )
 }
 
 export const applyCorsHeaders = (

packages/mcp-server/src/http.ts

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
 import type { SevLogger } from '@transloadit/sev-logger'
-import { normalizePath, parsePathname } from './http-helpers.ts'
+import { isBasicAuthorized, normalizePath, parsePathname } from './http-helpers.ts'
 import { createMcpRequestHandler } from './http-request-handler.ts'
 import { getMetrics, getMetricsContentType } from './metrics.ts'
 import type { TransloaditMcpServerOptions } from './server.ts'
@@ -15,6 +15,7 @@ export type TransloaditMcpHttpOptions = TransloaditMcpServerOptions & {
   mcpToken?: string
   path?: string
   metricsPath?: string | false
+  metricsAuth?: { username: string; password: string }
   sessionIdGenerator?: (() => string) | undefined
   logger?: SevLogger
 }
@@ -44,6 +45,7 @@ export const createTransloaditMcpHttpHandler = async (
   const expectedPath = options.path ?? defaultPath
   const metricsPath =
     options.metricsPath === false ? undefined : normalizePath(options.metricsPath ?? '/metrics')
+  const metricsAuth = options.metricsAuth
 
   const mcpHandler = createMcpRequestHandler(transport, {
     allowedOrigins: options.allowedOrigins,
@@ -57,6 +59,12 @@ export const createTransloaditMcpHttpHandler = async (
     if (metricsPath) {
       const pathname = normalizePath(parsePathname(req.url, expectedPath))
       if (pathname === metricsPath) {
+        if (metricsAuth && !isBasicAuthorized(req, metricsAuth)) {
+          res.statusCode = 401
+          res.setHeader('WWW-Authenticate', 'Basic realm="metrics"')
+          res.end('Unauthorized')
+          return
+        }
         if (req.method !== 'GET' && req.method !== 'HEAD') {
           res.statusCode = 405
           res.end('Method Not Allowed')

packages/mcp-server/test/e2e/metrics.test.ts

@@ -20,4 +20,36 @@ describe('metrics', () => {
       await close()
     }
   })
+
+  it('requires basic auth when configured', async () => {
+    const { url, close } = await startHttpServer({
+      metricsAuth: { username: 'metrics-user', password: 'metrics-pass' },
+    })
+
+    try {
+      const metricsUrl = new URL(url)
+      metricsUrl.pathname = '/metrics'
+
+      const unauthorized = await fetch(metricsUrl)
+      expect(unauthorized.status).toBe(401)
+
+      const wrongAuth = await fetch(metricsUrl, {
+        headers: {
+          Authorization: `Basic ${Buffer.from('wrong:creds').toString('base64')}`,
+        },
+      })
+      expect(wrongAuth.status).toBe(401)
+
+      const ok = await fetch(metricsUrl, {
+        headers: {
+          Authorization: `Basic ${Buffer.from('metrics-user:metrics-pass').toString('base64')}`,
+        },
+      })
+      expect(ok.status).toBe(200)
+      const body = await ok.text()
+      expect(body).toContain('process_cpu_user_seconds_total')
+    } finally {
+      await close()
+    }
+  })
 })