{"record":{"id":"ba5800bf39474116","repo":"vercel/ai","slug":"acp-transport-mcp-servers-require-client-side-mcp","errorCode":null,"errorMessage":"ACP-transport MCP servers require client-side mcp/connect handling, which this harness does not provide.","messagePattern":"ACP-transport MCP servers require client-side mcp/connect handling, which this harness does not provide\\.","errorType":"exception","errorClass":"HarnessBridgeCapabilityUnsupportedError","httpStatus":null,"severity":"error","filePath":"packages/harness-acp/src/v1/bridge/index.ts","lineNumber":645,"sourceCode":"  return { initialHostToolCatalogRefreshRequired: tools.length > 0 };\n}\n\nfunction createExternalMcpServers({\n  mcpServers,\n  initialization,\n}: {\n  mcpServers: Record<string, unknown> | undefined;\n  initialization: acp.InitializeResponse;\n}): acp.McpServer[] {\n  if (mcpServers == null) return [];\n  return Object.entries(mcpServers).map(([name, value]) => {\n    if (!isRecord(value)) {\n      throw new Error(\n        `ACP MCP server ${JSON.stringify(name)} must be configured with an object value.`,\n      );\n    }\n    if (value.type === 'acp') {\n      throw new HarnessBridgeCapabilityUnsupportedError({\n        harnessId: bridgeType,\n        message:\n          'ACP-transport MCP servers require client-side mcp/connect handling, which this harness does not provide.',\n      });\n    }\n    const mcpCapabilities = initialization.agentCapabilities?.mcpCapabilities;\n    if (\n      (value.type === 'http' && mcpCapabilities?.http !== true) ||\n      (value.type === 'sse' && mcpCapabilities?.sse !== true)\n    ) {\n      throw new HarnessBridgeCapabilityUnsupportedError({\n        harnessId: bridgeType,\n        message: `The ACP agent does not advertise support for ${value.type.toUpperCase()} MCP servers.`,\n      });\n    }\n    return { ...value, name } as acp.McpServer;\n  });\n}","sourceCodeStart":627,"sourceCodeEnd":663,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-acp/src/v1/bridge/index.ts#L627-L663","documentation":"createExternalMcpServers rejects mcpServers entries with type: 'acp' by throwing HarnessBridgeCapabilityUnsupportedError, because ACP-transport MCP servers require the client to handle mcp/connect requests, which this harness bridge does not implement. Only transport types the harness can hand to the agent directly (e.g. stdio/http) are supported.","triggerScenarios":"Configuring mcpServers with an entry whose value includes type: 'acp' — e.g. { myServer: { type: 'acp', ... } } — when creating the ACP bridge session.","commonSituations":"Reusing an MCP config authored for a different harness/agent that supports ACP-transport servers; following docs for another bridge implementation; assuming all @ai-sdk harness bridges provide client-side mcp/connect handling.","solutions":["Change the server's transport to one the harness supports, e.g. { type: 'stdio', command, args } or { type: 'http', url }.","Run that MCP server as a standalone process (stdio) or expose it over HTTP instead of relying on client-side ACP connect.","Check the specific harness bridge's capability documentation for supported MCP transport types before configuring."],"exampleFix":"// before\nmcpServers: { notes: { type: 'acp', command: 'npx', args: ['-y', 'notes-mcp'] } }\n// after\nmcpServers: { notes: { type: 'stdio', command: 'npx', args: ['-y', 'notes-mcp'] } }","handlingStrategy":"validation","validationCode":"function assertSupportedTransports(mcpServers: Record<string, Record<string, unknown>>): void {\n  for (const [name, cfg] of Object.entries(mcpServers)) {\n    if (cfg.type === 'acp') {\n      throw new Error(`MCP server '${name}' uses unsupported 'acp' transport; use stdio or http`);\n    }\n  }\n}","typeGuard":"function usesAcpTransport(cfg: Record<string, unknown>): boolean {\n  return cfg.type === 'acp';\n}","tryCatchPattern":"try {\n  await createBridge({ mcpServers });\n} catch (error) {\n  if (HarnessBridgeCapabilityUnsupportedError.isInstance(error)) {\n    // reconfigure the server with stdio/http transport\n  }\n  throw error;\n}","preventionTips":["Never configure type: 'acp' MCP servers with harness bridges lacking client-side mcp/connect handling.","Prefer stdio or http transports for MCP servers in this harness.","Check the bridge's supported MCP capabilities in docs before porting configs from other tools."],"tags":["acp","mcp","unsupported-capability","configuration"],"backgroundTag":"unsupported-mcp-transport","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}