feat: add MCP server for Claude Code / Codex / MCP-compatible agents

README.md

@@ -163,7 +163,28 @@ Example transaction: [`5c898eb4...`](https://stellar.expert/explorer/testnet/tx/
 
 ## Using the Service
 
-Any x402-compatible agent can use RenderGate with just the URL. No API keys, no accounts, no setup.
+### Option 1: MCP Tool (Claude Code, Codex, any MCP-compatible agent)
+
+Add to your MCP config (`.mcp.json` or Claude Code settings):
+
+```json
+{
+  "mcpServers": {
+    "rendergate": {
+      "command": "node",
+      "args": ["/path/to/rendergate/mcp-server.js"],
+      "env": {
+        "STELLAR_PRIVATE_KEY": "S...your_testnet_secret_key...",
+        "RENDERGATE_URL": "https://tantk-rendergate.hf.space"
+      }
+    }
+  }
+}
+```
+
+Then the agent can simply call `render_page("https://x.com/stellarorg")` — payment happens transparently.
+
+### Option 2: x402 Fetch (any Node.js agent)
 
 ```javascript
 import { wrapFetchWithPayment } from "@x402/fetch";
@@ -176,14 +197,14 @@ const data = await response.json();
 // { title: "Stellar (@StellarOrg) / X", content: "9,913 posts...", ... }
 ```
 
-That's it. The agent just needs:
+The agent just needs:
 - `@x402/fetch` + `@x402/stellar` (npm packages)
 - A Stellar wallet with USDC
 - Our URL
 
-## Try It
+### Try It
 
-`demo-client.js` is included to test the service end-to-end. It walks through the x402 payment flow step by step.
+`demo-client.js` is included to test the service end-to-end:
 
 ```bash
 npm install

mcp-server.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { Transaction, TransactionBuilder } from "@stellar/stellar-sdk";
+import { x402Client, x402HTTPClient } from "@x402/fetch";
+import { createEd25519Signer, getNetworkPassphrase } from "@x402/stellar";
+import { ExactStellarScheme } from "@x402/stellar/exact/client";
+
+const STELLAR_PRIVATE_KEY = process.env.STELLAR_PRIVATE_KEY;
+const SERVER_URL = process.env.RENDERGATE_URL || "https://tantk-rendergate.hf.space";
+const NETWORK = "stellar:testnet";
+const STELLAR_RPC_URL = "https://soroban-testnet.stellar.org";
+
+// Setup x402 payment client
+let httpClient = null;
+let client = null;
+
+function getPaymentClient() {
+  if (!client && STELLAR_PRIVATE_KEY) {
+    const signer = createEd25519Signer(STELLAR_PRIVATE_KEY, NETWORK);
+    client = new x402Client().register(
+      "stellar:*",
+      new ExactStellarScheme(signer, { url: STELLAR_RPC_URL }),
+    );
+    httpClient = new x402HTTPClient(client);
+  }
+  return { client, httpClient };
+}
+
+async function paidRender(url) {
+  const { client, httpClient } = getPaymentClient();
+  if (!client) {
+    throw new Error("STELLAR_PRIVATE_KEY not set — cannot make x402 payments");
+  }
+
+  const renderEndpoint = `${SERVER_URL}/render?url=${encodeURIComponent(url)}`;
+
+  // Step 1: Get 402 response
+  const firstTry = await fetch(renderEndpoint);
+  if (firstTry.status !== 402) {
+    return await firstTry.json();
+  }
+
+  // Step 2: Create payment
+  const paymentRequired = httpClient.getPaymentRequiredResponse((name) =>
+    firstTry.headers.get(name),
+  );
+
+  let paymentPayload = await client.createPaymentPayload(paymentRequired);
+  const networkPassphrase = getNetworkPassphrase(NETWORK);
+  const tx = new Transaction(
+    paymentPayload.payload.transaction,
+    networkPassphrase,
+  );
+  const sorobanData = tx.toEnvelope().v1()?.tx()?.ext()?.sorobanData();
+  if (sorobanData) {
+    paymentPayload = {
+      ...paymentPayload,
+      payload: {
+        ...paymentPayload.payload,
+        transaction: TransactionBuilder.cloneFrom(tx, {
+          fee: "1",
+          sorobanData,
+          networkPassphrase,
+        })
+          .build()
+          .toXDR(),
+      },
+    };
+  }
+
+  // Step 3: Send paid request
+  const headers = httpClient.encodePaymentSignatureHeader(paymentPayload);
+  const resp = await fetch(renderEndpoint, { method: "GET", headers });
+
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(`Render failed (${resp.status}): ${text}`);
+  }
+
+  return await resp.json();
+}
+
+// Create MCP server
+const server = new McpServer({
+  name: "rendergate",
+  version: "1.0.0",
+});
+
+server.tool(
+  "render_page",
+  "Render a JavaScript-heavy webpage using a headless browser. Pays $0.001 USDC on Stellar per request via x402. Use this when standard HTTP fetch returns empty content from SPAs, Twitter/X, LinkedIn, DeFi apps, or Cloudflare-protected sites.",
+  {
+    url: z.string().url().describe("The URL to render (must be public http/https)"),
+  },
+  async ({ url }) => {
+    try {
+      const result = await paidRender(url);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `# ${result.title}\n\nURL: ${result.url}\nRendered: ${result.renderedAt}\nRender time: ${result.renderTimeMs}ms\nPayment: ${result.payment?.price} on ${result.payment?.network}\n\n${result.content}`,
+          },
+        ],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+        isError: true,
+      };
+    }
+  },
+);
+
+// Start
+const transport = new StdioServerTransport();
+await server.connect(transport);

package-lock.json

@@ -7,8 +7,9 @@
     "": {
       "name": "rendergate",
       "version": "1.0.0",
-      "license": "ISC",
+      "license": "MIT",
       "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.29.0",
         "@stellar/stellar-sdk": "^15.0.1",
         "@x402/core": "^2.9.0",
         "@x402/express": "^2.9.0",
@@ -26,6 +27,79 @@
       "license": "MIT",
       "peer": true
     },
+    "node_modules/@hono/node-server": {
+      "version": "1.19.14",
+      "resolved": "https://registry.npmmirror.com/@hono/node-server/-/node-server-1.19.14.tgz",
+      "integrity": "sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.14.1"
+      },
+      "peerDependencies": {
+        "hono": "^4"
+      }
+    },
+    "node_modules/@modelcontextprotocol/sdk": {
+      "version": "1.29.0",
+      "resolved": "https://registry.npmmirror.com/@modelcontextprotocol/sdk/-/sdk-1.29.0.tgz",
+      "integrity": "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@hono/node-server": "^1.19.9",
+        "ajv": "^8.17.1",
+        "ajv-formats": "^3.0.1",
+        "content-type": "^1.0.5",
+        "cors": "^2.8.5",
+        "cross-spawn": "^7.0.5",
+        "eventsource": "^3.0.2",
+        "eventsource-parser": "^3.0.0",
+        "express": "^5.2.1",
+        "express-rate-limit": "^8.2.1",
+        "hono": "^4.11.4",
+        "jose": "^6.1.3",
+        "json-schema-typed": "^8.0.2",
+        "pkce-challenge": "^5.0.0",
+        "raw-body": "^3.0.0",
+        "zod": "^3.25 || ^4.0",
+        "zod-to-json-schema": "^3.25.1"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@cfworker/json-schema": "^4.1.1",
+        "zod": "^3.25 || ^4.0"
+      },
+      "peerDependenciesMeta": {
+        "@cfworker/json-schema": {
+          "optional": true
+        },
+        "zod": {
+          "optional": false
+        }
+      }
+    },
+    "node_modules/@modelcontextprotocol/sdk/node_modules/eventsource": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmmirror.com/eventsource/-/eventsource-3.0.7.tgz",
+      "integrity": "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==",
+      "license": "MIT",
+      "dependencies": {
+        "eventsource-parser": "^3.0.1"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/@modelcontextprotocol/sdk/node_modules/jose": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmmirror.com/jose/-/jose-6.2.2.tgz",
+      "integrity": "sha512-d7kPDd34KO/YnzaDOlikGpOurfF0ByC2sEV4cANCtdqLlTfBlw2p14O/5d/zv40gJPbIQxfES3nSx1/oYNyuZQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/panva"
+      }
+    },
     "node_modules/@noble/ciphers": {
       "version": "1.3.0",
       "resolved": "https://registry.npmmirror.com/@noble/ciphers/-/ciphers-1.3.0.tgz",
@@ -375,6 +449,23 @@
         "url": "https://github.com/sponsors/epoberezkin"
       }
     },
+    "node_modules/ajv-formats": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmmirror.com/ajv-formats/-/ajv-formats-3.0.1.tgz",
+      "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==",
+      "license": "MIT",
+      "dependencies": {
+        "ajv": "^8.0.0"
+      },
+      "peerDependencies": {
+        "ajv": "^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "ajv": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/apg-js": {
       "version": "4.4.0",
       "resolved": "https://registry.npmmirror.com/apg-js/-/apg-js-4.4.0.tgz",
@@ -616,6 +707,37 @@
         "node": ">=6.6.0"
       }
     },
+    "node_modules/cors": {
+      "version": "2.8.6",
+      "resolved": "https://registry.npmmirror.com/cors/-/cors-2.8.6.tgz",
+      "integrity": "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==",
+      "license": "MIT",
+      "dependencies": {
+        "object-assign": "^4",
+        "vary": "^1"
+      },
+      "engines": {
+        "node": ">= 0.10"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/cross-spawn": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmmirror.com/cross-spawn/-/cross-spawn-7.0.6.tgz",
+      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+      "license": "MIT",
+      "dependencies": {
+        "path-key": "^3.1.0",
+        "shebang-command": "^2.0.0",
+        "which": "^2.0.1"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
     "node_modules/debug": {
       "version": "4.4.3",
       "resolved": "https://registry.npmmirror.com/debug/-/debug-4.4.3.tgz",
@@ -839,6 +961,15 @@
         "node": ">=12.0.0"
       }
     },
+    "node_modules/eventsource-parser": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmmirror.com/eventsource-parser/-/eventsource-parser-3.0.6.tgz",
+      "integrity": "sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
     "node_modules/express": {
       "version": "5.2.1",
       "resolved": "https://registry.npmmirror.com/express/-/express-5.2.1.tgz",
@@ -882,6 +1013,24 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/express-rate-limit": {
+      "version": "8.3.2",
+      "resolved": "https://registry.npmmirror.com/express-rate-limit/-/express-rate-limit-8.3.2.tgz",
+      "integrity": "sha512-77VmFeJkO0/rvimEDuUC5H30oqUC4EyOhyGccfqoLebB0oiEYfM7nwPrsDsBL1gsTpwfzX8SFy2MT3TDyRq+bg==",
+      "license": "MIT",
+      "dependencies": {
+        "ip-address": "10.1.0"
+      },
+      "engines": {
+        "node": ">= 16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/express-rate-limit"
+      },
+      "peerDependencies": {
+        "express": ">= 4.11"
+      }
+    },
     "node_modules/fast-deep-equal": {
       "version": "3.1.3",
       "resolved": "https://registry.npmmirror.com/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
@@ -1147,6 +1296,15 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/hono": {
+      "version": "4.12.12",
+      "resolved": "https://registry.npmmirror.com/hono/-/hono-4.12.12.tgz",
+      "integrity": "sha512-p1JfQMKaceuCbpJKAPKVqyqviZdS0eUxH9v82oWo1kb9xjQ5wA6iP3FNVAPDFlz5/p7d45lO+BpSk1tuSZMF4Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=16.9.0"
+      }
+    },
     "node_modules/http-errors": {
       "version": "2.0.1",
       "resolved": "https://registry.npmmirror.com/http-errors/-/http-errors-2.0.1.tgz",
@@ -1209,6 +1367,15 @@
       "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
       "license": "ISC"
     },
+    "node_modules/ip-address": {
+      "version": "10.1.0",
+      "resolved": "https://registry.npmmirror.com/ip-address/-/ip-address-10.1.0.tgz",
+      "integrity": "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
     "node_modules/ipaddr.js": {
       "version": "1.9.1",
       "resolved": "https://registry.npmmirror.com/ipaddr.js/-/ipaddr.js-1.9.1.tgz",
@@ -1269,6 +1436,12 @@
       "integrity": "sha512-xHjhDr3cNBK0BzdUJSPXZntQUx/mwMS5Rw4A7lPJ90XGAO6ISP/ePDNuo0vhqOZU+UD5JoodwCAAoZQd3FeAKw==",
       "license": "MIT"
     },
+    "node_modules/isexe": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmmirror.com/isexe/-/isexe-2.0.0.tgz",
+      "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+      "license": "ISC"
+    },
     "node_modules/isows": {
       "version": "1.0.7",
       "resolved": "https://registry.npmmirror.com/isows/-/isows-1.0.7.tgz",
@@ -1299,6 +1472,12 @@
       "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
       "license": "MIT"
     },
+    "node_modules/json-schema-typed": {
+      "version": "8.0.2",
+      "resolved": "https://registry.npmmirror.com/json-schema-typed/-/json-schema-typed-8.0.2.tgz",
+      "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==",
+      "license": "BSD-2-Clause"
+    },
     "node_modules/math-intrinsics": {
       "version": "1.1.0",
       "resolved": "https://registry.npmmirror.com/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
@@ -1369,6 +1548,15 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/object-assign": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmmirror.com/object-assign/-/object-assign-4.1.1.tgz",
+      "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/object-inspect": {
       "version": "1.13.4",
       "resolved": "https://registry.npmmirror.com/object-inspect/-/object-inspect-1.13.4.tgz",
@@ -1462,6 +1650,15 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/path-key": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmmirror.com/path-key/-/path-key-3.1.1.tgz",
+      "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/path-to-regexp": {
       "version": "8.4.2",
       "resolved": "https://registry.npmmirror.com/path-to-regexp/-/path-to-regexp-8.4.2.tgz",
@@ -1472,6 +1669,15 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/pkce-challenge": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmmirror.com/pkce-challenge/-/pkce-challenge-5.0.1.tgz",
+      "integrity": "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
     "node_modules/playwright": {
       "version": "1.59.1",
       "resolved": "https://registry.npmmirror.com/playwright/-/playwright-1.59.1.tgz",
@@ -1729,6 +1935,27 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/shebang-command": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmmirror.com/shebang-command/-/shebang-command-2.0.0.tgz",
+      "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
+      "license": "MIT",
+      "dependencies": {
+        "shebang-regex": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/shebang-regex": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmmirror.com/shebang-regex/-/shebang-regex-3.0.0.tgz",
+      "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/side-channel": {
       "version": "1.1.0",
       "resolved": "https://registry.npmmirror.com/side-channel/-/side-channel-1.1.0.tgz",
@@ -2006,6 +2233,21 @@
         }
       }
     },
+    "node_modules/which": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmmirror.com/which/-/which-2.0.2.tgz",
+      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+      "license": "ISC",
+      "dependencies": {
+        "isexe": "^2.0.0"
+      },
+      "bin": {
+        "node-which": "bin/node-which"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
     "node_modules/which-typed-array": {
       "version": "1.1.20",
       "resolved": "https://registry.npmmirror.com/which-typed-array/-/which-typed-array-1.1.20.tgz",
@@ -2063,6 +2305,15 @@
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }
+    },
+    "node_modules/zod-to-json-schema": {
+      "version": "3.25.2",
+      "resolved": "https://registry.npmmirror.com/zod-to-json-schema/-/zod-to-json-schema-3.25.2.tgz",
+      "integrity": "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==",
+      "license": "ISC",
+      "peerDependencies": {
+        "zod": "^3.25.28 || ^4"
+      }
     }
   }
 }

package.json

@@ -7,11 +7,18 @@
     "start": "node server.js",
     "demo": "node demo-client.js"
   },
-  "keywords": ["x402", "stellar", "render", "headless-browser", "micropayments"],
+  "keywords": [
+    "x402",
+    "stellar",
+    "render",
+    "headless-browser",
+    "micropayments"
+  ],
   "author": "tantk",
   "license": "MIT",
   "type": "module",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@stellar/stellar-sdk": "^15.0.1",
     "@x402/core": "^2.9.0",
     "@x402/express": "^2.9.0",