{"record":{"id":"057c84c6f99f5348","repo":"vercel/ai","slug":"failed-to-create-mcp-headers-for-tool-request-p","errorCode":null,"errorMessage":"Failed to create MCP headers for tool \"${request.params.name}\"","messagePattern":"Failed to create MCP headers for tool \"(.+?)\"","errorType":"exception","errorClass":"MCPClientError","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/tool/mcp-client.ts","lineNumber":982,"sourceCode":"    }\n\n    const bindings = this.toolHeaderBindings.get(request.params.name);\n    if (bindings == null || bindings.length === 0) {\n      return undefined;\n    }\n\n    const args = request.params.arguments;\n    if (args == null || typeof args !== 'object' || Array.isArray(args)) {\n      return undefined;\n    }\n\n    try {\n      return createMCPToolHeaders({\n        bindings,\n        args: args as Record<string, unknown>,\n      });\n    } catch (error) {\n      throw new MCPClientError({\n        message: `Failed to create MCP headers for tool \"${request.params.name}\"`,\n        cause: error,\n      });\n    }\n  }\n\n  private async callToolWithRetry({\n    options,\n    execute,\n  }: {\n    options?: RequestOptions;\n    execute: () => Promise<CallToolResult>;\n  }): Promise<CallToolResult> {\n    if (this.maxRetries === 0) {\n      return execute();\n    }\n\n    return retryWithExponentialBackoff({","sourceCodeStart":964,"sourceCodeEnd":1000,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/mcp/src/tool/mcp-client.ts#L964-L1000","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before: header binding 'Bearer {apiKey}' but argument missing\nawait mcpTool.execute({ query: 'x' }, options);\n\n// after\nawait mcpTool.execute({ query: 'x', apiKey: process.env.MCP_API_KEY }, options);","handlingStrategy":"validation","validationCode":"const requiredArgs = Object.keys(toolHeaderBindings.match(/\\{(\\w+)\\}/g) ?? []);\nconst missing = requiredArgs.filter(name => args?.[name] == null);\nif (missing.length > 0) {\n  throw new Error(`Header bindings require arguments: ${missing.join(', ')}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await mcpTool.execute(args, options);\n} catch (error) {\n  if (MCPClientError.isInstance(error) && error.message.startsWith('Failed to create MCP headers')) {\n    console.error('Header binding failed:', error.cause); // find the offending binding\n  } else {\n    throw error;\n  }\n}","preventionTips":["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"],"tags":["mcp","headers","binding","configuration"],"backgroundTag":"template-binding-resolution-failed","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}