feat(mcp-server): add /.well-known/mcp/server-card.json endpoint

Serves static MCP server card metadata (tools, capabilities, auth info)
without requiring authentication. This fixes Smithery's "No capabilities
found" issue caused by its tool introspection being blocked by the auth
wall.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: kvz

packages/mcp-server/src/express.ts

@@ -5,6 +5,7 @@ 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 { buildServerCard, serverCardPath } from './server-card.ts'
 import { createTransloaditMcpServer } from './server.ts'
 
 export type TransloaditMcpExpressOptions = TransloaditMcpHttpOptions & {
@@ -37,6 +38,15 @@ export const createTransloaditMcpExpressRouter = async (
     redactSecrets: [options.mcpToken, options.authKey, options.authSecret],
   })
 
+  const serverCardJson = JSON.stringify(buildServerCard(routePath))
+
+  router.get(serverCardPath, (_req, res) => {
+    res.setHeader('Access-Control-Allow-Origin', '*')
+    res.setHeader('Access-Control-Allow-Methods', 'GET,HEAD,OPTIONS')
+    res.setHeader('Content-Type', 'application/json')
+    res.status(200).send(serverCardJson)
+  })
+
   router.all(routePath, (req, res) => {
     void handler(req, res)
   })

packages/mcp-server/src/http.ts

@@ -5,6 +5,7 @@ import type { SevLogger } from '@transloadit/sev-logger'
 import { isBasicAuthorized, normalizePath, parsePathname } from './http-helpers.ts'
 import { createMcpRequestHandler } from './http-request-handler.ts'
 import { getMetrics, getMetricsContentType } from './metrics.ts'
+import { buildServerCard, serverCardPath } from './server-card.ts'
 import type { TransloaditMcpServerOptions } from './server.ts'
 import { createTransloaditMcpServer } from './server.ts'
 
@@ -55,31 +56,51 @@ export const createTransloaditMcpHttpHandler = async (
     redactSecrets: [options.mcpToken, options.authKey, options.authSecret],
   })
 
+  const serverCardJson = JSON.stringify(buildServerCard(expectedPath))
+
   const handler = (async (req, res) => {
-    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')
-          return
-        }
+    const pathname = normalizePath(parsePathname(req.url, expectedPath))
+
+    if (pathname === serverCardPath) {
+      res.setHeader('Access-Control-Allow-Origin', '*')
+      res.setHeader('Access-Control-Allow-Methods', 'GET,HEAD,OPTIONS')
+      if (req.method === 'OPTIONS') {
+        res.statusCode = 204
+        res.end()
+        return
+      }
+      if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.statusCode = 405
+        res.end('Method Not Allowed')
+        return
+      }
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.end(req.method === 'HEAD' ? undefined : serverCardJson)
+      return
+    }
+
+    if (metricsPath && 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')
+        return
+      }
 
-        res.statusCode = 200
-        res.setHeader('Content-Type', getMetricsContentType())
-        if (req.method === 'HEAD') {
-          res.end()
-          return
-        }
-        res.end(await getMetrics())
+      res.statusCode = 200
+      res.setHeader('Content-Type', getMetricsContentType())
+      if (req.method === 'HEAD') {
+        res.end()
         return
       }
+      res.end(await getMetrics())
+      return
     }
 
     await mcpHandler(req, res)

packages/mcp-server/src/server-card.ts

@@ -0,0 +1,89 @@
+import packageJson from '../package.json' with { type: 'json' }
+
+export const serverCardPath = '/.well-known/mcp/server-card.json'
+
+type ServerCardTool = {
+  name: string
+  description: string
+}
+
+type ServerCard = {
+  $schema: string
+  version: string
+  protocolVersion: string
+  serverInfo: { name: string; title: string; version: string }
+  description: string
+  documentationUrl: string
+  iconUrl: string
+  transport: { type: string; endpoint: string }
+  authentication: { required: boolean; schemes: Array<{ type: string; description: string }> }
+  capabilities: { tools: boolean }
+  tools: ServerCardTool[]
+}
+
+const tools: ServerCardTool[] = [
+  {
+    name: 'transloadit_lint_assembly_instructions',
+    description:
+      'Lint Assembly Instructions without creating an Assembly. Returns structured issues.',
+  },
+  {
+    name: 'transloadit_create_assembly',
+    description:
+      'Create or resume an Assembly, optionally uploading files and waiting for completion.',
+  },
+  {
+    name: 'transloadit_get_assembly_status',
+    description: 'Fetch the latest Assembly status by URL or ID.',
+  },
+  {
+    name: 'transloadit_wait_for_assembly',
+    description: 'Polls until the Assembly completes or timeout is reached.',
+  },
+  {
+    name: 'transloadit_list_robots',
+    description: 'Returns a filtered list of robots with short summaries.',
+  },
+  {
+    name: 'transloadit_get_robot_help',
+    description: 'Returns a robot summary and parameter details.',
+  },
+  {
+    name: 'transloadit_list_templates',
+    description:
+      'List Assembly Templates (owned and/or builtin). Tip: pass include_builtin: "exclusively-latest" to list builtins only.',
+  },
+]
+
+export const buildServerCard = (endpoint: string): ServerCard => ({
+  $schema: 'https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json',
+  version: '1.0',
+  protocolVersion: '2025-03-26',
+  serverInfo: {
+    name: 'transloadit-mcp',
+    title: 'Transloadit MCP Server',
+    version: packageJson.version,
+  },
+  description:
+    'Agent-native media processing: video encoding, image manipulation, document conversion, and more via 86+ Robots.',
+  documentationUrl: 'https://transloadit.com/docs/topics/ai-agents/',
+  iconUrl: 'https://transloadit.com/favicon.ico',
+  transport: {
+    type: 'streamable-http',
+    endpoint,
+  },
+  authentication: {
+    required: true,
+    schemes: [
+      {
+        type: 'bearer',
+        description:
+          'Transloadit API Bearer token. Self-hosted: set TRANSLOADIT_KEY and TRANSLOADIT_SECRET env vars (auto-mints tokens). Hosted: call the authenticate tool or pass a bearer token.',
+      },
+    ],
+  },
+  capabilities: {
+    tools: true,
+  },
+  tools,
+})