Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(x402-mcp): drop the invalid stdio transport from bazaar discovery rows and prove the mcp:// URL interops

nirholas6ef382f3182d
diff --git a/examples/paid-mcp-server/src/payments.js b/examples/paid-mcp-server/src/payments.js
index 4e952761c..3d594fe3f 100644
--- a/examples/paid-mcp-server/src/payments.js
+++ b/examples/paid-mcp-server/src/payments.js
@@ -126,7 +126,11 @@ export function paid(config, handler) {
const discovery = declareDiscoveryExtension({
toolName,
description,
- transport: 'stdio',
+ // No `transport`: the bazaar discovery spec only accepts
+ // "streamable-http" and "sse" there, so declaring "stdio" made every
+ // row fail validateDiscoveryExtensionSpec and get dropped by an
+ // indexer. The field is optional, and a stdio server has no valid
+ // value for it, so it is left off.
inputSchema,
example,
});
diff --git a/mcp-server/src/payments.js b/mcp-server/src/payments.js
index df502c548..91b1eb003 100644
--- a/mcp-server/src/payments.js
+++ b/mcp-server/src/payments.js
@@ -289,7 +289,11 @@ export function paid(cfg, handler) {
const bazaar = declareDiscoveryExtension({
toolName,
description,
- transport: 'stdio',
+ // No `transport`: the bazaar discovery spec only accepts
+ // "streamable-http" and "sse" there, so declaring "stdio" made every
+ // row fail validateDiscoveryExtensionSpec and get dropped by an
+ // indexer. The field is optional, and a stdio server has no valid
+ // value for it, so it is left off.
inputSchema,
example,
output: outputExample ? { example: outputExample } : undefined,
diff --git a/packages/ibm-x402-mcp/src/payments.js b/packages/ibm-x402-mcp/src/payments.js
index 0289a2e7d..f16f6f9ed 100644
--- a/packages/ibm-x402-mcp/src/payments.js
+++ b/packages/ibm-x402-mcp/src/payments.js
@@ -136,7 +136,11 @@ export function paid(cfg, handler) {
const bazaar = declareDiscoveryExtension({
toolName,
description,
- transport: 'stdio',
+ // No `transport`: the bazaar discovery spec only accepts
+ // "streamable-http" and "sse" there, so declaring "stdio" made every
+ // row fail validateDiscoveryExtensionSpec and get dropped by an
+ // indexer. The field is optional, and a stdio server has no valid
+ // value for it, so it is left off.
inputSchema,
example,
output: outputExample ? { example: outputExample } : undefined,
diff --git a/packages/ibm-x402-mcp/test/payments.test.mjs b/packages/ibm-x402-mcp/test/payments.test.mjs
index 081bcb73f..e2c7eb83e 100644
--- a/packages/ibm-x402-mcp/test/payments.test.mjs
+++ b/packages/ibm-x402-mcp/test/payments.test.mjs
@@ -108,7 +108,10 @@ test('calling a paid tool without payment returns the x402 PaymentRequired envel
assert.ok(bazaar, 'bazaar discovery extension present');
assert.equal(bazaar.type, 'mcp');
assert.equal(bazaar.toolName, 'ibm_granite_chat');
- assert.equal(bazaar.transport, 'stdio');
+ // No transport is declared: the bazaar spec's only legal values are
+ // "streamable-http" and "sse", so a stdio server omits the optional field
+ // rather than emitting a value an indexer rejects.
+ assert.equal(bazaar.transport, undefined);
assert.equal(bazaar.inputSchema.type, 'object');
assert.ok(bazaar.inputSchema.properties.messages, 'input schema rides in discovery');
diff --git a/scripts/x402-bazaar-mcp-url-repro.mjs b/scripts/x402-bazaar-mcp-url-repro.mjs
new file mode 100644
index 000000000..1922ef66b
--- /dev/null
+++ b/scripts/x402-bazaar-mcp-url-repro.mjs
@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// Minimal reproduction of an upstream x402 defect, kept runnable so the report
+// filed against x402-foundation/x402 can be re-checked against any new release.
+//
+// The defect, in one sentence: @x402/mcp mints `mcp://tool/<name>` resource URLs
+// for MCP tools, and @x402/extensions' bazaar discovery cannot canonicalize
+// them, so every MCP tool row a bazaar indexer ingests is keyed on the literal
+// string "null".
+//
+// Why: `extractDiscoveryInfo` builds its canonical URL as `${url.origin}${url.pathname}`.
+// `mcp:` is not a WHATWG "special" scheme, so `new URL('mcp://tool/x').origin`
+// is the string "null" and the host lands in the pathname. The two packages ship
+// from the same monorepo, so the producer and the consumer disagree about a URL
+// neither side treats as invalid.
+//
+// three.ws is unaffected in settlement: the official auto-pay client pays these
+// tools correctly (verified against our stdio server). Only bazaar discovery
+// rows are corrupted, which is why this is filed rather than worked around.
+//
+// Run: node scripts/x402-bazaar-mcp-url-repro.mjs (exit 1 while the bug is live)
+
+import { createToolResourceUrl } from '@x402/mcp';
+import { declareDiscoveryExtension, extractDiscoveryInfo } from '@x402/extensions/bazaar';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const versions = {
+ '@x402/mcp': require('@x402/mcp/package.json').version,
+ '@x402/extensions': require('@x402/extensions/package.json').version,
+ node: process.version,
+};
+console.log('versions:', JSON.stringify(versions));
+
+const toolName = 'example_paid_tool';
+const resourceUrl = createToolResourceUrl(toolName);
+console.log(`createToolResourceUrl(${JSON.stringify(toolName)}) -> ${resourceUrl}`);
+console.log(`new URL(resourceUrl).origin -> ${JSON.stringify(new URL(resourceUrl).origin)}`);
+
+const paymentRequired = {
+ x402Version: 2,
+ error: 'Payment required to access this tool',
+ resource: { url: resourceUrl, description: 'An example paid MCP tool.', mimeType: 'application/json' },
+ accepts: [],
+ extensions: declareDiscoveryExtension({
+ toolName,
+ description: 'An example paid MCP tool.',
+ inputSchema: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] },
+ }),
+};
+
+const info = extractDiscoveryInfo(paymentRequired, undefined);
+const canonical = info?.resourceUrl;
+console.log(`extractDiscoveryInfo(...).resourceUrl -> ${JSON.stringify(canonical)}`);
+
+const expected = `mcp://tool/${toolName}`;
+if (canonical === expected) {
+ console.log('\nFIXED: the canonical discovery URL now round-trips the mcp:// resource.');
+ process.exit(0);
+}
+console.error(
+ `\nBUG: expected the canonical URL to round-trip ${JSON.stringify(expected)}, got ` +
+ `${JSON.stringify(canonical)}. Every MCP row an indexer keys on this URL collides on "null".`,
+);
+process.exit(1);
diff --git a/scripts/x402-mcp-url-interop-check.mjs b/scripts/x402-mcp-url-interop-check.mjs
new file mode 100644
index 000000000..d1204b49b
--- /dev/null
+++ b/scripts/x402-mcp-url-interop-check.mjs
@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Does the official x402 MCP auto-pay client accept an `mcp://tool/<name>`
+ * resource URL?
+ *
+ * The store-submission tracker carried a long-standing claim that it does not,
+ * and that claim blocked the agent-commerce listing (prompt 08) on a supposed
+ * upstream interop defect. This script settles the question by running the real
+ * loop instead of reading the source: an in-memory MCP server whose paid tool is
+ * wrapped by `@x402/mcp`'s own `createPaymentWrapper` with the resource URL that
+ * `@x402/mcp`'s own `createToolResourceUrl()` mints, and an `x402MCPClient` with
+ * auto-payment on and a real Solana `exact` scheme signer.
+ *
+ * Run it from the repo root:
+ *
+ * node scripts/x402-mcp-url-interop-check.mjs
+ *
+ * The buyer keypair is generated fresh and is deliberately unfunded, so the
+ * settlement leg is expected to end in `transaction_simulation_failed`. That is
+ * the pass condition, not a failure: reaching simulation proves the client
+ * accepted the `mcp://` URL, selected the requirements, signed a payment and put
+ * it on the wire. A URL rejection would instead throw before any signing, and
+ * `paymentMade` would be false.
+ *
+ * Exit code 0 means the `mcp://` path is interoperable. Exit code 1 means the
+ * defect has reappeared and the details are printed above it.
+ *
+ * Requires network access to the facilitator. No wallet, key or funds needed.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { HTTPFacilitatorClient, x402ResourceServer } from '@x402/core/server';
+import { x402Client } from '@x402/core/client';
+import { createPaymentWrapper, createToolResourceUrl, wrapMCPClientWithPayment } from '@x402/mcp';
+import { registerExactSvmScheme as registerServerSvm } from '@x402/svm/exact/server';
+import { registerExactSvmScheme as registerClientSvm } from '@x402/svm/exact/client';
+import { generateKeyPairSigner } from '@solana/kit';
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+
+const NETWORK_SOLANA_MAINNET = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
+const SOLANA_USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+const DEFAULT_FEE_PAYER = 'PayeRNCipcerPHCsYMTrX9pAYDm1LnPGzgb66NUDG5a';
+const DEFAULT_FACILITATOR = 'https://facilitator.payai.network';
+// Sales settle to the platform Solana address; this check never moves funds.
+const PAY_TO = process.env.X402_PAY_TO_SOLANA || 'wwwwwDxFWRn7grgr3Esrsg5C6NvDoDHSA4gaCffccrU';
+
+// These packages do not export `./package.json`, so read the installed manifest
+// off disk rather than resolving it through the module graph.
+function versionOf(pkg) {
+ try {
+ return JSON.parse(readFileSync(new URL(`../node_modules/${pkg}/package.json`, import.meta.url), 'utf8')).version;
+ } catch {
+ return 'unknown';
+ }
+}
+
+async function main() {
+ for (const pkg of ['@x402/mcp', '@x402/core', '@x402/svm']) {
+ console.log(`[versions] ${pkg} ${versionOf(pkg)}`);
+ }
+
+ const facilitator = new HTTPFacilitatorClient({
+ url: process.env.X402_FACILITATOR_URL || DEFAULT_FACILITATOR,
+ });
+ const resourceServer = new x402ResourceServer([facilitator]);
+ registerServerSvm(resourceServer, {});
+ await resourceServer.initialize();
+ console.log('[server] facilitator initialize: ok');
+
+ const resourceUrl = createToolResourceUrl('demo_paid');
+ console.log(`[server] createToolResourceUrl() minted: ${resourceUrl}`);
+ if (!resourceUrl.startsWith('mcp://')) {
+ console.error('[fail] upstream no longer mints an mcp:// URL; this check needs updating.');
+ return 1;
+ }
+
+ const accepts = await resourceServer.buildPaymentRequirementsFromOptions(
+ [
+ {
+ scheme: 'exact',
+ network: NETWORK_SOLANA_MAINNET,
+ payTo: PAY_TO,
+ price: '$0.001',
+ maxTimeoutSeconds: 60,
+ extra: {
+ name: 'USDC',
+ decimals: 6,
+ asset: SOLANA_USDC,
+ feePayer: DEFAULT_FEE_PAYER,
+ },
+ },
+ ],
+ { resourceUrl },
+ );
+
+ const paid = createPaymentWrapper(resourceServer, {
+ accepts,
+ resource: { url: resourceUrl, description: 'interop check', mimeType: 'application/json' },
+ });
+
+ const server = new McpServer({ name: 'x402-mcp-url-interop-check', version: '1.0.0' });
+ server.registerTool(
+ 'demo_paid',
+ { description: 'Paid tool used only by this interop check.', inputSchema: { q: z.string().optional() } },
+ paid(async () => ({ content: [{ type: 'text', text: 'paid content' }] })),
+ );
+
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+
+ const signer = await generateKeyPairSigner();
+ console.log(`[client] unfunded buyer: ${signer.address}`);
+ const paymentClient = new x402Client();
+ registerClientSvm(paymentClient, { signer });
+
+ const client = wrapMCPClientWithPayment(new Client({ name: 'interop-check', version: '1.0.0' }), paymentClient, {
+ autoPayment: true,
+ });
+ await client.connect(clientTransport);
+
+ let result;
+ try {
+ result = await client.callTool('demo_paid', { q: 'interop' }, { timeout: 90_000 });
+ } catch (err) {
+ console.error(`[fail] auto-pay threw before settlement: ${err.message}`);
+ console.error(' An mcp:// URL rejection looks exactly like this. Capture it and file upstream.');
+ return 1;
+ }
+
+ if (!result.paymentMade) {
+ console.error('[fail] the client never produced a payment for the mcp:// resource URL.');
+ return 1;
+ }
+
+ const body = JSON.stringify(result.content);
+ console.log(`[client] paymentMade=${result.paymentMade} isError=${result.isError}`);
+ console.log(`[client] server replied: ${body.slice(0, 200)}`);
+ if (body.includes('mcp://tool/demo_paid')) {
+ console.log('[ok] the mcp:// resource URL survived the whole round trip.');
+ }
+ console.log('[pass] the mcp:// tool URL is interoperable: the client signed and submitted a payment.');
+ console.log(' A settlement failure from the unfunded buyer is expected and is not an interop defect.');
+ return 0;
+}
+
+process.exitCode = await main();