agents 0.19.0 → 0.20.0

package/dist/mcp/server.d.ts

@@ -0,0 +1,17 @@
+import {
+  a as McpAuthContext,
+  i as createStatelessMcpHandler,
+  n as StatelessMcpHandler,
+  o as getMcpAuthContext,
+  r as StatelessMcpServerInput,
+  t as CreateStatelessMcpHandlerOptions
+} from "../handler-stateless-C_bo-Ytq.js";
+export {
+  type CreateStatelessMcpHandlerOptions as CreateMcpHandlerOptions,
+  type CreateStatelessMcpHandlerOptions,
+  type McpAuthContext,
+  type StatelessMcpHandler,
+  type StatelessMcpServerInput,
+  createStatelessMcpHandler as createMcpHandler,
+  getMcpAuthContext
+};

package/dist/mcp/server.js

@@ -0,0 +1,2 @@
+import { n as getMcpAuthContext, t as createStatelessMcpHandler } from "../handler-stateless-8hQN_kC3.js";
+export { createStatelessMcpHandler as createMcpHandler, getMcpAuthContext };

package/dist/mcp/x402.d.ts

@@ -1,10 +1,14 @@
+import {
+  n as LegacyCallToolResultSchema,
+  t as CompatibleMcpClient
+} from "../client-invoker-BNSZxAkv.js";
 import { ZodRawShape } from "zod";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import {
   CallToolRequest,
+  CallToolRequestOptions
+} from "@modelcontextprotocol/client";
+import {
   CallToolResult,
-  CallToolResultSchema,
-  CompatibilityCallToolResultSchema,
   ToolAnnotations
 } from "@modelcontextprotocol/sdk/types.js";
 import {
@@ -16,7 +20,6 @@ import {
   FacilitatorConfig,
   FacilitatorConfig as FacilitatorConfig$1
 } from "@x402/core/server";
-import { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import {
   Network,
   Network as Network$1,
@@ -65,10 +68,19 @@ interface X402AugmentedClient {
       | ((payment: PaymentRequirements$1[]) => Promise<boolean>)
       | null,
     params: CallToolRequest["params"],
-    resultSchema?:
-      | typeof CallToolResultSchema
-      | typeof CompatibilityCallToolResultSchema,
-    options?: RequestOptions
+    options?: CallToolRequestOptions
+  ): Promise<CallToolResult>;
+  /**
+   * @deprecated Prefer the request-options overload. Explicit legacy result
+   * schemas remain honored through the SDK v2 request funnel.
+   */
+  callTool(
+    x402ConfirmationCallback:
+      | ((payment: PaymentRequirements$1[]) => Promise<boolean>)
+      | null,
+    params: CallToolRequest["params"],
+    resultSchema: LegacyCallToolResultSchema,
+    options?: CallToolRequestOptions
   ): Promise<CallToolResult>;
 }
 type X402ClientConfig = {
@@ -88,7 +100,7 @@ type X402ClientConfig = {
   version?: number /** Confirmation callback for payment approval */;
   confirmationCallback?: (payment: PaymentRequirements$1[]) => Promise<boolean>;
 };
-declare function withX402Client<T extends Client>(
+declare function withX402Client<T extends CompatibleMcpClient>(
   client: T,
   x402Config: X402ClientConfig
 ): X402AugmentedClient & T;

package/dist/mcp/x402.js

@@ -1,3 +1,4 @@
+import { t as bindMcpClient } from "../client-invoker-VNZ7X0nn.js";
 import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
 import { x402Client } from "@x402/core/client";
 import { registerExactEvmScheme } from "@x402/evm/exact/server";
@@ -147,6 +148,7 @@ function withX402(server, cfg) {
 	return server;
 }
 function withX402Client(client, x402Config) {
+	const invoker = bindMcpClient(client);
 	const { account } = x402Config;
 	const maxPaymentValue = x402Config.maxPaymentValue ?? BigInt(1e5);
 	const paymentClient = new x402Client();
@@ -158,9 +160,8 @@ function withX402Client(client, x402Config) {
 			return matching.length > 0 ? matching : reqs;
 		});
 	}
-	const _listTools = client.listTools.bind(client);
 	const listTools = async (params, options) => {
-		const toolsRes = await _listTools(params, options);
+		const toolsRes = await invoker.listTools(params, options);
 		return {
 			...toolsRes,
 			tools: toolsRes.tools.map((tool) => {
@@ -176,9 +177,9 @@ function withX402Client(client, x402Config) {
 			})
 		};
 	};
-	const _callTool = client.callTool.bind(client);
-	const callToolWithPayment = async (x402ConfirmationCallback, params, resultSchema, options) => {
-		const res = await _callTool(params, resultSchema, options);
+	const callToolWithPayment = async (x402ConfirmationCallback, params, schemaOrOptions, options) => {
+		const invoke = (callParams) => invoker.callTool(callParams, schemaOrOptions, options);
+		const res = await invoke(params);
 		const maybeX402Error = res._meta?.["x402/error"];
 		if (res.isError && maybeX402Error && maybeX402Error.accepts && Array.isArray(maybeX402Error.accepts) && maybeX402Error.accepts.length > 0) {
 			const accepts = maybeX402Error.accepts;
@@ -228,13 +229,13 @@ function withX402Client(client, x402Config) {
 				};
 			}
 			const token = btoa(JSON.stringify(paymentPayload));
-			return _callTool({
+			return invoke({
 				...params,
 				_meta: {
 					...params._meta,
 					"x402/payment": token
 				}
-			}, resultSchema, options);
+			});
 		}
 		return res;
 	};

package/dist/mcp/x402.js.map

@@ -1 +1 @@
-{"version":3,"file":"x402.js","names":[],"sources":["../../src/mcp/x402.ts"],"sourcesContent":["/**\n * X402 MCP Integration (v2)\n *\n * Based on:\n * - Coinbase's x402 (Apache 2.0): https://github.com/coinbase/x402\n * - @ethanniser and his work at https://github.com/ethanniser/x402-mcp\n */\n\nimport type {\n  McpServer,\n  RegisteredTool,\n  ToolCallback\n} from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { Client as MCPClient } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport type {\n  CallToolResultSchema,\n  CompatibilityCallToolResultSchema,\n  CallToolRequest,\n  CallToolResult,\n  ToolAnnotations\n} from \"@modelcontextprotocol/sdk/types.js\";\nimport type { ZodRawShape } from \"zod\";\nimport type { RequestOptions } from \"@modelcontextprotocol/sdk/shared/protocol.js\";\n\n// v2 imports from @x402/core\nimport { x402ResourceServer, HTTPFacilitatorClient } from \"@x402/core/server\";\nimport type { FacilitatorConfig, ResourceConfig } from \"@x402/core/server\";\nimport { x402Client } from \"@x402/core/client\";\nimport type {\n  PaymentPayload,\n  PaymentRequirements,\n  PaymentRequired,\n  Network\n} from \"@x402/core/types\";\n\n// v2 imports from @x402/evm\nimport { registerExactEvmScheme as registerServerEvmScheme } from \"@x402/evm/exact/server\";\nimport { registerExactEvmScheme as registerClientEvmScheme } from \"@x402/evm/exact/client\";\nimport type { ClientEvmSigner } from \"@x402/evm\";\n\n// Re-export commonly used types for consumer convenience\nexport type {\n  PaymentRequirements,\n  PaymentRequired,\n  Network\n} from \"@x402/core/types\";\nexport type { FacilitatorConfig } from \"@x402/core/server\";\nexport type { ClientEvmSigner } from \"@x402/evm\";\n\n/**\n * Map of legacy v1 network names to CAIP-2 identifiers.\n * Allows backward compatibility with v1 config.\n */\nconst LEGACY_NETWORK_MAP: Record<string, string> = {\n  \"base-sepolia\": \"eip155:84532\",\n  base: \"eip155:8453\",\n  ethereum: \"eip155:1\",\n  sepolia: \"eip155:11155111\"\n};\n\n/**\n * Normalize a network identifier to CAIP-2 format.\n * Accepts both legacy v1 names (\"base-sepolia\") and CAIP-2 (\"eip155:84532\").\n */\nexport function normalizeNetwork(network: string): Network {\n  return (LEGACY_NETWORK_MAP[network] ?? network) as Network;\n}\n\n/*\n  ======= SERVER SIDE =======\n*/\n\nexport type X402Config = {\n  /**\n   * Network identifier.\n   * Accepts both legacy names (\"base-sepolia\") and CAIP-2 format (\"eip155:84532\").\n   */\n  network: string;\n  /** Payment recipient address */\n  recipient: `0x${string}`;\n  /** Facilitator configuration. Defaults to https://x402.org/facilitator */\n  facilitator?: FacilitatorConfig;\n  /** @deprecated No longer used in v2. The protocol version is determined automatically. */\n  version?: number;\n};\n\nexport interface X402AugmentedServer {\n  paidTool<Args extends ZodRawShape>(\n    name: string,\n    description: string,\n    priceUSD: number,\n    paramsSchema: Args,\n    annotations: ToolAnnotations,\n    cb: ToolCallback<Args>\n  ): RegisteredTool;\n}\n\nexport function withX402<T extends McpServer>(\n  server: T,\n  cfg: X402Config\n): T & X402AugmentedServer {\n  const network = normalizeNetwork(cfg.network);\n  const facilitatorConfig: FacilitatorConfig = cfg.facilitator ?? {\n    url: \"https://x402.org/facilitator\"\n  };\n\n  // Create v2 resource server with facilitator client\n  const facilitatorClient = new HTTPFacilitatorClient(facilitatorConfig);\n  const resourceServer = new x402ResourceServer(facilitatorClient);\n  registerServerEvmScheme(resourceServer);\n\n  // Lazy initialization: fetch supported kinds from facilitator on first use\n  let initPromise: Promise<void> | null = null;\n  function ensureInitialized(): Promise<void> {\n    if (!initPromise) {\n      initPromise = resourceServer.initialize().catch((err) => {\n        initPromise = null; // allow retry on failure\n        throw err;\n      });\n    }\n    return initPromise;\n  }\n\n  function paidTool<Args extends ZodRawShape>(\n    name: string,\n    description: string,\n    priceUSD: number,\n    paramsSchema: Args,\n    annotations: ToolAnnotations,\n    cb: ToolCallback<Args>\n  ): RegisteredTool {\n    return server.registerTool(\n      name,\n      {\n        description,\n        inputSchema: paramsSchema,\n        annotations,\n        _meta: {\n          \"agents-x402/paymentRequired\": true,\n          \"agents-x402/priceUSD\": priceUSD\n        }\n      },\n      (async (args, extra) => {\n        await ensureInitialized();\n\n        // Build v2 payment requirements for this tool call\n        const resourceConfig: ResourceConfig = {\n          scheme: \"exact\",\n          payTo: cfg.recipient,\n          price: priceUSD,\n          network,\n          maxTimeoutSeconds: 300\n        };\n\n        let requirements: PaymentRequirements[];\n        try {\n          requirements =\n            await resourceServer.buildPaymentRequirements(resourceConfig);\n        } catch {\n          const payload = { x402Version: 2, error: \"PRICE_COMPUTE_FAILED\" };\n          return {\n            isError: true,\n            _meta: { \"x402/error\": payload },\n            content: [{ type: \"text\", text: JSON.stringify(payload) }]\n          } as const;\n        }\n\n        const resourceInfo = {\n          url: `x402://${name}`,\n          description,\n          mimeType: \"application/json\"\n        };\n\n        // Get payment token from MCP _meta or HTTP headers\n        // Support both v2 (PAYMENT-SIGNATURE) and v1 (X-PAYMENT) header names\n        const headers = extra?.requestInfo?.headers ?? {};\n        const token =\n          (extra?._meta?.[\"x402/payment\"] as string | undefined) ??\n          headers[\"PAYMENT-SIGNATURE\"] ??\n          headers[\"X-PAYMENT\"];\n\n        const paymentRequired = (\n          reason = \"PAYMENT_REQUIRED\",\n          extraFields: Record<string, unknown> = {}\n        ) => {\n          const payload = {\n            x402Version: 2,\n            error: reason,\n            resource: resourceInfo,\n            accepts: requirements,\n            ...extraFields\n          };\n          return {\n            isError: true,\n            _meta: { \"x402/error\": payload },\n            content: [{ type: \"text\", text: JSON.stringify(payload) }]\n          } as const;\n        };\n\n        if (!token || typeof token !== \"string\") return paymentRequired();\n\n        // Decode the payment payload (base64-encoded JSON)\n        let paymentPayload: PaymentPayload;\n        try {\n          paymentPayload = JSON.parse(atob(token));\n        } catch {\n          return paymentRequired(\"INVALID_PAYMENT\");\n        }\n\n        // Find matching requirements for this payment\n        const matchingReq = resourceServer.findMatchingRequirements(\n          requirements,\n          paymentPayload\n        );\n        if (!matchingReq) {\n          return paymentRequired(\"INVALID_PAYMENT\");\n        }\n\n        // Verify payment with facilitator\n        try {\n          const vr = await resourceServer.verifyPayment(\n            paymentPayload,\n            matchingReq\n          );\n          if (!vr.isValid) {\n            return paymentRequired(vr.invalidReason ?? \"INVALID_PAYMENT\", {\n              payer: vr.payer\n            });\n          }\n        } catch {\n          return paymentRequired(\"INVALID_PAYMENT\");\n        }\n\n        // Execute the tool callback\n        let result: CallToolResult;\n        let failed = false;\n        try {\n          result = await cb(args, extra);\n          if (\n            result &&\n            typeof result === \"object\" &&\n            \"isError\" in result &&\n            result.isError\n          ) {\n            failed = true;\n          }\n        } catch (e) {\n          failed = true;\n          result = {\n            isError: true,\n            content: [\n              { type: \"text\", text: `Tool execution failed: ${String(e)}` }\n            ]\n          };\n        }\n\n        // Settle payment only on success\n        if (!failed) {\n          try {\n            const s = await resourceServer.settlePayment(\n              paymentPayload,\n              matchingReq\n            );\n            if (s.success) {\n              result._meta ??= {};\n              result._meta[\"x402/payment-response\"] = {\n                success: true,\n                transaction: s.transaction,\n                network: s.network,\n                payer: s.payer\n              };\n            } else {\n              return paymentRequired(s.errorReason ?? \"SETTLEMENT_FAILED\");\n            }\n          } catch {\n            return paymentRequired(\"SETTLEMENT_FAILED\");\n          }\n        }\n\n        return result;\n      }) as ToolCallback<Args>\n    );\n  }\n\n  Object.defineProperty(server, \"paidTool\", {\n    value: paidTool,\n    writable: false,\n    enumerable: false,\n    configurable: true\n  });\n\n  // Tell TS the object now also has the paidTool method\n  return server as T & X402AugmentedServer;\n}\n\n/*\n  ======= CLIENT SIDE =======\n*/\n\nexport interface X402AugmentedClient {\n  callTool(\n    x402ConfirmationCallback:\n      | ((payment: PaymentRequirements[]) => Promise<boolean>)\n      | null,\n    params: CallToolRequest[\"params\"],\n    resultSchema?:\n      | typeof CallToolResultSchema\n      | typeof CompatibilityCallToolResultSchema,\n    options?: RequestOptions\n  ): Promise<CallToolResult>;\n}\n\nexport type X402ClientConfig = {\n  /**\n   * EVM account/signer for signing payment authorizations.\n   * Use `privateKeyToAccount()` from viem/accounts to create one.\n   */\n  account: ClientEvmSigner;\n  /**\n   * Preferred network identifier (optional).\n   * Accepts both legacy names (\"base-sepolia\") and CAIP-2 format (\"eip155:84532\").\n   * When set, the client prefers payment requirements matching this network.\n   * If omitted, the client automatically selects from available requirements.\n   */\n  network?: string;\n  /** Maximum payment value in atomic units (default: 0.10 USDC = 100000) */\n  maxPaymentValue?: bigint;\n  /** @deprecated No longer used in v2. The protocol version is determined automatically. */\n  version?: number;\n  /** Confirmation callback for payment approval */\n  confirmationCallback?: (payment: PaymentRequirements[]) => Promise<boolean>;\n};\n\nexport function withX402Client<T extends MCPClient>(\n  client: T,\n  x402Config: X402ClientConfig\n): X402AugmentedClient & T {\n  const { account } = x402Config;\n\n  const maxPaymentValue = x402Config.maxPaymentValue ?? BigInt(100_000); // 0.10 USDC\n\n  // Create v2 x402 payment client with EVM scheme support\n  const paymentClient = new x402Client();\n  registerClientEvmScheme(paymentClient, { signer: account });\n\n  // If a preferred network is specified, register a policy to prefer it\n  if (x402Config.network) {\n    const preferredNetwork = normalizeNetwork(x402Config.network);\n    paymentClient.registerPolicy((_version, reqs) => {\n      const matching = reqs.filter((r) => r.network === preferredNetwork);\n      return matching.length > 0 ? matching : reqs;\n    });\n  }\n\n  const _listTools = client.listTools.bind(client);\n\n  // Wrap the original method to include payment information in the description\n  const listTools: typeof _listTools = async (params, options) => {\n    const toolsRes = await _listTools(params, options);\n    return {\n      ...toolsRes,\n      tools: toolsRes.tools.map((tool) => {\n        let description = tool.description;\n        // Check _meta for payment information (agents-x402/ is our extension for pre-advertising prices)\n        if (tool._meta?.[\"agents-x402/paymentRequired\"]) {\n          const cost = tool._meta?.[\"agents-x402/priceUSD\"]\n            ? `$${tool._meta?.[\"agents-x402/priceUSD\"]}`\n            : \"an unknown amount\";\n          description += ` (This is a paid tool, you will be charged ${cost} for its execution)`;\n        }\n        return {\n          ...tool,\n          description\n        };\n      })\n    };\n  };\n\n  const _callTool = client.callTool.bind(client);\n\n  const callToolWithPayment = async (\n    x402ConfirmationCallback:\n      | ((payment: PaymentRequirements[]) => Promise<boolean>)\n      | null,\n    params: CallToolRequest[\"params\"],\n    resultSchema?:\n      | typeof CallToolResultSchema\n      | typeof CompatibilityCallToolResultSchema,\n    options?: RequestOptions\n  ): ReturnType<typeof client.callTool> => {\n    // Call the tool\n    const res = await _callTool(params, resultSchema, options);\n\n    // Check for x402 payment required error in response metadata\n    const maybeX402Error = res._meta?.[\"x402/error\"] as\n      | (PaymentRequired & Record<string, unknown>)\n      | undefined;\n\n    if (\n      res.isError &&\n      maybeX402Error &&\n      maybeX402Error.accepts &&\n      Array.isArray(maybeX402Error.accepts) &&\n      maybeX402Error.accepts.length > 0\n    ) {\n      const accepts = maybeX402Error.accepts;\n      const confirmationCallback =\n        x402ConfirmationCallback ?? x402Config.confirmationCallback;\n\n      // Use the confirmation callback if provided\n      if (confirmationCallback && !(await confirmationCallback(accepts))) {\n        return {\n          isError: true,\n          content: [{ type: \"text\", text: \"User declined payment\" }]\n        };\n      }\n\n      // Check max payment value against the first requirement's amount\n      const selectedReq = accepts[0];\n      if (!selectedReq || selectedReq.scheme !== \"exact\") return res;\n\n      let amount: bigint;\n      try {\n        amount = BigInt(selectedReq.amount);\n      } catch {\n        return res; // malformed amount — return original error\n      }\n      if (amount > maxPaymentValue) {\n        return {\n          isError: true,\n          content: [\n            {\n              type: \"text\",\n              text: `Payment exceeds client cap: ${amount} > ${maxPaymentValue}`\n            }\n          ]\n        };\n      }\n\n      // Reconstruct the PaymentRequired response for the v2 x402 client\n      const paymentRequiredResponse: PaymentRequired = {\n        x402Version: (maybeX402Error.x402Version as number) ?? 2,\n        resource: (maybeX402Error.resource as PaymentRequired[\"resource\"]) ?? {\n          url: \"\",\n          description: \"\",\n          mimeType: \"application/json\"\n        },\n        accepts,\n        extensions: maybeX402Error.extensions as\n          | Record<string, unknown>\n          | undefined\n      };\n\n      // Create the payment payload using the v2 x402 client\n      let paymentPayload: PaymentPayload;\n      try {\n        paymentPayload = await paymentClient.createPaymentPayload(\n          paymentRequiredResponse\n        );\n      } catch {\n        return {\n          isError: true,\n          content: [{ type: \"text\", text: \"Failed to create payment payload\" }]\n        };\n      }\n\n      // Encode the payment payload as a base64 JSON token for MCP transport\n      const token = btoa(JSON.stringify(paymentPayload));\n\n      // Retry the tool call with the payment token\n      return _callTool(\n        {\n          ...params,\n          _meta: {\n            ...params._meta,\n            \"x402/payment\": token\n          }\n        },\n        resultSchema,\n        options\n      );\n    }\n\n    return res;\n  };\n\n  const _client = client as X402AugmentedClient & T;\n  Object.defineProperty(_client, \"listTools\", {\n    value: listTools,\n    writable: false,\n    enumerable: false,\n    configurable: true\n  });\n  Object.defineProperty(_client, \"callTool\", {\n    value: callToolWithPayment,\n    writable: false,\n    enumerable: false,\n    configurable: true\n  });\n\n  return _client;\n}\n"],"mappings":";;;;;;;;;AAqDA,MAAM,qBAA6C;CACjD,gBAAgB;CAChB,MAAM;CACN,UAAU;CACV,SAAS;AACX;;;;;AAMA,SAAgB,iBAAiB,SAA0B;CACzD,OAAQ,mBAAmB,YAAY;AACzC;AA+BA,SAAgB,SACd,QACA,KACyB;CACzB,MAAM,UAAU,iBAAiB,IAAI,OAAO;CAO5C,MAAM,iBAAiB,IAAI,mBAAmB,IADhB,sBALe,IAAI,eAAe,EAC9D,KAAK,+BACP,CAI8D,CAAC;CAC/D,uBAAwB,cAAc;CAGtC,IAAI,cAAoC;CACxC,SAAS,oBAAmC;EAC1C,IAAI,CAAC,aACH,cAAc,eAAe,WAAW,CAAC,CAAC,OAAO,QAAQ;GACvD,cAAc;GACd,MAAM;EACR,CAAC;EAEH,OAAO;CACT;CAEA,SAAS,SACP,MACA,aACA,UACA,cACA,aACA,IACgB;EAChB,OAAO,OAAO,aACZ,MACA;GACE;GACA,aAAa;GACb;GACA,OAAO;IACL,+BAA+B;IAC/B,wBAAwB;GAC1B;EACF,IACC,OAAO,MAAM,UAAU;GACtB,MAAM,kBAAkB;GAGxB,MAAM,iBAAiC;IACrC,QAAQ;IACR,OAAO,IAAI;IACX,OAAO;IACP;IACA,mBAAmB;GACrB;GAEA,IAAI;GACJ,IAAI;IACF,eACE,MAAM,eAAe,yBAAyB,cAAc;GAChE,QAAQ;IACN,MAAM,UAAU;KAAE,aAAa;KAAG,OAAO;IAAuB;IAChE,OAAO;KACL,SAAS;KACT,OAAO,EAAE,cAAc,QAAQ;KAC/B,SAAS,CAAC;MAAE,MAAM;MAAQ,MAAM,KAAK,UAAU,OAAO;KAAE,CAAC;IAC3D;GACF;GAEA,MAAM,eAAe;IACnB,KAAK,UAAU;IACf;IACA,UAAU;GACZ;GAIA,MAAM,UAAU,OAAO,aAAa,WAAW,CAAC;GAChD,MAAM,QACH,OAAO,QAAQ,mBAChB,QAAQ,wBACR,QAAQ;GAEV,MAAM,mBACJ,SAAS,oBACT,cAAuC,CAAC,MACrC;IACH,MAAM,UAAU;KACd,aAAa;KACb,OAAO;KACP,UAAU;KACV,SAAS;KACT,GAAG;IACL;IACA,OAAO;KACL,SAAS;KACT,OAAO,EAAE,cAAc,QAAQ;KAC/B,SAAS,CAAC;MAAE,MAAM;MAAQ,MAAM,KAAK,UAAU,OAAO;KAAE,CAAC;IAC3D;GACF;GAEA,IAAI,CAAC,SAAS,OAAO,UAAU,UAAU,OAAO,gBAAgB;GAGhE,IAAI;GACJ,IAAI;IACF,iBAAiB,KAAK,MAAM,KAAK,KAAK,CAAC;GACzC,QAAQ;IACN,OAAO,gBAAgB,iBAAiB;GAC1C;GAGA,MAAM,cAAc,eAAe,yBACjC,cACA,cACF;GACA,IAAI,CAAC,aACH,OAAO,gBAAgB,iBAAiB;GAI1C,IAAI;IACF,MAAM,KAAK,MAAM,eAAe,cAC9B,gBACA,WACF;IACA,IAAI,CAAC,GAAG,SACN,OAAO,gBAAgB,GAAG,iBAAiB,mBAAmB,EAC5D,OAAO,GAAG,MACZ,CAAC;GAEL,QAAQ;IACN,OAAO,gBAAgB,iBAAiB;GAC1C;GAGA,IAAI;GACJ,IAAI,SAAS;GACb,IAAI;IACF,SAAS,MAAM,GAAG,MAAM,KAAK;IAC7B,IACE,UACA,OAAO,WAAW,YAClB,aAAa,UACb,OAAO,SAEP,SAAS;GAEb,SAAS,GAAG;IACV,SAAS;IACT,SAAS;KACP,SAAS;KACT,SAAS,CACP;MAAE,MAAM;MAAQ,MAAM,0BAA0B,OAAO,CAAC;KAAI,CAC9D;IACF;GACF;GAGA,IAAI,CAAC,QACH,IAAI;IACF,MAAM,IAAI,MAAM,eAAe,cAC7B,gBACA,WACF;IACA,IAAI,EAAE,SAAS;KACb,OAAO,UAAU,CAAC;KAClB,OAAO,MAAM,2BAA2B;MACtC,SAAS;MACT,aAAa,EAAE;MACf,SAAS,EAAE;MACX,OAAO,EAAE;KACX;IACF,OACE,OAAO,gBAAgB,EAAE,eAAe,mBAAmB;GAE/D,QAAQ;IACN,OAAO,gBAAgB,mBAAmB;GAC5C;GAGF,OAAO;EACT,EACF;CACF;CAEA,OAAO,eAAe,QAAQ,YAAY;EACxC,OAAO;EACP,UAAU;EACV,YAAY;EACZ,cAAc;CAChB,CAAC;CAGD,OAAO;AACT;AAwCA,SAAgB,eACd,QACA,YACyB;CACzB,MAAM,EAAE,YAAY;CAEpB,MAAM,kBAAkB,WAAW,mBAAmB,OAAO,GAAO;CAGpE,MAAM,gBAAgB,IAAI,WAAW;CACrC,yBAAwB,eAAe,EAAE,QAAQ,QAAQ,CAAC;CAG1D,IAAI,WAAW,SAAS;EACtB,MAAM,mBAAmB,iBAAiB,WAAW,OAAO;EAC5D,cAAc,gBAAgB,UAAU,SAAS;GAC/C,MAAM,WAAW,KAAK,QAAQ,MAAM,EAAE,YAAY,gBAAgB;GAClE,OAAO,SAAS,SAAS,IAAI,WAAW;EAC1C,CAAC;CACH;CAEA,MAAM,aAAa,OAAO,UAAU,KAAK,MAAM;CAG/C,MAAM,YAA+B,OAAO,QAAQ,YAAY;EAC9D,MAAM,WAAW,MAAM,WAAW,QAAQ,OAAO;EACjD,OAAO;GACL,GAAG;GACH,OAAO,SAAS,MAAM,KAAK,SAAS;IAClC,IAAI,cAAc,KAAK;IAEvB,IAAI,KAAK,QAAQ,gCAAgC;KAC/C,MAAM,OAAO,KAAK,QAAQ,0BACtB,IAAI,KAAK,QAAQ,4BACjB;KACJ,eAAe,8CAA8C,KAAK;IACpE;IACA,OAAO;KACL,GAAG;KACH;IACF;GACF,CAAC;EACH;CACF;CAEA,MAAM,YAAY,OAAO,SAAS,KAAK,MAAM;CAE7C,MAAM,sBAAsB,OAC1B,0BAGA,QACA,cAGA,YACuC;EAEvC,MAAM,MAAM,MAAM,UAAU,QAAQ,cAAc,OAAO;EAGzD,MAAM,iBAAiB,IAAI,QAAQ;EAInC,IACE,IAAI,WACJ,kBACA,eAAe,WACf,MAAM,QAAQ,eAAe,OAAO,KACpC,eAAe,QAAQ,SAAS,GAChC;GACA,MAAM,UAAU,eAAe;GAC/B,MAAM,uBACJ,4BAA4B,WAAW;GAGzC,IAAI,wBAAwB,CAAE,MAAM,qBAAqB,OAAO,GAC9D,OAAO;IACL,SAAS;IACT,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM;IAAwB,CAAC;GAC3D;GAIF,MAAM,cAAc,QAAQ;GAC5B,IAAI,CAAC,eAAe,YAAY,WAAW,SAAS,OAAO;GAE3D,IAAI;GACJ,IAAI;IACF,SAAS,OAAO,YAAY,MAAM;GACpC,QAAQ;IACN,OAAO;GACT;GACA,IAAI,SAAS,iBACX,OAAO;IACL,SAAS;IACT,SAAS,CACP;KACE,MAAM;KACN,MAAM,+BAA+B,OAAO,KAAK;IACnD,CACF;GACF;GAIF,MAAM,0BAA2C;IAC/C,aAAc,eAAe,eAA0B;IACvD,UAAW,eAAe,YAA4C;KACpE,KAAK;KACL,aAAa;KACb,UAAU;IACZ;IACA;IACA,YAAY,eAAe;GAG7B;GAGA,IAAI;GACJ,IAAI;IACF,iBAAiB,MAAM,cAAc,qBACnC,uBACF;GACF,QAAQ;IACN,OAAO;KACL,SAAS;KACT,SAAS,CAAC;MAAE,MAAM;MAAQ,MAAM;KAAmC,CAAC;IACtE;GACF;GAGA,MAAM,QAAQ,KAAK,KAAK,UAAU,cAAc,CAAC;GAGjD,OAAO,UACL;IACE,GAAG;IACH,OAAO;KACL,GAAG,OAAO;KACV,gBAAgB;IAClB;GACF,GACA,cACA,OACF;EACF;EAEA,OAAO;CACT;CAEA,MAAM,UAAU;CAChB,OAAO,eAAe,SAAS,aAAa;EAC1C,OAAO;EACP,UAAU;EACV,YAAY;EACZ,cAAc;CAChB,CAAC;CACD,OAAO,eAAe,SAAS,YAAY;EACzC,OAAO;EACP,UAAU;EACV,YAAY;EACZ,cAAc;CAChB,CAAC;CAED,OAAO;AACT"}
+{"version":3,"file":"x402.js","names":[],"sources":["../../src/mcp/x402.ts"],"sourcesContent":["/**\n * X402 MCP Integration (v2)\n *\n * Based on:\n * - Coinbase's x402 (Apache 2.0): https://github.com/coinbase/x402\n * - @ethanniser and his work at https://github.com/ethanniser/x402-mcp\n */\n\nimport type {\n  McpServer,\n  RegisteredTool,\n  ToolCallback\n} from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type {\n  CallToolRequest,\n  CallToolRequestOptions,\n  Client as MCPClient\n} from \"@modelcontextprotocol/client\";\nimport type {\n  CallToolResult,\n  ToolAnnotations\n} from \"@modelcontextprotocol/sdk/types.js\";\nimport {\n  bindMcpClient,\n  type CallToolSchemaOrOptions,\n  type CompatibleMcpClient,\n  type LegacyCallToolResultSchema\n} from \"./client-invoker\";\nimport type { ZodRawShape } from \"zod\";\n\n// v2 imports from @x402/core\nimport { x402ResourceServer, HTTPFacilitatorClient } from \"@x402/core/server\";\nimport type { FacilitatorConfig, ResourceConfig } from \"@x402/core/server\";\nimport { x402Client } from \"@x402/core/client\";\nimport type {\n  PaymentPayload,\n  PaymentRequirements,\n  PaymentRequired,\n  Network\n} from \"@x402/core/types\";\n\n// v2 imports from @x402/evm\nimport { registerExactEvmScheme as registerServerEvmScheme } from \"@x402/evm/exact/server\";\nimport { registerExactEvmScheme as registerClientEvmScheme } from \"@x402/evm/exact/client\";\nimport type { ClientEvmSigner } from \"@x402/evm\";\n\n// Re-export commonly used types for consumer convenience\nexport type {\n  PaymentRequirements,\n  PaymentRequired,\n  Network\n} from \"@x402/core/types\";\nexport type { FacilitatorConfig } from \"@x402/core/server\";\nexport type { ClientEvmSigner } from \"@x402/evm\";\n\n/**\n * Map of legacy v1 network names to CAIP-2 identifiers.\n * Allows backward compatibility with v1 config.\n */\nconst LEGACY_NETWORK_MAP: Record<string, string> = {\n  \"base-sepolia\": \"eip155:84532\",\n  base: \"eip155:8453\",\n  ethereum: \"eip155:1\",\n  sepolia: \"eip155:11155111\"\n};\n\n/**\n * Normalize a network identifier to CAIP-2 format.\n * Accepts both legacy v1 names (\"base-sepolia\") and CAIP-2 (\"eip155:84532\").\n */\nexport function normalizeNetwork(network: string): Network {\n  return (LEGACY_NETWORK_MAP[network] ?? network) as Network;\n}\n\n/*\n  ======= SERVER SIDE =======\n*/\n\nexport type X402Config = {\n  /**\n   * Network identifier.\n   * Accepts both legacy names (\"base-sepolia\") and CAIP-2 format (\"eip155:84532\").\n   */\n  network: string;\n  /** Payment recipient address */\n  recipient: `0x${string}`;\n  /** Facilitator configuration. Defaults to https://x402.org/facilitator */\n  facilitator?: FacilitatorConfig;\n  /** @deprecated No longer used in v2. The protocol version is determined automatically. */\n  version?: number;\n};\n\nexport interface X402AugmentedServer {\n  paidTool<Args extends ZodRawShape>(\n    name: string,\n    description: string,\n    priceUSD: number,\n    paramsSchema: Args,\n    annotations: ToolAnnotations,\n    cb: ToolCallback<Args>\n  ): RegisteredTool;\n}\n\nexport function withX402<T extends McpServer>(\n  server: T,\n  cfg: X402Config\n): T & X402AugmentedServer {\n  const network = normalizeNetwork(cfg.network);\n  const facilitatorConfig: FacilitatorConfig = cfg.facilitator ?? {\n    url: \"https://x402.org/facilitator\"\n  };\n\n  // Create v2 resource server with facilitator client\n  const facilitatorClient = new HTTPFacilitatorClient(facilitatorConfig);\n  const resourceServer = new x402ResourceServer(facilitatorClient);\n  registerServerEvmScheme(resourceServer);\n\n  // Lazy initialization: fetch supported kinds from facilitator on first use\n  let initPromise: Promise<void> | null = null;\n  function ensureInitialized(): Promise<void> {\n    if (!initPromise) {\n      initPromise = resourceServer.initialize().catch((err) => {\n        initPromise = null; // allow retry on failure\n        throw err;\n      });\n    }\n    return initPromise;\n  }\n\n  function paidTool<Args extends ZodRawShape>(\n    name: string,\n    description: string,\n    priceUSD: number,\n    paramsSchema: Args,\n    annotations: ToolAnnotations,\n    cb: ToolCallback<Args>\n  ): RegisteredTool {\n    return server.registerTool(\n      name,\n      {\n        description,\n        inputSchema: paramsSchema,\n        annotations,\n        _meta: {\n          \"agents-x402/paymentRequired\": true,\n          \"agents-x402/priceUSD\": priceUSD\n        }\n      },\n      (async (args, extra) => {\n        await ensureInitialized();\n\n        // Build v2 payment requirements for this tool call\n        const resourceConfig: ResourceConfig = {\n          scheme: \"exact\",\n          payTo: cfg.recipient,\n          price: priceUSD,\n          network,\n          maxTimeoutSeconds: 300\n        };\n\n        let requirements: PaymentRequirements[];\n        try {\n          requirements =\n            await resourceServer.buildPaymentRequirements(resourceConfig);\n        } catch {\n          const payload = { x402Version: 2, error: \"PRICE_COMPUTE_FAILED\" };\n          return {\n            isError: true,\n            _meta: { \"x402/error\": payload },\n            content: [{ type: \"text\", text: JSON.stringify(payload) }]\n          } as const;\n        }\n\n        const resourceInfo = {\n          url: `x402://${name}`,\n          description,\n          mimeType: \"application/json\"\n        };\n\n        // Get payment token from MCP _meta or HTTP headers\n        // Support both v2 (PAYMENT-SIGNATURE) and v1 (X-PAYMENT) header names\n        const headers = extra?.requestInfo?.headers ?? {};\n        const token =\n          (extra?._meta?.[\"x402/payment\"] as string | undefined) ??\n          headers[\"PAYMENT-SIGNATURE\"] ??\n          headers[\"X-PAYMENT\"];\n\n        const paymentRequired = (\n          reason = \"PAYMENT_REQUIRED\",\n          extraFields: Record<string, unknown> = {}\n        ) => {\n          const payload = {\n            x402Version: 2,\n            error: reason,\n            resource: resourceInfo,\n            accepts: requirements,\n            ...extraFields\n          };\n          return {\n            isError: true,\n            _meta: { \"x402/error\": payload },\n            content: [{ type: \"text\", text: JSON.stringify(payload) }]\n          } as const;\n        };\n\n        if (!token || typeof token !== \"string\") return paymentRequired();\n\n        // Decode the payment payload (base64-encoded JSON)\n        let paymentPayload: PaymentPayload;\n        try {\n          paymentPayload = JSON.parse(atob(token));\n        } catch {\n          return paymentRequired(\"INVALID_PAYMENT\");\n        }\n\n        // Find matching requirements for this payment\n        const matchingReq = resourceServer.findMatchingRequirements(\n          requirements,\n          paymentPayload\n        );\n        if (!matchingReq) {\n          return paymentRequired(\"INVALID_PAYMENT\");\n        }\n\n        // Verify payment with facilitator\n        try {\n          const vr = await resourceServer.verifyPayment(\n            paymentPayload,\n            matchingReq\n          );\n          if (!vr.isValid) {\n            return paymentRequired(vr.invalidReason ?? \"INVALID_PAYMENT\", {\n              payer: vr.payer\n            });\n          }\n        } catch {\n          return paymentRequired(\"INVALID_PAYMENT\");\n        }\n\n        // Execute the tool callback\n        let result: CallToolResult;\n        let failed = false;\n        try {\n          result = await cb(args, extra);\n          if (\n            result &&\n            typeof result === \"object\" &&\n            \"isError\" in result &&\n            result.isError\n          ) {\n            failed = true;\n          }\n        } catch (e) {\n          failed = true;\n          result = {\n            isError: true,\n            content: [\n              { type: \"text\", text: `Tool execution failed: ${String(e)}` }\n            ]\n          };\n        }\n\n        // Settle payment only on success\n        if (!failed) {\n          try {\n            const s = await resourceServer.settlePayment(\n              paymentPayload,\n              matchingReq\n            );\n            if (s.success) {\n              result._meta ??= {};\n              result._meta[\"x402/payment-response\"] = {\n                success: true,\n                transaction: s.transaction,\n                network: s.network,\n                payer: s.payer\n              };\n            } else {\n              return paymentRequired(s.errorReason ?? \"SETTLEMENT_FAILED\");\n            }\n          } catch {\n            return paymentRequired(\"SETTLEMENT_FAILED\");\n          }\n        }\n\n        return result;\n      }) as ToolCallback<Args>\n    );\n  }\n\n  Object.defineProperty(server, \"paidTool\", {\n    value: paidTool,\n    writable: false,\n    enumerable: false,\n    configurable: true\n  });\n\n  // Tell TS the object now also has the paidTool method\n  return server as T & X402AugmentedServer;\n}\n\n/*\n  ======= CLIENT SIDE =======\n*/\n\nexport interface X402AugmentedClient {\n  callTool(\n    x402ConfirmationCallback:\n      | ((payment: PaymentRequirements[]) => Promise<boolean>)\n      | null,\n    params: CallToolRequest[\"params\"],\n    options?: CallToolRequestOptions\n  ): Promise<CallToolResult>;\n  /**\n   * @deprecated Prefer the request-options overload. Explicit legacy result\n   * schemas remain honored through the SDK v2 request funnel.\n   */\n  callTool(\n    x402ConfirmationCallback:\n      | ((payment: PaymentRequirements[]) => Promise<boolean>)\n      | null,\n    params: CallToolRequest[\"params\"],\n    resultSchema: LegacyCallToolResultSchema,\n    options?: CallToolRequestOptions\n  ): Promise<CallToolResult>;\n}\n\nexport type X402ClientConfig = {\n  /**\n   * EVM account/signer for signing payment authorizations.\n   * Use `privateKeyToAccount()` from viem/accounts to create one.\n   */\n  account: ClientEvmSigner;\n  /**\n   * Preferred network identifier (optional).\n   * Accepts both legacy names (\"base-sepolia\") and CAIP-2 format (\"eip155:84532\").\n   * When set, the client prefers payment requirements matching this network.\n   * If omitted, the client automatically selects from available requirements.\n   */\n  network?: string;\n  /** Maximum payment value in atomic units (default: 0.10 USDC = 100000) */\n  maxPaymentValue?: bigint;\n  /** @deprecated No longer used in v2. The protocol version is determined automatically. */\n  version?: number;\n  /** Confirmation callback for payment approval */\n  confirmationCallback?: (payment: PaymentRequirements[]) => Promise<boolean>;\n};\n\nexport function withX402Client<T extends CompatibleMcpClient>(\n  client: T,\n  x402Config: X402ClientConfig\n): X402AugmentedClient & T {\n  const invoker = bindMcpClient(client);\n  const { account } = x402Config;\n\n  const maxPaymentValue = x402Config.maxPaymentValue ?? BigInt(100_000); // 0.10 USDC\n\n  // Create v2 x402 payment client with EVM scheme support\n  const paymentClient = new x402Client();\n  registerClientEvmScheme(paymentClient, { signer: account });\n\n  // If a preferred network is specified, register a policy to prefer it\n  if (x402Config.network) {\n    const preferredNetwork = normalizeNetwork(x402Config.network);\n    paymentClient.registerPolicy((_version, reqs) => {\n      const matching = reqs.filter((r) => r.network === preferredNetwork);\n      return matching.length > 0 ? matching : reqs;\n    });\n  }\n\n  const listTools = async (\n    params?: Parameters<MCPClient[\"listTools\"]>[0],\n    options?: Parameters<MCPClient[\"listTools\"]>[1]\n  ) => {\n    const toolsRes = await invoker.listTools(params, options);\n    return {\n      ...toolsRes,\n      tools: toolsRes.tools.map((tool) => {\n        let description = tool.description;\n        // Check _meta for payment information (agents-x402/ is our extension for pre-advertising prices)\n        if (tool._meta?.[\"agents-x402/paymentRequired\"]) {\n          const cost = tool._meta?.[\"agents-x402/priceUSD\"]\n            ? `$${tool._meta?.[\"agents-x402/priceUSD\"]}`\n            : \"an unknown amount\";\n          description += ` (This is a paid tool, you will be charged ${cost} for its execution)`;\n        }\n        return {\n          ...tool,\n          description\n        };\n      })\n    };\n  };\n\n  const callToolWithPayment = async (\n    x402ConfirmationCallback:\n      | ((payment: PaymentRequirements[]) => Promise<boolean>)\n      | null,\n    params: CallToolRequest[\"params\"],\n    schemaOrOptions?: CallToolSchemaOrOptions,\n    options?: CallToolRequestOptions\n  ): ReturnType<MCPClient[\"callTool\"]> => {\n    const invoke = (callParams: CallToolRequest[\"params\"]) =>\n      invoker.callTool(callParams, schemaOrOptions, options);\n    const res = await invoke(params);\n\n    // Check for x402 payment required error in response metadata\n    const maybeX402Error = res._meta?.[\"x402/error\"] as\n      | (PaymentRequired & Record<string, unknown>)\n      | undefined;\n\n    if (\n      res.isError &&\n      maybeX402Error &&\n      maybeX402Error.accepts &&\n      Array.isArray(maybeX402Error.accepts) &&\n      maybeX402Error.accepts.length > 0\n    ) {\n      const accepts = maybeX402Error.accepts;\n      const confirmationCallback =\n        x402ConfirmationCallback ?? x402Config.confirmationCallback;\n\n      // Use the confirmation callback if provided\n      if (confirmationCallback && !(await confirmationCallback(accepts))) {\n        return {\n          isError: true,\n          content: [{ type: \"text\", text: \"User declined payment\" }]\n        };\n      }\n\n      // Check max payment value against the first requirement's amount\n      const selectedReq = accepts[0];\n      if (!selectedReq || selectedReq.scheme !== \"exact\") return res;\n\n      let amount: bigint;\n      try {\n        amount = BigInt(selectedReq.amount);\n      } catch {\n        return res; // malformed amount — return original error\n      }\n      if (amount > maxPaymentValue) {\n        return {\n          isError: true,\n          content: [\n            {\n              type: \"text\",\n              text: `Payment exceeds client cap: ${amount} > ${maxPaymentValue}`\n            }\n          ]\n        };\n      }\n\n      // Reconstruct the PaymentRequired response for the v2 x402 client\n      const paymentRequiredResponse: PaymentRequired = {\n        x402Version: (maybeX402Error.x402Version as number) ?? 2,\n        resource: (maybeX402Error.resource as PaymentRequired[\"resource\"]) ?? {\n          url: \"\",\n          description: \"\",\n          mimeType: \"application/json\"\n        },\n        accepts,\n        extensions: maybeX402Error.extensions as\n          | Record<string, unknown>\n          | undefined\n      };\n\n      // Create the payment payload using the v2 x402 client\n      let paymentPayload: PaymentPayload;\n      try {\n        paymentPayload = await paymentClient.createPaymentPayload(\n          paymentRequiredResponse\n        );\n      } catch {\n        return {\n          isError: true,\n          content: [{ type: \"text\", text: \"Failed to create payment payload\" }]\n        };\n      }\n\n      // Encode the payment payload as a base64 JSON token for MCP transport\n      const token = btoa(JSON.stringify(paymentPayload));\n\n      // Retry the tool call with the payment token\n      return invoke({\n        ...params,\n        _meta: {\n          ...params._meta,\n          \"x402/payment\": token\n        }\n      });\n    }\n\n    return res;\n  };\n\n  const _client = client as X402AugmentedClient & T;\n  Object.defineProperty(_client, \"listTools\", {\n    value: listTools,\n    writable: false,\n    enumerable: false,\n    configurable: true\n  });\n  Object.defineProperty(_client, \"callTool\", {\n    value: callToolWithPayment,\n    writable: false,\n    enumerable: false,\n    configurable: true\n  });\n\n  return _client;\n}\n"],"mappings":";;;;;;;;;;AA2DA,MAAM,qBAA6C;CACjD,gBAAgB;CAChB,MAAM;CACN,UAAU;CACV,SAAS;AACX;;;;;AAMA,SAAgB,iBAAiB,SAA0B;CACzD,OAAQ,mBAAmB,YAAY;AACzC;AA+BA,SAAgB,SACd,QACA,KACyB;CACzB,MAAM,UAAU,iBAAiB,IAAI,OAAO;CAO5C,MAAM,iBAAiB,IAAI,mBAAmB,IADhB,sBALe,IAAI,eAAe,EAC9D,KAAK,+BACP,CAI8D,CAAC;CAC/D,uBAAwB,cAAc;CAGtC,IAAI,cAAoC;CACxC,SAAS,oBAAmC;EAC1C,IAAI,CAAC,aACH,cAAc,eAAe,WAAW,CAAC,CAAC,OAAO,QAAQ;GACvD,cAAc;GACd,MAAM;EACR,CAAC;EAEH,OAAO;CACT;CAEA,SAAS,SACP,MACA,aACA,UACA,cACA,aACA,IACgB;EAChB,OAAO,OAAO,aACZ,MACA;GACE;GACA,aAAa;GACb;GACA,OAAO;IACL,+BAA+B;IAC/B,wBAAwB;GAC1B;EACF,IACC,OAAO,MAAM,UAAU;GACtB,MAAM,kBAAkB;GAGxB,MAAM,iBAAiC;IACrC,QAAQ;IACR,OAAO,IAAI;IACX,OAAO;IACP;IACA,mBAAmB;GACrB;GAEA,IAAI;GACJ,IAAI;IACF,eACE,MAAM,eAAe,yBAAyB,cAAc;GAChE,QAAQ;IACN,MAAM,UAAU;KAAE,aAAa;KAAG,OAAO;IAAuB;IAChE,OAAO;KACL,SAAS;KACT,OAAO,EAAE,cAAc,QAAQ;KAC/B,SAAS,CAAC;MAAE,MAAM;MAAQ,MAAM,KAAK,UAAU,OAAO;KAAE,CAAC;IAC3D;GACF;GAEA,MAAM,eAAe;IACnB,KAAK,UAAU;IACf;IACA,UAAU;GACZ;GAIA,MAAM,UAAU,OAAO,aAAa,WAAW,CAAC;GAChD,MAAM,QACH,OAAO,QAAQ,mBAChB,QAAQ,wBACR,QAAQ;GAEV,MAAM,mBACJ,SAAS,oBACT,cAAuC,CAAC,MACrC;IACH,MAAM,UAAU;KACd,aAAa;KACb,OAAO;KACP,UAAU;KACV,SAAS;KACT,GAAG;IACL;IACA,OAAO;KACL,SAAS;KACT,OAAO,EAAE,cAAc,QAAQ;KAC/B,SAAS,CAAC;MAAE,MAAM;MAAQ,MAAM,KAAK,UAAU,OAAO;KAAE,CAAC;IAC3D;GACF;GAEA,IAAI,CAAC,SAAS,OAAO,UAAU,UAAU,OAAO,gBAAgB;GAGhE,IAAI;GACJ,IAAI;IACF,iBAAiB,KAAK,MAAM,KAAK,KAAK,CAAC;GACzC,QAAQ;IACN,OAAO,gBAAgB,iBAAiB;GAC1C;GAGA,MAAM,cAAc,eAAe,yBACjC,cACA,cACF;GACA,IAAI,CAAC,aACH,OAAO,gBAAgB,iBAAiB;GAI1C,IAAI;IACF,MAAM,KAAK,MAAM,eAAe,cAC9B,gBACA,WACF;IACA,IAAI,CAAC,GAAG,SACN,OAAO,gBAAgB,GAAG,iBAAiB,mBAAmB,EAC5D,OAAO,GAAG,MACZ,CAAC;GAEL,QAAQ;IACN,OAAO,gBAAgB,iBAAiB;GAC1C;GAGA,IAAI;GACJ,IAAI,SAAS;GACb,IAAI;IACF,SAAS,MAAM,GAAG,MAAM,KAAK;IAC7B,IACE,UACA,OAAO,WAAW,YAClB,aAAa,UACb,OAAO,SAEP,SAAS;GAEb,SAAS,GAAG;IACV,SAAS;IACT,SAAS;KACP,SAAS;KACT,SAAS,CACP;MAAE,MAAM;MAAQ,MAAM,0BAA0B,OAAO,CAAC;KAAI,CAC9D;IACF;GACF;GAGA,IAAI,CAAC,QACH,IAAI;IACF,MAAM,IAAI,MAAM,eAAe,cAC7B,gBACA,WACF;IACA,IAAI,EAAE,SAAS;KACb,OAAO,UAAU,CAAC;KAClB,OAAO,MAAM,2BAA2B;MACtC,SAAS;MACT,aAAa,EAAE;MACf,SAAS,EAAE;MACX,OAAO,EAAE;KACX;IACF,OACE,OAAO,gBAAgB,EAAE,eAAe,mBAAmB;GAE/D,QAAQ;IACN,OAAO,gBAAgB,mBAAmB;GAC5C;GAGF,OAAO;EACT,EACF;CACF;CAEA,OAAO,eAAe,QAAQ,YAAY;EACxC,OAAO;EACP,UAAU;EACV,YAAY;EACZ,cAAc;CAChB,CAAC;CAGD,OAAO;AACT;AAiDA,SAAgB,eACd,QACA,YACyB;CACzB,MAAM,UAAU,cAAc,MAAM;CACpC,MAAM,EAAE,YAAY;CAEpB,MAAM,kBAAkB,WAAW,mBAAmB,OAAO,GAAO;CAGpE,MAAM,gBAAgB,IAAI,WAAW;CACrC,yBAAwB,eAAe,EAAE,QAAQ,QAAQ,CAAC;CAG1D,IAAI,WAAW,SAAS;EACtB,MAAM,mBAAmB,iBAAiB,WAAW,OAAO;EAC5D,cAAc,gBAAgB,UAAU,SAAS;GAC/C,MAAM,WAAW,KAAK,QAAQ,MAAM,EAAE,YAAY,gBAAgB;GAClE,OAAO,SAAS,SAAS,IAAI,WAAW;EAC1C,CAAC;CACH;CAEA,MAAM,YAAY,OAChB,QACA,YACG;EACH,MAAM,WAAW,MAAM,QAAQ,UAAU,QAAQ,OAAO;EACxD,OAAO;GACL,GAAG;GACH,OAAO,SAAS,MAAM,KAAK,SAAS;IAClC,IAAI,cAAc,KAAK;IAEvB,IAAI,KAAK,QAAQ,gCAAgC;KAC/C,MAAM,OAAO,KAAK,QAAQ,0BACtB,IAAI,KAAK,QAAQ,4BACjB;KACJ,eAAe,8CAA8C,KAAK;IACpE;IACA,OAAO;KACL,GAAG;KACH;IACF;GACF,CAAC;EACH;CACF;CAEA,MAAM,sBAAsB,OAC1B,0BAGA,QACA,iBACA,YACsC;EACtC,MAAM,UAAU,eACd,QAAQ,SAAS,YAAY,iBAAiB,OAAO;EACvD,MAAM,MAAM,MAAM,OAAO,MAAM;EAG/B,MAAM,iBAAiB,IAAI,QAAQ;EAInC,IACE,IAAI,WACJ,kBACA,eAAe,WACf,MAAM,QAAQ,eAAe,OAAO,KACpC,eAAe,QAAQ,SAAS,GAChC;GACA,MAAM,UAAU,eAAe;GAC/B,MAAM,uBACJ,4BAA4B,WAAW;GAGzC,IAAI,wBAAwB,CAAE,MAAM,qBAAqB,OAAO,GAC9D,OAAO;IACL,SAAS;IACT,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM;IAAwB,CAAC;GAC3D;GAIF,MAAM,cAAc,QAAQ;GAC5B,IAAI,CAAC,eAAe,YAAY,WAAW,SAAS,OAAO;GAE3D,IAAI;GACJ,IAAI;IACF,SAAS,OAAO,YAAY,MAAM;GACpC,QAAQ;IACN,OAAO;GACT;GACA,IAAI,SAAS,iBACX,OAAO;IACL,SAAS;IACT,SAAS,CACP;KACE,MAAM;KACN,MAAM,+BAA+B,OAAO,KAAK;IACnD,CACF;GACF;GAIF,MAAM,0BAA2C;IAC/C,aAAc,eAAe,eAA0B;IACvD,UAAW,eAAe,YAA4C;KACpE,KAAK;KACL,aAAa;KACb,UAAU;IACZ;IACA;IACA,YAAY,eAAe;GAG7B;GAGA,IAAI;GACJ,IAAI;IACF,iBAAiB,MAAM,cAAc,qBACnC,uBACF;GACF,QAAQ;IACN,OAAO;KACL,SAAS;KACT,SAAS,CAAC;MAAE,MAAM;MAAQ,MAAM;KAAmC,CAAC;IACtE;GACF;GAGA,MAAM,QAAQ,KAAK,KAAK,UAAU,cAAc,CAAC;GAGjD,OAAO,OAAO;IACZ,GAAG;IACH,OAAO;KACL,GAAG,OAAO;KACV,gBAAgB;IAClB;GACF,CAAC;EACH;EAEA,OAAO;CACT;CAEA,MAAM,UAAU;CAChB,OAAO,eAAe,SAAS,aAAa;EAC1C,OAAO;EACP,UAAU;EACV,YAAY;EACZ,cAAc;CAChB,CAAC;CACD,OAAO,eAAe,SAAS,YAAY;EACzC,OAAO;EACP,UAAU;EACV,YAAY;EACZ,cAAc;CAChB,CAAC;CAED,OAAO;AACT"}

package/dist/react.d.ts

@@ -2,7 +2,7 @@ import {
   Y as MCPServersState,
   _ as AgentToolRunState,
   g as AgentToolRunPart
-} from "./agent-tool-types-BNUGGBzQ.js";
+} from "./agent-tool-types-Btk9ETS-.js";
 import { ClientParameters } from "./serializable.js";
 import {
   AgentConnectionError,

package/dist/serializable.d.ts

@@ -1,4 +1,4 @@
-import { st as StreamingResponse } from "./agent-tool-types-BNUGGBzQ.js";
+import { st as StreamingResponse } from "./agent-tool-types-Btk9ETS-.js";
 
 //#region src/serializable.d.ts
 type SerializablePrimitive = undefined | null | string | number | boolean;

package/dist/sub-routing.d.ts

@@ -1,10 +1,10 @@
 import {
-  an as SUB_PREFIX,
-  cn as parseSubAgentPath,
-  ln as routeSubAgentRequest,
-  on as SubAgentPathMatch,
-  sn as getSubAgentByName
-} from "./agent-tool-types-BNUGGBzQ.js";
+  cn as SubAgentPathMatch,
+  dn as routeSubAgentRequest,
+  ln as getSubAgentByName,
+  sn as SUB_PREFIX,
+  un as parseSubAgentPath
+} from "./agent-tool-types-Btk9ETS-.js";
 export {
   SUB_PREFIX,
   SubAgentPathMatch,

package/dist/workflows.d.ts

@@ -1,4 +1,4 @@
-import { O as Agent } from "./agent-tool-types-BNUGGBzQ.js";
+import { O as Agent } from "./agent-tool-types-Btk9ETS-.js";
 import {
   C as WorkflowStatus,
   S as WorkflowRejectedError,

package/docs/human-in-the-loop.md

@@ -25,13 +25,14 @@ Human-in-the-loop (HITL) patterns allow agents to pause execution and wait for h
 
 Agents SDK supports multiple human-in-the-loop patterns. Choose based on your use case:
 
-| Use Case               | Pattern           | Best For                                           | Example                                                                                                      |
-| ---------------------- | ----------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Long-running workflows | Workflow Approval | Multi-step processes, durable approval gates       | [examples/workflows/](https://github.com/cloudflare/agents/tree/main/examples/workflows)                     |
-| AIChatAgent tools      | `needsApproval`   | Chat-based tool calls with `@cloudflare/ai-chat`   | [guides/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/guides/human-in-the-loop)         |
-| OpenAI Agents SDK      | `needsApproval`   | Using OpenAI's agent SDK with conditional approval | [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop) |
-| Client-side tools      | `onToolCall`      | Tools that need browser APIs or user interaction   | Pattern below                                                                                                |
-| MCP Servers            | Elicitation       | MCP tools requesting structured user input         | [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)         |
+| Use Case               | Pattern               | Best For                                           | Example                                                                                                        |
+| ---------------------- | --------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Long-running workflows | Workflow Approval     | Multi-step processes, durable approval gates       | [examples/workflows/](https://github.com/cloudflare/agents/tree/main/examples/workflows)                       |
+| AIChatAgent tools      | `needsApproval`       | Chat-based tool calls with `@cloudflare/ai-chat`   | [guides/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/guides/human-in-the-loop)           |
+| OpenAI Agents SDK      | `needsApproval`       | Using OpenAI's agent SDK with conditional approval | [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop)   |
+| Client-side tools      | `onToolCall`          | Tools that need browser APIs or user interaction   | Pattern below                                                                                                  |
+| Stateless servers      | Stateless Elicitation | Current MCP tools requesting structured input      | [examples/mcp-elicitation-mrtr/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation-mrtr) |
+| Legacy servers         | Legacy Elicitation    | Existing sessionful MCP deployments                | [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)           |
 
 ### Decision Guide
 
@@ -452,85 +453,64 @@ See the complete example: [openai-sdk/human-in-the-loop/](https://github.com/clo
 
 ### MCP Elicitation
 
-When building MCP servers with `McpAgent`, you can request additional user input during tool execution using **elicitation**. The MCP client (like Claude Desktop) renders a form based on your JSON Schema and returns the user's response.
+**Stateless Elicitation** uses multi-round-trip requests (MRTR). A handler returns `inputRequired(...)`; the client gathers the requested input and retries with SDK-managed state. No Worker remains suspended while the user responds.
 
 ```typescript
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { Agent } from "agents";
-
-export class MyMcpAgent extends Agent<Env, State> {
-  server = new McpServer({
-    name: "my-mcp-server",
-    version: "1.0.0"
-  });
-
-  onStart() {
-    this.server.registerTool(
-      "increase-counter",
-      {
-        description: "Increase the counter by a user-specified amount",
-        inputSchema: {
-          confirm: z.boolean().describe("Do you want to increase the counter?")
-        }
-      },
-      async ({ confirm }, extra) => {
-        if (!confirm) {
-          return { content: [{ type: "text", text: "Cancelled." }] };
-        }
-
-        // Request additional input from the user
-        const userInput = await this.server.server.elicitInput(
-          {
-            message: "By how much do you want to increase the counter?",
-            requestedSchema: {
-              type: "object",
-              properties: {
-                amount: {
-                  type: "number",
-                  title: "Amount",
-                  description: "The amount to increase the counter by"
-                }
-              },
-              required: ["amount"]
-            }
-          },
-          { relatedRequestId: extra.requestId }
-        );
-
-        // Check if user accepted or cancelled
-        if (userInput.action !== "accept" || !userInput.content) {
-          return { content: [{ type: "text", text: "Cancelled." }] };
-        }
+import {
+  McpServer,
+  acceptedContent,
+  inputRequired
+} from "@modelcontextprotocol/server";
+import { createMcpHandler } from "agents/mcp/server";
+import { z } from "zod";
 
-        // Use the input
-        const amount = Number(userInput.content.amount);
-        this.setState({
-          ...this.state,
-          counter: this.state.counter + amount
+function createServer() {
+  const server = new McpServer({ name: "my-server", version: "1.0.0" });
+  server.registerTool(
+    "ask-name",
+    { inputSchema: z.object({}) },
+    async (_args, context) => {
+      const answer = acceptedContent(
+        context.mcpReq.inputResponses,
+        "name",
+        z.object({ name: z.string() })
+      );
+      if (!answer) {
+        return inputRequired({
+          inputRequests: {
+            name: inputRequired.elicit({
+              message: "What is your name?",
+              requestedSchema: {
+                type: "object",
+                properties: { name: { type: "string" } },
+                required: ["name"]
+              }
+            })
+          }
         });
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Counter increased by ${amount}, now at ${this.state.counter}`
-            }
-          ]
-        };
       }
+      return { content: [{ type: "text", text: `Hello ${answer.name}` }] };
+    }
+  );
+  return server;
+}
+
+export default {
+  fetch(request, env, ctx) {
+    return createMcpHandler(createServer, { legacy: "reject" })(
+      request,
+      env,
+      ctx
     );
   }
-}
+} satisfies ExportedHandler;
 ```
 
-**Key differences from other patterns:**
+The MCP client renders the JSON Schema form and the original operation remains pending from the application's perspective while the SDK completes the rounds.
 
-- Used by **MCP servers** exposing tools to clients, not agents calling tools
-- Uses **JSON Schema** for structured form-based input
-- The **MCP client** (Claude Desktop, etc.) handles UI rendering
-- Returns `{ action: "accept" | "decline", content: {...} }`
+See the [Stateless Elicitation example](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation-mrtr).
 
-See the complete example: [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)
+**Legacy Elicitation** in existing Legacy deployments uses pushed `elicitation/create` requests over a stateful transport. See the explicitly legacy [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation) example when retaining `McpAgent` or `createLegacyMcpHandler` with `WorkerTransport`.
 
 ## State Patterns for Approvals
 
@@ -647,15 +627,16 @@ async submitForApproval(request: ApprovalRequest): Promise<string> {
 
 ## Complete Examples
 
-| Pattern           | Location                                                                                                     | Description                                        |
-| ----------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
-| Workflow approval | [examples/workflows/](https://github.com/cloudflare/agents/tree/main/examples/workflows)                     | Multi-step task processing with approval gate      |
-| AIChatAgent tools | [guides/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/guides/human-in-the-loop)         | Chat tool approval with needsApproval + onToolCall |
-| OpenAI Agents SDK | [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop) | Conditional tool approval with modal               |
-| MCP Elicitation   | [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)         | MCP server requesting structured user input        |
+| Pattern               | Location                                                                                                       | Description                                        |
+| --------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| Workflow approval     | [examples/workflows/](https://github.com/cloudflare/agents/tree/main/examples/workflows)                       | Multi-step task processing with approval gate      |
+| AIChatAgent tools     | [guides/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/guides/human-in-the-loop)           | Chat tool approval with needsApproval + onToolCall |
+| OpenAI Agents SDK     | [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop)   | Conditional tool approval with modal               |
+| Stateless Elicitation | [examples/mcp-elicitation-mrtr/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation-mrtr) | Stateless multi-round input                        |
+| Legacy Elicitation    | [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)           | Stateful pushed input requests                     |
 
 For detailed API documentation, see:
 
 - [Workflows](./workflows.md) - `waitForApproval()`, `approveWorkflow()`, `rejectWorkflow()`
-- [MCP Servers](./mcp-servers.md) - `elicitInput()` for MCP elicitation
+- [MCP Servers](./mcp-servers.md) - `inputRequired()` and legacy `elicitInput()`
 - [Callable Methods](./callable-methods.md) - `@callable()` decorator for approval endpoints

package/docs/mcp-client.md

@@ -15,6 +15,12 @@ The MCP client capability lets your agent:
 
 ## Quick Start
 
+Install the exact MCP client peer used by this Agents release:
+
+```sh
+pnpm add agents @modelcontextprotocol/client@2.0.0-beta.5
+```
+
 ```typescript
 import { Agent } from "agents";
 
@@ -95,6 +101,20 @@ await this.addMcpServer("internal", "https://internal-mcp.example.com/mcp", {
 });
 ```
 
+### Legacy OAuth metadata compatibility
+
+SDK v2 validates authorization-server metadata issuers by default. A trusted Legacy server with known mismatched RFC 8414 metadata can opt out explicitly:
+
+```typescript
+await this.addMcpServer("legacy", "https://legacy.example.com/mcp", {
+  transport: {
+    skipIssuerMetadataValidation: true
+  }
+});
+```
+
+This weakens OAuth mix-up protection. Do not enable it for unknown servers or as a general fallback.
+
 ### Retry Options
 
 Configure retry behavior for connection and reconnection attempts:
@@ -111,9 +131,13 @@ await this.addMcpServer("github", "https://mcp.github.com/mcp", {
 
 These options are persisted and used when reconnecting after hibernation or after OAuth completion. Default: 3 attempts, 500ms base delay, 5s max delay. See [Retries](./retries.md) for more details.
 
-### Elicitation
+### Protocol negotiation and elicitation
+
+Agents uses the MCP v2 client and automatically negotiates the protocol version for every connection. It uses `server/discover` with Stateless servers and falls back to the `initialize` handshake on the same connection for Legacy Streamable HTTP, SSE, and RPC servers.
 
-MCP servers can request input from the client during a tool call (`elicitation/create`). To respond, configure an elicitation handler before MCP connections are registered or restored:
+MCP servers can request input from the client during `callTool`, `getPrompt`, or `readResource`. Stateless Elicitation returns an `input_required` result and completes through MRTR: the MCP SDK invokes the configured `elicitation/create` handler, sends its response, and continues the original request. Agents does not expose an intermediate continuation; the original call stays pending while human input is collected and eventually resolves to the ordinary tool, prompt, or resource result. Legacy Elicitation on Legacy servers continues to use pushed `elicitation/create` requests. Both generations share the same handlers.
+
+Configure elicitation handlers before MCP connections are registered or restored:
 
 ```typescript
 import { Agent } from "agents";
@@ -136,6 +160,8 @@ class MyAgent extends Agent<Env> {
 
 The advertised modes are persisted with each MCP server, so a connection restored from storage after hibernation re-advertises the same modes at the handshake; the handlers themselves re-attach when `onStart()` runs. Configuring a handler after an MCP connection is already active updates the in-memory handler, but the server only sees new advertised elicitation modes after that connection reconnects.
 
+Handlers and pending calls are memory-only. A Durable Object hibernation or isolate restart does not preserve an in-flight interactive call; callers must retry it after the connection is restored. Agents intentionally does not persist in-flight Stateless `requestState` or implement a manual/resumable continuation layer.
+
 Connections advertise only the elicitation modes with configured handlers at the `initialize` handshake: configure `form` to advertise form-mode elicitation, `url` to advertise url-mode elicitation (MCP spec 2025-11-25 — url mode is used for sensitive flows like OAuth URLs), or both to advertise both modes. Without handlers, connections advertise no elicitation capability, so spec-compliant servers use their non-elicitation fallbacks instead of sending requests the agent cannot answer.
 
 To override the advertised modes, declare them explicitly — an explicit declaration always wins and is persisted with the server options, surviving hibernation:
@@ -416,7 +442,7 @@ function Dashboard() {
     onMcpUpdate: (mcpState) => {
       setTools(mcpState.tools);
       setServers(mcpState.servers);
-    }
+    },
   });
 
   return (
@@ -429,10 +455,8 @@ function Dashboard() {
       ))}
 
       <h2>Available Tools ({tools.length})</h2>
-      {tools.map(tool => (
-        <div key={`${tool.serverId}-${tool.name}`}>
-          {tool.name}
-        </div>
+      {tools.map((tool) => (
+        <div key={`${tool.serverId}-${tool.name}`}>{tool.name}</div>
       ))}
     </div>
   );