vercel/ai · error · MCPClientError

Failed to create MCP headers for tool "${request.params.name

Error message

Failed to create MCP headers for tool "${request.params.name}"

What it means

MCPClientError thrown by getToolRequestHeaders when createMCPToolHeaders fails while building per-tool HTTP headers from argument bindings. The original binding error is preserved as `cause`. This wraps header-binding failures (e.g. a template placeholder in the tool's header configuration that cannot be resolved from the provided arguments) into a single MCP error type.

Source

Thrown at packages/mcp/src/tool/mcp-client.ts:982

    }

    const bindings = this.toolHeaderBindings.get(request.params.name);
    if (bindings == null || bindings.length === 0) {
      return undefined;
    }

    const args = request.params.arguments;
    if (args == null || typeof args !== 'object' || Array.isArray(args)) {
      return undefined;
    }

    try {
      return createMCPToolHeaders({
        bindings,
        args: args as Record<string, unknown>,
      });
    } catch (error) {
      throw new MCPClientError({
        message: `Failed to create MCP headers for tool "${request.params.name}"`,
        cause: error,
      });
    }
  }

  private async callToolWithRetry({
    options,
    execute,
  }: {
    options?: RequestOptions;
    execute: () => Promise<CallToolResult>;
  }): Promise<CallToolResult> {
    if (this.maxRetries === 0) {
      return execute();
    }

    return retryWithExponentialBackoff({

View on GitHub (pinned to 69428b1f8b)

Solutions

Inspect error.cause to find which header binding failed and which argument it references
Pass all arguments referenced by the tool's header binding templates in the tool call
Fix the tool/server configuration so header templates reference existing argument names
Ensure required environment variables or secrets used in bindings are set before execution

Example fix

// before: header binding 'Bearer {apiKey}' but argument missing
await mcpTool.execute({ query: 'x' }, options);

// after
await mcpTool.execute({ query: 'x', apiKey: process.env.MCP_API_KEY }, options);

Defensive patterns

Strategy: validation

Validate before calling

const requiredArgs = Object.keys(toolHeaderBindings.match(/\{(\w+)\}/g) ?? []);
const missing = requiredArgs.filter(name => args?.[name] == null);
if (missing.length > 0) {
  throw new Error(`Header bindings require arguments: ${missing.join(', ')}`);
}

Try / catch

try {
  await mcpTool.execute(args, options);
} catch (error) {
  if (MCPClientError.isInstance(error) && error.message.startsWith('Failed to create MCP headers')) {
    console.error('Header binding failed:', error.cause); // find the offending binding
  } else {
    throw error;
  }
}

Prevention

Keep header binding templates in sync with argument names; rename both together
Validate that all interpolated values (secrets/env vars) are set before executing tools
Log error.cause — it contains the underlying binding failure

When it happens

Trigger: Executing an MCP tool that defines header bindings (e.g. Authorization: 'Bearer {api_key}') where a bound argument name is missing from the call arguments, is of the wrong type, or the binding template itself is malformed. Raised from the headers path of tool execution.

Common situations: Server config declares headers that interpolate from tool arguments but the client forgets to pass the required argument; renaming an argument without updating the header binding template; secrets/env values not set so the binding resolves to null/undefined.

Related errors

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