{"record":{"id":"5c291ae04ffda2a3","repo":"vercel/ai","slug":"unsupported-or-invalid-transport-configuration-if","errorCode":null,"errorMessage":"Unsupported or invalid transport configuration. If you are using a custom transport, make sure it implements the MCPTransport interface.","messagePattern":"Unsupported or invalid transport configuration\\. If you are using a custom transport, make sure it implements the MCPTransport interface\\.","errorType":"exception","errorClass":"MCPClientError","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/tool/mcp-transport.ts","lineNumber":190,"sourceCode":"   * Optional custom fetch implementation to use for HTTP requests.\n   * Useful for runtimes that need a request-local fetch.\n   * @default globalThis.fetch\n   */\n  fetch?: FetchFunction;\n};\n\nexport function createMcpTransport(config: MCPTransportConfig): MCPTransport {\n  switch (config.type) {\n    case 'sse':\n      return new SseMCPTransport(config);\n    case 'http':\n      return new HttpMCPTransport({\n        ...config,\n        initialProtocolVersion:\n          config.initialProtocolVersion ?? LATEST_PROTOCOL_VERSION,\n      });\n    default:\n      throw new MCPClientError({\n        message:\n          'Unsupported or invalid transport configuration. If you are using a custom transport, make sure it implements the MCPTransport interface.',\n      });\n  }\n}\n\nexport function isCustomMcpTransport(\n  transport: MCPTransportConfig | MCPTransport,\n): transport is MCPTransport {\n  return (\n    'start' in transport &&\n    typeof transport.start === 'function' &&\n    'send' in transport &&\n    typeof transport.send === 'function' &&\n    'close' in transport &&\n    typeof transport.close === 'function'\n  );\n}","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/mcp/src/tool/mcp-transport.ts#L172-L208","documentation":"createMcpTransport() is the factory that turns a user-supplied transport config into a concrete MCPTransport (stdio, SSE, or HTTP). When the config's type/discriminator is not one of the supported values (and the object is not already a valid MCPTransport instance), it throws MCPClientError. This guards against typos in the transport type and against passing an object that doesn't implement the MCPTransport interface.","triggerScenarios":"Passing `{ type: 'websocket' }` or any type other than 'stdio' | 'sse' | 'http' to the DefaultMCPClient constructor; passing a malformed config object that is neither a known config nor a class implementing MCPTransport; passing null/undefined or a plain object where an MCPTransport instance is expected; constructing a client with an object from a different/older library version whose config shape no longer matches.","commonSituations":"Typo like `type: 'streamable-http'` or `'streamableHttp'` when the SDK expects 'http'; copying config from older MCP SDK docs where the type names differ; passing a custom transport class instance that forgot to implement one of the MCPTransport methods so the duck-typing check fails; mixing `@modelcontextprotocol/sdk` transports with AI SDK MCP client expecting its own MCPTransport interface.","solutions":["Check the transport config `type` value: it must be exactly 'stdio', 'sse', or 'http' (case-sensitive).","If using a custom transport, make sure your class implements the full MCPTransport interface (start, send, close, and the onmessage/onerror/onclose callbacks setter) from packages/mcp/src/tool/mcp-transport.ts, and pass an instance of it directly.","Don't pass transports from `@modelcontextprotocol/sdk`; wrap them in an adapter implementing the AI SDK MCPTransport interface.","Log/inspect the config object right before constructing DefaultMCPClient to catch undefined/misspelled fields.","Update @ai-sdk/mcp if the config keys changed between versions and check the changelog for the current transport config union."],"exampleFix":"// before: typo'd type -> factory falls to default branch\nconst client = new DefaultMCPClient({ transport: { type: 'streamable-http', url: 'https://mcp.example.com' } });\n// after: use a supported type\nconst client = new DefaultMCPClient({ transport: { type: 'http', url: 'https://mcp.example.com' } });\n// custom transport: pass an MCPTransport instance\nconst client2 = new DefaultMCPClient({ transport: new MyMCPTransport() });","handlingStrategy":"validation","validationCode":"const SUPPORTED = new Set(['stdio', 'sse', 'http']);\nexport function assertValidTransportConfig(config: unknown): void {\n  if (config == null || typeof config !== 'object') {\n    throw new TypeError('transport config must be an object');\n  }\n  const cfg = config as { type?: unknown };\n  if ('type' in cfg && !SUPPORTED.has(String(cfg.type))) {\n    throw new TypeError(`Unsupported transport type: ${String(cfg.type)}. Use stdio, sse, or http.`);\n  }\n}\n// call before: new DefaultMCPClient({ transport: cfg })","typeGuard":"export function isMCPTransport(x: unknown): x is MCPTransport {\n  return (\n    typeof x === 'object' && x !== null &&\n    typeof (x as MCPTransport).start === 'function' &&\n    typeof (x as MCPTransport).send === 'function' &&\n    typeof (x as MCPTransport).close === 'function'\n  );\n}","tryCatchPattern":"try {\n  const client = new DefaultMCPClient({ transport: config });\n} catch (error) {\n  if (MCPClientError.isInstance(error) && error.message.startsWith('Unsupported or invalid transport configuration')) {\n    console.error('Bad MCP transport config:', JSON.stringify(config));\n  } else {\n    throw error;\n  }\n}","preventionTips":["Type the transport config with the SDK's union type so TS catches invalid `type` values at compile time.","Only use 'stdio' | 'sse' | 'http' as type strings — check current docs for exact names.","Wrap foreign transports (e.g. @modelcontextprotocol/sdk) in an adapter implementing the AI SDK MCPTransport interface.","Unit-test client construction with each config variant you ship."],"tags":["mcp","configuration","typescript","factory"],"backgroundTag":"invalid-transport-configuration","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}