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

createACP rejects an MCP server entry named "ai-sdk-harness-tools" because that key is reserved: the harness itself exposes HarnessAgent built-in tools to the agent under this MCP server name. A user-defined server with the same name would collide with the internal tool channel, so it is rejected at construction time.

Source

Thrown at packages/harness-acp/src/acp-harness.ts:136

export function createACP<TBuiltinTools extends ToolSet = {}>(
  settings: ACPHarnessSettings<TBuiltinTools>,
): 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.',
    );
  }
  const version = (settings as { readonly version?: string }).version ?? 'v1';
  switch (version) {
    case 'v1': {
      const clientApp = settings.clientApp ?? ACP_CLIENT_APP;
      return createACPV1({
        settings,
        builtinTools:
          settings.builtinTools ?? (ACP_BUILTIN_TOOLS as TBuiltinTools),
        port: settings.port,
        portEndpoint: settings.portEndpoint,
        startupTimeoutMs: settings.startupTimeoutMs,
        clientApp,
        lifecycleStateSchema: acpResumeStateSchema,
      });
    }

View on GitHub (pinned to 69428b1f8b)

Solutions

Rename your MCP server entry to a different key (e.g. 'my-tools').
Remove the entry if the tools it defines are already provided as HarnessAgent builtinTools.
Search your config-building code for hardcoded 'ai-sdk-harness-tools' and change it.

Example fix

// before
createACP({ mcpServers: { 'ai-sdk-harness-tools': { command: 'npx', args: ['my-mcp'] } } }); // throws
// after
createACP({ mcpServers: { 'my-tools': { command: 'npx', args: ['my-mcp'] } } });

Defensive patterns

Strategy: validation

Validate before calling

const RESERVED_MCP_SERVER_NAMES = ['ai-sdk-harness-tools'];
function validateMcpServerNames(mcpServers?: Record<string, unknown>): void {
  if (mcpServers == null) return;
  for (const name of Object.keys(mcpServers)) {
    if (RESERVED_MCP_SERVER_NAMES.includes(name)) {
      throw new Error(`MCP server name "${name}" is reserved.`);
    }
  }
}

Prevention

Prefix user MCP server keys with your app name (e.g. 'app-my-tools').
Keep a shared constant of reserved names in config-generation code.
Never copy internal harness tool-server names into user config.

When it happens

Trigger: Passing settings.mcpServers whose object contains the key 'ai-sdk-harness-tools', e.g. createACP({ mcpServers: { 'ai-sdk-harness-tools': { ... } } }) or any wrapper factory forwarding such mcpServers.

Common situations: Generating MCP server config programmatically and colliding with the reserved name; copying an internal example that uses the harness tool server; merging config maps where the reserved key was already present.

Related errors

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