{"record":{"id":"c2712e918d5b6183","repo":"paperclipai/paperclip","slug":"mcp-transport-unsupported","errorCode":"mcp_transport_unsupported","errorMessage":"Assigned MCP connection transport is unsupported","messagePattern":"Assigned MCP connection transport is unsupported","errorType":"http","errorClass":"ToolGatewayHttpError","httpStatus":501,"severity":"error","filePath":"server/src/services/tool-gateway.ts","lineNumber":5206,"sourceCode":"    );\n    return record.result;\n  }\n\n  async function callAssignedConnectionProtocol(input: {\n    session: ToolGatewaySession;\n    connection: typeof toolConnections.$inferSelect;\n    method: string;\n    params?: Record<string, unknown>;\n    callerHeaders?: Record<string, string | string[] | undefined>;\n  }): Promise<unknown> {\n    if (input.connection.transport === \"mcp_remote\") {\n      return callRemoteConnectionProtocol({\n        ...input,\n        params: input.params ?? {},\n      });\n    }\n    if (input.connection.transport !== \"local_stdio\") {\n      throw new ToolGatewayHttpError(\n        501,\n        \"Assigned MCP connection transport is unsupported\",\n        \"mcp_transport_unsupported\",\n      );\n    }\n    const template = await resolveLocalStdioRuntimeTemplate(input.connection);\n    const grant = await resolveConnectionGrant(input.session, input.connection);\n    const env = await localStdioEnvironment(\n      input.session,\n      input.connection,\n      template,\n      grant,\n    );\n    return runtimeSupervisor.useConnectionSlot(\n      {\n        companyId: input.session.companyId,\n        applicationId: input.connection.applicationId,\n        connectionId: input.connection.id,","sourceCodeStart":5188,"sourceCodeEnd":5224,"githubUrl":"https://github.com/paperclipai/paperclip/blob/3f1d897a7c018d76563a21c6e39c3c9b03933622/server/src/services/tool-gateway.ts#L5188-L5224","documentation":"This ToolGatewayHttpError (HTTP 501) is thrown by the tool-call dispatch when an assigned MCP connection has a transport that is neither 'remote' (handled by callRemoteConnectionProtocol) nor 'local_stdio'. Only those two transports are implemented, so anything else is rejected as unsupported. It signals an unimplemented/unknown transport value in the connection record, not a transient failure.","triggerScenarios":"A tool call is dispatched to a connection whose transport column holds a value other than 'remote' or 'local_stdio' — e.g. a hand-inserted or migrated connection row with transport 'http', 'sse', 'websocket', or an empty/legacy value — reaching the check at tool-gateway.ts:5206.","commonSituations":"Direct database edits or migrations introducing new transport kinds before gateway support landed; importing connection configs from another tool that uses different transport names; a partially rolled-out new transport feature where rows exist but the dispatch branch isn't implemented yet.","solutions":["Fix the connection record so transport is a supported value ('remote' or 'local_stdio'): UPDATE connections SET transport = 'remote' WHERE id = ... (matching how the connection actually connects).","Re-create the connection through the UI/install flow so the transport is set to a supported value by the application instead of hand-editing rows.","If the source system genuinely uses another transport (e.g. SSE), find or build a supported equivalent — remote protocol transport — rather than keeping the unsupported value.","Check for schema/validation drift: add a validator on connection creation so unsupported transport values are rejected at write time."],"exampleFix":"// before: unknown transport in the connection row\nUPDATE connections SET transport = 'sse' WHERE id = $1; -- gateway throws 501\n// after: use a supported transport\nUPDATE connections SET transport = 'remote' WHERE id = $1;","handlingStrategy":"type-guard","validationCode":"const SUPPORTED_TRANSPORTS = [\"remote\", \"local_stdio\"] as const;\nif (!SUPPORTED_TRANSPORTS.includes(connection.transport)) {\n  throw new Error(`Connection ${connection.id} has unsupported transport '${connection.transport}'.`);\n}","typeGuard":"type SupportedTransport = \"remote\" | \"local_stdio\";\nfunction isSupportedTransport(t: string): t is SupportedTransport {\n  return t === \"remote\" || t === \"local_stdio\";\n}","tryCatchPattern":"try {\n  await callAssignedMcpTool(session, connectionId, params);\n} catch (e) {\n  if (e instanceof ToolGatewayHttpError && e.code === \"mcp_transport_unsupported\") {\n    return { status: \"unsupported_transport\", remediation: \"Re-create the connection with transport 'remote' or 'local_stdio'.\" };\n  }\n  throw e;\n}","preventionTips":["Validate connection.transport against an enum (shared validator) on create/import so unsupported values never reach dispatch.","Never hand-edit connection rows; use the app's connection install flow to set transport.","When migrating connections from other tools, map foreign transport names (sse/http) to a supported transport first.","Add a DB constraint or check for the transport column values if schema changes are possible."],"tags":["mcp","transport","unsupported","tool-gateway","config"],"backgroundTag":"unsupported-operation","analyzedSha":"3f1d897a7c018d76563a21c6e39c3c9b03933622","analyzedAt":"2026-09-18T08:03:59.046Z","contentChangedAt":"2026-09-18T08:03:59.046Z","schemaVersion":2},"datasetVersion":"2026-09-22T06:17:15.046Z"}