feat(mcp): graduate MCP proxy to stable, fix schema proxying and notification forwarding

- Switch from McpServer to low-level Server to proxy raw JSON schemas verbatim without Zod conversion
- Forward all MCP content types (image, audio, resource_link) not just text
- Forward blob resource contents instead of silently dropping them
- Subscribe to remote tools/resources list_changed notifications and forward to local clients
- Consolidate dynamic imports, add debug logging for resource availability
- Remove alpha label and runtime warning

Author: tenequm

packages/x402-proxy/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-03-16
+
+### Changed
+- MCP proxy graduated from alpha to stable - removed alpha warning and label
+- MCP proxy uses low-level `Server` class instead of `McpServer` to proxy raw JSON schemas verbatim without Zod conversion
+- MCP proxy now forwards blob resource contents (previously only text was proxied)
+- MCP content type widened to pass through all MCP content types (image, audio, resource_link) not just text
+
+### Added
+- MCP proxy forwards `notifications/tools/list_changed` and `notifications/resources/list_changed` from remote servers so local clients stay in sync with dynamic tool/resource updates
+
 ## [0.4.2] - 2026-03-16
 
 ### Fixed
@@ -105,7 +116,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - CLI binary accessible via `npx x402-proxy`
 - `fetch` command (default) - curl-like HTTP client with automatic x402 payment
-- `mcp` command (alpha) - MCP stdio proxy with auto-payment for AI agents
+- `mcp` command - MCP stdio proxy with auto-payment for AI agents
 - `setup` command - interactive onboarding wizard with @clack/prompts
 - `status` command - config, wallet, and spend summary
 - `wallet` subcommand with `info`, `history`, `fund`, `export-key`
@@ -129,7 +140,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `appendHistory` / `readHistory` / `calcSpend` - JSONL transaction history
 - Re-exports from `@x402/fetch`, `@x402/svm`, `@x402/evm`
 
-[Unreleased]: https://github.com/cascade-protocol/x402-proxy/compare/v0.4.2...HEAD
+[Unreleased]: https://github.com/cascade-protocol/x402-proxy/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/cascade-protocol/x402-proxy/compare/v0.4.2...v0.5.0
 [0.4.2]: https://github.com/cascade-protocol/x402-proxy/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/cascade-protocol/x402-proxy/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/cascade-protocol/x402-proxy/compare/v0.3.2...v0.4.0

packages/x402-proxy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-proxy",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "curl for x402 paid APIs. Auto-pays any endpoint on Base and Solana.",
   "type": "module",
   "sideEffects": false,

packages/x402-proxy/src/commands/mcp.ts

@@ -14,7 +14,7 @@ type McpFlags = {
 
 export const mcpCommand = buildCommand<McpFlags, [remoteUrl: string], CommandContext>({
   docs: {
-    brief: "Start MCP stdio proxy with x402 payment (alpha)",
+    brief: "Start MCP stdio proxy with x402 payment",
     fullDescription: `Start an MCP stdio proxy with automatic x402 payment for AI agents.
 
 Add to your MCP client config (Claude, Cursor, etc.):
@@ -67,7 +67,6 @@ Add to your MCP client config (Claude, Cursor, etc.):
       process.exit(1);
     }
 
-    warn("Note: MCP proxy is alpha - please report issues.");
     dim(`x402-proxy MCP proxy -> ${remoteUrl}`);
     if (wallet.evmAddress) dim(`  EVM:    ${wallet.evmAddress}`);
     if (wallet.solanaAddress) dim(`  Solana: ${wallet.solanaAddress}`);
@@ -104,7 +103,7 @@ Add to your MCP client config (Claude, Cursor, etc.):
     const { StreamableHTTPClientTransport } = await import(
       "@modelcontextprotocol/sdk/client/streamableHttp.js"
     );
-    const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+    const { Server } = await import("@modelcontextprotocol/sdk/server/index.js");
     const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
     const { x402MCPClient } = await import("@x402/mcp");
 
@@ -169,62 +168,96 @@ Add to your MCP client config (Claude, Cursor, etc.):
       }
     }
 
-    // Get remote tools to register on the local server
-    const { tools } = await x402Mcp.listTools();
+    // Discover remote capabilities
+    let { tools } = await x402Mcp.listTools();
     dim(`  ${tools.length} tools available`);
 
-    // Create local MCP server (stdio)
-    const localServer = new McpServer({
-      name: "x402-proxy",
-      version: __VERSION__,
-    });
+    let remoteResources: Array<{
+      name: string;
+      uri: string;
+      description?: string;
+      mimeType?: string;
+    }> = [];
+    try {
+      const res = await x402Mcp.listResources();
+      remoteResources = res.resources;
+      if (remoteResources.length > 0) dim(`  ${remoteResources.length} resources available`);
+    } catch {
+      dim("  Resources not available from remote");
+    }
 
-    // Register each remote tool as a local tool that proxies through x402
-    for (const tool of tools) {
-      localServer.tool(
-        tool.name,
-        tool.description ?? "",
-        tool.inputSchema?.properties
-          ? Object.fromEntries(
-              Object.entries(tool.inputSchema.properties as Record<string, unknown>).map(
-                ([k, v]) => [k, v as object],
-              ),
-            )
-          : {},
-        async (args) => {
-          const result = await x402Mcp.callTool(tool.name, args);
-          return {
-            content: result.content as Array<{ type: "text"; text: string }>,
-            isError: result.isError,
-          };
+    // Create local server using low-level Server (not McpServer) to proxy
+    // raw JSON Schemas verbatim without Zod conversion
+    const localServer = new Server(
+      { name: "x402-proxy", version: __VERSION__ },
+      {
+        capabilities: {
+          tools: tools.length > 0 ? {} : undefined,
+          resources: remoteResources.length > 0 ? {} : undefined,
         },
-      );
+      },
+    );
+
+    const {
+      ListToolsRequestSchema,
+      CallToolRequestSchema,
+      ListResourcesRequestSchema,
+      ReadResourceRequestSchema,
+      ToolListChangedNotificationSchema,
+      ResourceListChangedNotificationSchema,
+    } = await import("@modelcontextprotocol/sdk/types.js");
+
+    localServer.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+        annotations: t.annotations,
+      })),
+    }));
+
+    localServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      const result = await x402Mcp.callTool(name, args ?? {});
+      return {
+        content: result.content as Array<{ type: string; [key: string]: unknown }>,
+        isError: result.isError,
+      };
+    });
+
+    if (remoteResources.length > 0) {
+      localServer.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: remoteResources.map((r) => ({
+          name: r.name,
+          uri: r.uri,
+          description: r.description,
+          mimeType: r.mimeType,
+        })),
+      }));
+
+      localServer.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const result = await x402Mcp.readResource({ uri: request.params.uri });
+        return {
+          contents: result.contents.map((c) => ({ ...c })),
+        };
+      });
     }
 
-    // Also proxy resources if available
-    try {
-      const { resources } = await x402Mcp.listResources();
-      if (resources.length > 0) {
-        dim(`  ${resources.length} resources available`);
-        for (const resource of resources) {
-          localServer.resource(
-            resource.name,
-            resource.uri,
-            resource.description ? { description: resource.description } : {},
-            async (uri) => {
-              const result = await x402Mcp.readResource({ uri: uri.href });
-              return {
-                contents: result.contents.map((c) => ({
-                  uri: c.uri,
-                  text: "text" in c ? (c.text as string) : "",
-                })),
-              };
-            },
-          );
-        }
-      }
-    } catch {
-      // Resources not supported by remote, that's fine
+    // Forward remote list-change notifications so local clients stay in sync
+    remoteClient.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+      const updated = await x402Mcp.listTools();
+      tools = updated.tools;
+      dim(`  Tools updated: ${tools.length} available`);
+      await localServer.notification({ method: "notifications/tools/list_changed" });
+    });
+
+    if (remoteResources.length > 0) {
+      remoteClient.setNotificationHandler(ResourceListChangedNotificationSchema, async () => {
+        const updated = await x402Mcp.listResources();
+        remoteResources = updated.resources;
+        dim(`  Resources updated: ${remoteResources.length} available`);
+        await localServer.notification({ method: "notifications/resources/list_changed" });
+      });
     }
 
     // Connect local server to stdio