vercel/ai · error · Error

ACP MCP server name "ai-sdk-harness-tools" is reserved for H

Error message

ACP MCP server name "ai-sdk-harness-tools" is reserved for HarnessAgent tools.

What it means

createACPV1 rejects an MCP server registered under the key "ai-sdk-harness-tools" because that name is reserved for the harness's internal HarnessAgent tool server. Allowing it would shadow or collide with the built-in tools exposed over that channel, so the conflict is caught during harness construction.

Source

Thrown at packages/harness-acp/src/v1/acp-v1-harness.ts:153

    HarnessV1<TBuiltinTools>['lifecycleStateSchema']
  >;
}): HarnessV1<TBuiltinTools> {
  if (
    (settings.credentialEnv == null) !==
    (settings.credentialBrokering == null)
  ) {
    throw new Error(
      'ACP credentialEnv and credentialBrokering must be configured together.',
    );
  }
  if (
    settings.mcpServers != null &&
    Object.prototype.hasOwnProperty.call(
      settings.mcpServers,
      'ai-sdk-harness-tools',
    )
  ) {
    throw new Error(
      'ACP MCP server name "ai-sdk-harness-tools" is reserved for HarnessAgent tools.',
    );
  }
  if (!HARNESS_ID_REGEXP.test(settings.harnessId)) {
    throw new Error(
      `ACP harnessId must be a stable kebab-case identifier; received ${JSON.stringify(settings.harnessId)}.`,
    );
  }
  const implementation = createACPV1Implementation({ settings });
  validateACPV1Implementation(implementation);
  const bootstrap = createACPBootstrap({
    harnessId: settings.harnessId,
    implementation,
  });
  const permissionModeMapping = isCompletePermissionModeMapping({
    value: settings.permissionModeMapping,
  })
    ? settings.permissionModeMapping

View on GitHub (pinned to 69428b1f8b)

Solutions

Rename the MCP server key to something else.
Remove the entry if its tools duplicate built-in HarnessAgent tools already enabled via builtinTools.
Grep config sources for 'ai-sdk-harness-tools' and eliminate user-supplied occurrences.

Example fix

// before
createACP({ mcpServers: { 'ai-sdk-harness-tools': { url: 'http://localhost:3001' } } }); // throws
// after
createACP({ mcpServers: { 'app-tools': { url: 'http://localhost:3001' } } });

Defensive patterns

Strategy: validation

Validate before calling

function validateMcpServerNames(mcpServers?: Record<string, unknown>): void {
  if (mcpServers != null && 'ai-sdk-harness-tools' in mcpServers) {
    throw new Error('MCP server name "ai-sdk-harness-tools" is reserved.');
  }
}

Prevention

Use a distinct naming convention for user MCP servers.
Run this name check before calling createACP in config-heavy codepaths.
Expose built-in tools via builtinTools rather than a same-named MCP server.

When it happens

Trigger: Calling createACP/createACPV1 with settings.mcpServers containing the key 'ai-sdk-harness-tools'.

Common situations: Template or generated MCP configs that happen to use the reserved key; users reading internal docs that reference the harness tool server and assuming it is user-configurable.

Related errors

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