docs(mcp): clarify current SIWX reuse path

examples/typescript/servers/mcp/README.md

@@ -102,6 +102,24 @@ Or use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to
 4. Server verifies payment, executes tool, returns result
 5. Payment is settled and receipt included in response
 
+## Extending This Pattern With SIWX
+
+This example is intentionally payment-first: every paid MCP tool call follows the `402 -> pay -> retry` loop above.
+
+If you want a "pay once, then reopen the same paid MCP tool without repaying" flow, the clean shape is:
+
+1. Add an auth-only MCP tool that returns a SIWX challenge
+2. Keep the first call to the paid tool on the normal x402 payment path
+3. Record entitlement for the exact MCP resource, for example `mcp://tool/get_weather`
+4. On later calls, accept wallet-auth plus stored entitlement instead of requiring a second payment
+
+Two important notes:
+
+- `@x402/mcp` `createPaymentWrapper()` currently requires at least one payment requirement, so auth-only MCP tools still need custom wrapper logic today
+- The HTTP [Sign-In-With-X example](../sign-in-with-x/README.md) is the best current reference for the wallet-auth pieces: challenge declaration, payment recording, and later reuse
+
+That makes MCP SIWX reuse a good docs-and-example extension point without changing the core pay-every-call example here.
+
 ## Architecture
 
 ```

examples/typescript/servers/sign-in-with-x/README.md

@@ -38,6 +38,17 @@ app.use(paymentMiddlewareFromHTTPServer(httpServer));
 3. **Server records** — Payment is recorded against the wallet address in storage
 4. **Later paid-route request** — Signature proves wallet ownership and grants access without re-payment
 
+## MCP Note
+
+This example is HTTP-based, but the same high-level SIWX pattern also applies to MCP:
+
+- surface the SIWX challenge in `PaymentRequired.extensions`
+- carry the signed proof in MCP `_meta`
+- record entitlement against the exact MCP resource, for example `mcp://tool/<toolName>`
+- allow later calls to that same paid tool through wallet-auth plus stored entitlement
+
+Today `@x402/mcp` is still payment-first and does not yet ship a first-class auth-only SIWX helper, so MCP servers that want this flow need custom wrapper logic around the existing MCP transport and the SIWX extension primitives shown here.
+
 ## Prerequisites
 
 - Node.js v20+ (install via [nvm](https://github.com/nvm-sh/nvm))

typescript/packages/mcp/README.md

@@ -236,6 +236,25 @@ const x402Mcp2 = wrapMCPClientWithPaymentFromConfig(mcpClient, {
 6. **Server settles payment** → Transaction submitted
 7. **Server returns result** → SettleResponse in `_meta["x402/payment-response"]`
 
+## Current Scope: Payment-First MCP
+
+`@x402/mcp` currently focuses on paid MCP tool execution.
+
+In particular:
+
+- `createPaymentWrapper()` requires at least one payment requirement
+- the package does not yet ship a first-class auth-only MCP helper
+- SIWX-style "pay once, then reopen the same paid tool without repaying" flows still need custom wrapper logic today
+
+If you want that pattern, the recommended shape is:
+
+1. Use the normal x402 payment flow for the first paid-tool unlock
+2. Record entitlement for the exact MCP resource, for example `mcp://tool/<toolName>`
+3. Carry wallet-auth material and any short-lived access grant in MCP `_meta`
+4. Re-check entitlement before allowing the later call through without payment
+
+For the wallet-auth building blocks, see the TypeScript [Sign-In-With-X server example](../../../examples/typescript/servers/sign-in-with-x/README.md).
+
 ## MCP SDK Limitation
 
 The x402 MCP transport spec defines payment errors using JSON-RPC's native error format: