vercel/ai · error · HarnessBridgeCapabilityUnsupportedError

ACP-transport MCP servers require client-side mcp/connect ha

Error message

ACP-transport MCP servers require client-side mcp/connect handling, which this harness does not provide.

What it means

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.

Source

Thrown at packages/harness-acp/src/v1/bridge/index.ts:645

  return { initialHostToolCatalogRefreshRequired: tools.length > 0 };
}

function createExternalMcpServers({
  mcpServers,
  initialization,
}: {
  mcpServers: Record<string, unknown> | undefined;
  initialization: acp.InitializeResponse;
}): acp.McpServer[] {
  if (mcpServers == null) return [];
  return Object.entries(mcpServers).map(([name, value]) => {
    if (!isRecord(value)) {
      throw new Error(
        `ACP MCP server ${JSON.stringify(name)} must be configured with an object value.`,
      );
    }
    if (value.type === 'acp') {
      throw new HarnessBridgeCapabilityUnsupportedError({
        harnessId: bridgeType,
        message:
          'ACP-transport MCP servers require client-side mcp/connect handling, which this harness does not provide.',
      });
    }
    const mcpCapabilities = initialization.agentCapabilities?.mcpCapabilities;
    if (
      (value.type === 'http' && mcpCapabilities?.http !== true) ||
      (value.type === 'sse' && mcpCapabilities?.sse !== true)
    ) {
      throw new HarnessBridgeCapabilityUnsupportedError({
        harnessId: bridgeType,
        message: `The ACP agent does not advertise support for ${value.type.toUpperCase()} MCP servers.`,
      });
    }
    return { ...value, name } as acp.McpServer;
  });
}

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Change the server's transport to one the harness supports, e.g. { type: 'stdio', command, args } or { type: 'http', url }.
2. Run that MCP server as a standalone process (stdio) or expose it over HTTP instead of relying on client-side ACP connect.
3. Check the specific harness bridge's capability documentation for supported MCP transport types before configuring.

Example fix

// before
mcpServers: { notes: { type: 'acp', command: 'npx', args: ['-y', 'notes-mcp'] } }
// after
mcpServers: { notes: { type: 'stdio', command: 'npx', args: ['-y', 'notes-mcp'] } }

function assertSupportedTransports(mcpServers: Record<string, Record<string, unknown>>): void {
  for (const [name, cfg] of Object.entries(mcpServers)) {
    if (cfg.type === 'acp') {
      throw new Error(`MCP server '${name}' uses unsupported 'acp' transport; use stdio or http`);
    }
  }
}

function usesAcpTransport(cfg: Record<string, unknown>): boolean {
  return cfg.type === 'acp';
}

try {
  await createBridge({ mcpServers });
} catch (error) {
  if (HarnessBridgeCapabilityUnsupportedError.isInstance(error)) {
    // reconfigure the server with stdio/http transport
  }
  throw error;
}

When it happens

Trigger: Configuring mcpServers with an entry whose value includes type: 'acp' — e.g. { myServer: { type: 'acp', ... } } — when creating the ACP bridge session.

Common situations: 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.

Related errors

• ACP MCP server ${JSON.stringify(name)} must be configured wi
• Invalid argument for parameter model: model ${model.provider
• ACP credentialEnv and credentialBrokering must be configured
• ACP MCP server name "ai-sdk-harness-tools" is reserved for H
• ACP credentialEnv and credentialBrokering must be configured

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/ba5800bf39474116. Report an issue: GitHub.