mcp-server: return 200 for bare GET health probes instead of 406 (#347)

Directory crawlers like Glama probe MCP endpoints with a plain GET
(no Accept: text/event-stream header). The MCP SDK rejects these
with 406, but crawlers interpret that as "server unhealthy".

Intercept non-MCP GETs in the request handler and return a friendly
JSON status. Real MCP clients always send the SSE Accept header
and are unaffected.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: kvz

.changeset/mcp-health-probe.md

@@ -0,0 +1,7 @@
+---
+'@transloadit/mcp-server': patch
+---
+
+Return friendly 200 JSON for bare GET health probes instead of 406
+
+Directory crawlers (Glama, uptime monitors) probe MCP endpoints with a plain GET without the required `Accept: text/event-stream` header. Previously this reached the MCP SDK transport which returned an opaque 406 "Not Acceptable". Now the HTTP handler intercepts these non-MCP GETs and returns a `{"name":"Transloadit MCP Server","status":"ok","docs":"..."}` response. Real MCP clients always include the SSE Accept header and are unaffected.

packages/mcp-server/src/http-request-handler.ts

@@ -51,6 +51,24 @@ export const createMcpRequestHandler = (
       return
     }
 
+    // Bare GETs without the SSE Accept header are not valid MCP requests (the
+    // Streamable HTTP spec requires Accept: text/event-stream for GET).  Return
+    // a friendly JSON status so directory health-probes (Glama, uptime monitors)
+    // see a 200 instead of the SDK's opaque 406.
+    const accept = req.headers.accept ?? ''
+    if (req.method === 'GET' && !accept.includes('text/event-stream')) {
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.end(
+        JSON.stringify({
+          name: 'Transloadit MCP Server',
+          status: 'ok',
+          docs: 'https://transloadit.com/docs/sdks/mcp-server/',
+        }),
+      )
+      return
+    }
+
     try {
       const parsedBody = (req as { body?: unknown }).body
       await transport.handleRequest(req, res, parsedBody)

packages/mcp-server/test/e2e/streamable-http-auth.test.ts

@@ -45,6 +45,42 @@ test('streamable http: allows authenticated client', async () => {
   }
 })
 
+test('streamable http: returns friendly JSON for bare GET health probes', async () => {
+  const server = await startHttpServer()
+
+  try {
+    // Bare GET without Accept: text/event-stream (like Glama, uptime monitors)
+    const response = await fetch(server.url, { method: 'GET' })
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toContain('application/json')
+
+    const body = await response.json()
+    expect(body).toMatchObject({
+      name: 'Transloadit MCP Server',
+      status: 'ok',
+    })
+    expect(body.docs).toContain('transloadit.com')
+  } finally {
+    await server.close()
+  }
+})
+
+test('streamable http: passes through GET with SSE Accept header', async () => {
+  const server = await startHttpServer()
+
+  try {
+    // GET with Accept: text/event-stream should reach the MCP transport
+    // (which will reject it for missing session-id, proving it passed through)
+    const response = await fetch(server.url, {
+      method: 'GET',
+      headers: { Accept: 'text/event-stream' },
+    })
+    expect(response.status).not.toBe(200)
+  } finally {
+    await server.close()
+  }
+})
+
 test('streamable http: rejects disallowed origins', async () => {
   const server = await startHttpServer({
     allowedOrigins: ['https://allowed.example'],