@oobe-protocol-labs/sap-mcp-server 0.3.0 → 0.7.1

package/dist/remote/server.js

@@ -6,7 +6,7 @@
 import { randomUUID } from 'crypto';
 import { existsSync, readFileSync } from 'fs';
 import * as http from 'http';
-import { dirname, join } from 'path';
+import { dirname, join, posix } from 'path';
 import { fileURLToPath } from 'url';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { getDataDir, loadConfig } from '../config/env.js';
@@ -14,12 +14,23 @@ import { MCP_SERVER_VERSION } from '../core/constants.js';
 import { logger, initLogger } from '../core/logger.js';
 import { createSapMcpServer } from '../server/create-server.js';
 import { AuthManager } from './auth/index.js';
-import { McpMonetizationGate } from '../payments/index.js';
+import { McpMonetizationGate, resolvePaymentNetwork } from '../payments/index.js';
+import { generatePayShProviderYaml } from '../payments/pay-sh-spec.js';
 import { RemoteRateLimiter, buildRemoteRateLimitConfigFromEnv } from './rate-limiter.js';
 const PUBLIC_SERVER_TITLE = 'SAP MCP Server | OOBE Protocol';
 const PUBLIC_SERVER_DESCRIPTION = 'Hosted Solana-native MCP gateway for Synapse Agent Protocol tools, x402/pay.sh monetization, SNS identity, and agent operations.';
 const LOGO_ASSET_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'assets', 'explorer_logo.png');
+const DOCS_ROOT_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'docs');
+const USER_DOCS_ROOT_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'USER_DOCS');
 const PAYMENT_STATS_CACHE_MS = 15_000;
+const RELEASE_DOWNLOAD_BASE_URL = `https://github.com/OOBE-PROTOCOL/sap-mcp/releases/download/${MCP_SERVER_VERSION}`;
+const WIZARD_NPM_COMMAND = 'npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard';
+const X402_PAID_CALL_NPX_COMMAND = 'npx --yes --package @oobe-protocol-labs/sap-mcp-server sap-mcp-x402-paid-call --tool sap_list_all_agents --arguments \'{"limit":5}\' --max-usd 0.02 --confirm';
+const X402_PAID_CALL_ADDON_PATH = '~/.config/mcp-sap/addons/x402-paid-call';
+const SOLANA_DEVNET_CAIP2 = 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1';
+const USDC_MAINNET_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+const USDC_DEVNET_MINT = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU';
+const MCP_REGISTRY_AUTH_PATH = '/.well-known/mcp-registry-auth';
 let logoAssetCache;
 let paymentStatsCache;
 /**
@@ -53,8 +64,13 @@ export function defaultRemoteConfig(appConfig) {
         port,
         host,
         corsOrigins: appConfig.httpCorsOrigins,
-        stateless: parseRemoteBoolean(process.env.SAP_MCP_HTTP_STATELESS, appConfig.mode === 'hosted-api'),
+        stateless: parseRemoteBoolean(process.env.SAP_MCP_HTTP_STATELESS, false),
         rateLimit: buildRemoteRateLimitConfigFromEnv(appConfig.rateLimitPerMinute),
+        paymentDiscovery: buildPublicPaymentDiscovery(appConfig),
+        paymentPriceRange: {
+            minUsd: appConfig.monetization.prices.minUsd,
+            maxUsd: appConfig.monetization.prices.maxUsd,
+        },
     };
     if (authType === 'none') {
         return {
@@ -86,6 +102,56 @@ export function defaultRemoteConfig(appConfig) {
         },
     };
 }
+/**
+ * @name buildPublicPaymentDiscovery
+ * @description Builds public x402 seller/facilitator coordinates without exposing facilitator URL or auth tokens.
+ */
+function buildPublicPaymentDiscovery(appConfig) {
+    if (!appConfig.monetization.enabled || !appConfig.monetization.payTo) {
+        return undefined;
+    }
+    const network = resolvePaymentNetwork(appConfig);
+    const facilitatorPublicKey = (process.env.SAP_MCP_X402_FACILITATOR_PUBLIC_KEY
+        ?? process.env.SAP_MCP_X402_FACILITATOR_FEE_PAYER
+        ?? '').trim();
+    return {
+        provider: appConfig.monetization.provider,
+        network,
+        asset: resolvePublicPaymentAsset(network),
+        assetSymbol: 'USDC',
+        payTo: appConfig.monetization.payTo,
+        seller: {
+            name: 'OOBE Protocol',
+            payTo: appConfig.monetization.payTo,
+        },
+        ...(facilitatorPublicKey
+            ? {
+                facilitator: {
+                    role: 'x402-svm-fee-payer',
+                    publicKey: facilitatorPublicKey,
+                },
+            }
+            : {}),
+        headers: {
+            paymentRequired: 'PAYMENT-REQUIRED',
+            paymentSignature: 'PAYMENT-SIGNATURE',
+            paymentResponse: 'PAYMENT-RESPONSE',
+        },
+    };
+}
+/**
+ * @name resolvePublicPaymentAsset
+ * @description Resolves the public USDC mint advertised in x402 discovery metadata.
+ */
+function resolvePublicPaymentAsset(network) {
+    if (network === SOLANA_DEVNET_CAIP2) {
+        return USDC_DEVNET_MINT;
+    }
+    return USDC_MAINNET_MINT;
+}
+function formatOpenApiUsd(value) {
+    return value.toFixed(6).replace(/0+$/, '').replace(/\.$/, '');
+}
 function parseRemoteBoolean(raw, fallback) {
     if (raw === undefined) {
         return fallback;
@@ -96,38 +162,248 @@ function parseRemoteBoolean(raw, fallback) {
  * @name writeJson
  * @description Writes a JSON response with optional additional headers.
  */
-function writeJson(res, status, body, headers = {}) {
+function writeJson(res, status, body, headers = {}, omitBody = false) {
+    const serialized = JSON.stringify(body);
     res.writeHead(status, {
         'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(serialized),
         ...headers,
     });
-    res.end(JSON.stringify(body));
+    res.end(omitBody ? undefined : serialized);
+}
+/**
+ * @name writeText
+ * @description Writes a cacheable text response with an explicit content type.
+ */
+function writeText(res, status, body, contentType, headers = {}, omitBody = false) {
+    res.writeHead(status, {
+        'Content-Type': contentType,
+        'Cache-Control': 'public, max-age=300',
+        'Content-Length': Buffer.byteLength(body),
+        'X-Content-Type-Options': 'nosniff',
+        ...headers,
+    });
+    res.end(omitBody ? undefined : body);
+}
+/**
+ * @name writeMcpJsonRpcError
+ * @description Writes an MCP-compatible JSON-RPC error response with HTTP status semantics.
+ */
+function writeMcpJsonRpcError(res, status, code, id, message, data) {
+    writeJson(res, status, {
+        jsonrpc: '2.0',
+        id,
+        error: {
+            code,
+            message,
+            ...(data === undefined ? {} : { data }),
+        },
+    });
+}
+/**
+ * @name readSingleHeader
+ * @description Reads one normalized HTTP header value without accepting ambiguous arrays.
+ */
+function readSingleHeader(value) {
+    if (Array.isArray(value)) {
+        return value[0]?.trim() || undefined;
+    }
+    return value?.trim() || undefined;
+}
+/**
+ * @name extractJsonRpcId
+ * @description Extracts a JSON-RPC id for error correlation.
+ */
+function extractJsonRpcId(body) {
+    if (Array.isArray(body) && body.length > 0) {
+        return extractJsonRpcId(body[0]);
+    }
+    if (!body || typeof body !== 'object') {
+        return null;
+    }
+    const record = body;
+    return typeof record.id === 'string' || typeof record.id === 'number' ? record.id : null;
+}
+/**
+ * @name isInitializeJsonRpcRequest
+ * @description Detects MCP initialize requests that are allowed to create a new stateful session.
+ */
+function isInitializeJsonRpcRequest(body) {
+    if (Array.isArray(body)) {
+        return body.some(isInitializeJsonRpcRequest);
+    }
+    if (!body || typeof body !== 'object') {
+        return false;
+    }
+    return body.method === 'initialize';
 }
 /**
  * @name writeHtml
  * @description Writes a cacheable HTML response for public endpoint previews and social sharing.
  */
-function writeHtml(res, status, html) {
+function writeHtml(res, status, html, omitBody = false) {
     res.writeHead(status, {
         'Content-Type': 'text/html; charset=utf-8',
         'Cache-Control': 'public, max-age=300',
+        'Content-Length': Buffer.byteLength(html),
+        'X-Content-Type-Options': 'nosniff',
+    });
+    res.end(omitBody ? undefined : html);
+}
+/**
+ * @name isPublicReadMethod
+ * @description Returns true for cacheable public metadata reads, including crawler-friendly HEAD checks.
+ */
+function isPublicReadMethod(method) {
+    return method === 'GET' || method === 'HEAD';
+}
+/**
+ * @name isHeadMethod
+ * @description Returns true when the request must emit headers without a response body.
+ */
+function isHeadMethod(method) {
+    return method === 'HEAD';
+}
+/**
+ * @name resolveMcpRegistryAuthRecord
+ * @description Resolves the MCP Registry HTTP ownership proof from a public env value or a private file path.
+ */
+function resolveMcpRegistryAuthRecord() {
+    const inlineRecord = process.env.SAP_MCP_REGISTRY_AUTH_RECORD?.trim();
+    if (inlineRecord) {
+        return inlineRecord;
+    }
+    const recordPath = process.env.SAP_MCP_REGISTRY_AUTH_FILE?.trim();
+    if (!recordPath) {
+        return undefined;
+    }
+    try {
+        if (!existsSync(recordPath)) {
+            return undefined;
+        }
+        const fileRecord = readFileSync(recordPath, 'utf8').trim();
+        return fileRecord || undefined;
+    }
+    catch (error) {
+        logger.warn('Failed to read MCP Registry auth record', {
+            path: recordPath,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+}
+/**
+ * @name writeMcpRegistryAuthRecord
+ * @description Writes the MCP Registry HTTP ownership proof without exposing private signing material.
+ */
+function writeMcpRegistryAuthRecord(res, omitBody) {
+    const record = resolveMcpRegistryAuthRecord();
+    if (!record) {
+        writeText(res, 404, 'MCP Registry auth record is not configured.\n', 'text/plain; charset=utf-8', { 'Cache-Control': 'no-store' }, omitBody);
+        return;
+    }
+    writeText(res, 200, `${record}\n`, 'text/plain; charset=utf-8', { 'Cache-Control': 'public, max-age=60' }, omitBody);
+}
+/**
+ * @name writeMarkdownAsset
+ * @description Writes a resolved public markdown documentation asset.
+ */
+function writeMarkdownAsset(res, asset) {
+    res.writeHead(200, {
+        'Content-Type': asset.contentType,
+        'Cache-Control': 'public, max-age=120',
+        'Content-Length': asset.contentLength,
         'X-Content-Type-Options': 'nosniff',
     });
-    res.end(html);
+    res.end(asset.body);
+}
+/**
+ * @name resolvePublicDocsMarkdown
+ * @description Resolves safe hosted documentation markdown requests under /docs and /docs/user.
+ */
+export function resolvePublicDocsMarkdown(method, pathname) {
+    if (method !== 'GET' && method !== 'HEAD') {
+        return undefined;
+    }
+    if (!pathname.startsWith('/docs/') || !pathname.endsWith('.md')) {
+        return undefined;
+    }
+    let decodedPath;
+    try {
+        decodedPath = decodeURIComponent(pathname.slice('/docs/'.length));
+    }
+    catch {
+        return undefined;
+    }
+    const normalizedPath = posix.normalize(decodedPath.replace(/\\/g, '/')).replace(/^[/\\]+/, '');
+    if (isUnsafeDocsPath(normalizedPath)) {
+        return undefined;
+    }
+    const root = normalizedPath.startsWith('user/')
+        ? USER_DOCS_ROOT_PATH
+        : DOCS_ROOT_PATH;
+    const relativePath = normalizedPath.startsWith('user/')
+        ? normalizedPath.slice('user/'.length)
+        : normalizedPath;
+    if (isUnsafeDocsPath(relativePath)) {
+        return undefined;
+    }
+    const absolutePath = join(root, relativePath);
+    if (!existsSync(absolutePath)) {
+        return undefined;
+    }
+    const markdown = readFileSync(absolutePath, 'utf-8');
+    return {
+        contentType: 'text/markdown; charset=utf-8',
+        contentLength: Buffer.byteLength(markdown),
+        body: method === 'HEAD' ? undefined : markdown,
+    };
+}
+function isUnsafeDocsPath(pathname) {
+    return pathname === ''
+        || pathname.includes('\0')
+        || pathname === '..'
+        || pathname.startsWith('../')
+        || pathname.includes('/../');
 }
 /**
- * @name writePngAsset
- * @description Writes the bundled SAP logo as a public icon/social image asset.
+ * @name resolvePublicLogoAsset
+ * @description Resolves public icon/social image routes, including HEAD-safe favicon responses for crawlers.
  */
-function writePngAsset(res) {
+export function resolvePublicLogoAsset(method, pathname) {
+    if (method !== 'GET' && method !== 'HEAD') {
+        return undefined;
+    }
     const image = readLogoAsset();
+    const body = method === 'HEAD' ? undefined : image;
+    if (['/favicon.png', '/apple-touch-icon.png', '/og.png'].includes(pathname)) {
+        return {
+            contentType: 'image/png',
+            contentLength: image.byteLength,
+            body,
+        };
+    }
+    if (pathname === '/favicon.ico') {
+        return {
+            contentType: 'image/x-icon',
+            contentLength: image.byteLength,
+            body,
+        };
+    }
+    return undefined;
+}
+/**
+ * @name writeLogoAsset
+ * @description Writes a resolved public logo asset response.
+ */
+function writeLogoAsset(res, asset) {
     res.writeHead(200, {
-        'Content-Type': 'image/png',
+        'Content-Type': asset.contentType,
         'Cache-Control': 'public, max-age=86400',
-        'Content-Length': image.byteLength,
+        'Content-Length': asset.contentLength,
         'X-Content-Type-Options': 'nosniff',
     });
-    res.end(image);
+    res.end(asset.body);
 }
 /**
  * @name readLogoAsset
@@ -265,13 +541,27 @@ export function buildPublicServerInfo(req, config) {
         },
         endpoints: {
             landing: `${baseUrl}/`,
+            docs: `${baseUrl}/docs`,
             mcp: `${baseUrl}/mcp`,
             health: `${baseUrl}/health`,
             serverInfo: `${baseUrl}/server.json`,
+            openApi: `${baseUrl}/openapi.json`,
+            x402Discovery: `${baseUrl}/.well-known/x402`,
+            payShProvider: `${baseUrl}/pay/provider.yml`,
             agentCard: `${baseUrl}/.well-known/agent-card.json`,
             wizardDescriptor: `${baseUrl}/.well-known/sap-mcp-wizard.json`,
+            wizardDownloads: `${baseUrl}/wizard/downloads.json`,
             wizardInstallScript: `${baseUrl}/wizard/install.sh`,
             favicon: `${baseUrl}/favicon.png`,
+            faviconIco: `${baseUrl}/favicon.ico`,
+        },
+        downloads: {
+            release: `https://github.com/OOBE-PROTOCOL/sap-mcp/releases/tag/${MCP_SERVER_VERSION}`,
+            desktopWizard: {
+                macosArm64Dmg: `${RELEASE_DOWNLOAD_BASE_URL}/SAP-MCP-Wizard-${MCP_SERVER_VERSION}-arm64.dmg`,
+                windowsX64Setup: `${RELEASE_DOWNLOAD_BASE_URL}/SAP-MCP-Wizard-Setup-${MCP_SERVER_VERSION}-x64.exe`,
+                linuxX64TarGz: `${RELEASE_DOWNLOAD_BASE_URL}/sap-mcp-wizard-${MCP_SERVER_VERSION}-x64.tar.gz`,
+            },
         },
         capabilities: {
             tools: true,
@@ -285,6 +575,7 @@ export function buildPublicServerInfo(req, config) {
             schemes: authRequired ? ['Bearer'] : ['none', 'x402'],
             bearerRequired: authRequired,
         },
+        ...(config.paymentDiscovery ? { payments: config.paymentDiscovery } : {}),
         security: {
             keypairBytesExposed: false,
             storesUserKeypairs: false,
@@ -298,6 +589,237 @@ export function buildPublicServerInfo(req, config) {
         },
     };
 }
+/**
+ * @name buildPublicPayShProviderYaml
+ * @description Builds a public pay.sh provider catalog for the hosted SAP MCP endpoint without RPC secrets or signer paths.
+ */
+export function buildPublicPayShProviderYaml(req, config, appConfig) {
+    const baseUrl = buildPublicBaseUrl(req, config);
+    return generatePayShProviderYaml(appConfig, {
+        name: 'oobe-sap-mcp',
+        subdomain: 'oobe-sap-mcp',
+        title: 'OOBE SAP MCP Server',
+        description: PUBLIC_SERVER_DESCRIPTION,
+        version: MCP_SERVER_VERSION,
+        upstreamUrl: baseUrl,
+        recipient: config.paymentDiscovery?.payTo ?? appConfig.monetization.payTo,
+        rpcUrl: undefined,
+        signerPath: undefined,
+    });
+}
+/**
+ * @name buildOpenApiSpec
+ * @description OpenAPI 3.1 spec for x402scan discovery. Describes the /mcp endpoint
+ * with x-payment-info so x402scan can discover and register the API.
+ */
+export function buildOpenApiSpec(req, config) {
+    const baseUrl = buildPublicBaseUrl(req, config);
+    const priceRange = config.paymentPriceRange ?? { minUsd: 0.001, maxUsd: 100 };
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: 'SAP MCP Server',
+            version: MCP_SERVER_VERSION,
+            description: 'MCP gateway for Solana DeFi, SAP agent registry, and x402 micropayments. 248 tools across Jupiter, Drift, Metaplex, Pump.fun, Raydium, Orca, and more.',
+            'x-guidance': 'Connect to POST /mcp with Accept: application/json, text/event-stream. Initialize an MCP session first, then call tools. Paid tools return a payment_required JSON-RPC error (HTTP 200 for MCP SDK compatibility) or HTTP 402 for non-MCP clients. Use x402_paid_call or npx sap-mcp-x402-paid-call to self-pay and retry.',
+            contact: {
+                name: 'OOBE Protocol Labs',
+                url: 'https://github.com/OOBE-PROTOCOL/sap-mcp',
+                email: 'oobe@oobeprotocol.ai',
+            },
+        },
+        'x-discovery': {
+            resources: [`${baseUrl}/mcp`],
+            openApi: `${baseUrl}/openapi.json`,
+            x402Discovery: `${baseUrl}/.well-known/x402`,
+            payShProvider: `${baseUrl}/pay/provider.yml`,
+            ...(config.paymentDiscovery ? { payments: config.paymentDiscovery } : {}),
+        },
+        'x-pay-sh': {
+            providerYaml: `${baseUrl}/pay/provider.yml`,
+            routing: {
+                type: 'proxy',
+                upstream: `${baseUrl}/`,
+            },
+            monetization: {
+                mode: 'metered',
+                unit: 'requests',
+                sourceOfTruth: 'SAP MCP per-tool x402 pricing remains authoritative after proxy forwarding.',
+            },
+        },
+        servers: [
+            { url: baseUrl, description: 'SAP MCP Hosted Server' },
+        ],
+        paths: {
+            '/mcp': {
+                post: {
+                    operationId: 'mcpCall',
+                    summary: 'Fetch SAP MCP JSON-RPC response',
+                    tags: ['MCP'],
+                    'x-payment-info': {
+                        price: {
+                            mode: 'dynamic',
+                            currency: 'USD',
+                            min: formatOpenApiUsd(priceRange.minUsd),
+                            max: formatOpenApiUsd(priceRange.maxUsd),
+                        },
+                        protocols: ['x402'],
+                        ...(config.paymentDiscovery
+                            ? {
+                                network: config.paymentDiscovery.network,
+                                asset: config.paymentDiscovery.asset,
+                                assetSymbol: config.paymentDiscovery.assetSymbol,
+                                payTo: config.paymentDiscovery.payTo,
+                                seller: config.paymentDiscovery.seller,
+                                facilitator: config.paymentDiscovery.facilitator,
+                            }
+                            : {}),
+                    },
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    oneOf: [
+                                        {
+                                            type: 'object',
+                                            description: 'General MCP JSON-RPC request such as initialize, tools/list, prompts/list, resources/list, or ping.',
+                                            properties: {
+                                                jsonrpc: { type: 'string', const: '2.0' },
+                                                id: { oneOf: [{ type: 'integer' }, { type: 'string' }], description: 'JSON-RPC request ID' },
+                                                method: {
+                                                    type: 'string',
+                                                    description: 'MCP method.',
+                                                    examples: ['initialize', 'tools/list', 'prompts/list', 'resources/list', 'ping'],
+                                                },
+                                                params: { type: 'object', additionalProperties: true },
+                                            },
+                                            required: ['jsonrpc', 'id', 'method'],
+                                        },
+                                        {
+                                            type: 'object',
+                                            description: 'MCP tools/call request. Paid tool calls may require x402 payment before execution.',
+                                            properties: {
+                                                jsonrpc: { type: 'string', const: '2.0' },
+                                                id: { oneOf: [{ type: 'integer' }, { type: 'string' }], description: 'JSON-RPC request ID' },
+                                                method: { type: 'string', const: 'tools/call' },
+                                                params: {
+                                                    type: 'object',
+                                                    description: 'MCP tools/call parameters containing the target tool name and optional tool arguments.',
+                                                    properties: {
+                                                        name: { type: 'string', description: 'Tool name (e.g. jupiter_getPrice)' },
+                                                        arguments: { type: 'object', description: 'Tool arguments', additionalProperties: true },
+                                                    },
+                                                    required: ['name'],
+                                                    additionalProperties: true,
+                                                },
+                                            },
+                                            required: ['jsonrpc', 'id', 'method', 'params'],
+                                        },
+                                    ],
+                                },
+                            },
+                        },
+                    },
+                    responses: {
+                        '200': {
+                            description: 'MCP tool result or payment_required JSON-RPC error (for MCP SDK clients)',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        properties: {
+                                            jsonrpc: { type: 'string' },
+                                            id: { type: 'integer' },
+                                            result: { type: 'object', description: 'Tool result (if free or paid)' },
+                                            error: {
+                                                type: 'object',
+                                                properties: {
+                                                    code: { type: 'integer' },
+                                                    message: { type: 'string' },
+                                                    data: {
+                                                        type: 'object',
+                                                        properties: {
+                                                            protocol: { type: 'string' },
+                                                            paymentRequirements: { type: 'array' },
+                                                        },
+                                                    },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                                'text/event-stream': {
+                                    schema: {
+                                        type: 'string',
+                                        description: 'Streamable HTTP MCP event stream containing JSON-RPC response events.',
+                                    },
+                                },
+                            },
+                        },
+                        '402': {
+                            description: 'Payment Required (x402 challenge for non-MCP clients)',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        properties: {
+                                            x402Version: { type: 'integer' },
+                                            error: { type: 'string' },
+                                            accepts: {
+                                                type: 'array',
+                                                items: {
+                                                    type: 'object',
+                                                    properties: {
+                                                        scheme: { type: 'string' },
+                                                        network: { type: 'string' },
+                                                        amount: { type: 'string', description: 'USDC atomic units (6 decimals)' },
+                                                        asset: { type: 'string' },
+                                                        payTo: { type: 'string' },
+                                                        maxTimeoutSeconds: { type: 'integer' },
+                                                        extra: {
+                                                            type: 'object',
+                                                            properties: {
+                                                                feePayer: { type: 'string' },
+                                                            },
+                                                        },
+                                                    },
+                                                },
+                                            },
+                                            resource: {
+                                                type: 'object',
+                                                properties: {
+                                                    url: { type: 'string' },
+                                                    description: { type: 'string' },
+                                                    mimeType: { type: 'string' },
+                                                    serviceName: { type: 'string' },
+                                                    tags: { type: 'array', items: { type: 'string' } },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    };
+}
+/**
+ * @name buildX402DiscoveryDocument
+ * @description Builds the compatibility discovery document consumed by x402scan.
+ */
+export function buildX402DiscoveryDocument(req, config) {
+    const baseUrl = buildPublicBaseUrl(req, config);
+    return {
+        version: 1,
+        resources: [`${baseUrl}/mcp`],
+        ...(config.paymentDiscovery ? { payments: config.paymentDiscovery } : {}),
+        instructions: 'SAP MCP exposes paid hosted MCP tool calls at /mcp. Probe POST /mcp without a payment header to receive a parseable x402 challenge for paid tools.',
+    };
+}
 /**
  * @name buildLandingHtml
  * @description Builds professional public HTML metadata for root and `/mcp` URL previews.
@@ -310,8 +832,9 @@ export function buildLandingHtml(req, config, endpoint = 'root') {
         ? 'SAP MCP Streamable HTTP Endpoint | OOBE Protocol'
         : info.title;
     const endpointLabel = endpoint === 'mcp' ? 'Streamable HTTP MCP endpoint' : 'Hosted MCP gateway';
-    const wizardCommand = 'npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard';
+    const wizardCommand = WIZARD_NPM_COMMAND;
     const installScriptCommand = 'curl -fsSL https://mcp.sap.oobeprotocol.ai/wizard/install.sh | sh';
+    const x402PaidCallCommand = X402_PAID_CALL_NPX_COMMAND;
     const publicInfo = JSON.stringify(info, null, 2).replace(/</g, '\\u003c');
     return `<!doctype html>
 <html lang="en">
@@ -322,8 +845,9 @@ export function buildLandingHtml(req, config, endpoint = 'root') {
   <meta name="description" content="${escapeHtml(info.description)}">
   <meta name="robots" content="index,follow">
   <link rel="canonical" href="${escapeHtml(pageUrl)}">
+  <link rel="icon" type="image/x-icon" href="/favicon.ico">
   <link rel="icon" type="image/png" href="/favicon.png">
-  <link rel="shortcut icon" type="image/png" href="/favicon.png">
+  <link rel="shortcut icon" href="/favicon.ico">
   <link rel="apple-touch-icon" href="/apple-touch-icon.png">
   <meta property="og:type" content="website">
   <meta property="og:title" content="${escapeHtml(title)}">
@@ -428,6 +952,21 @@ export function buildLandingHtml(req, config, endpoint = 'root') {
     .list { padding-left: 18px; margin: 0; color: var(--muted); }
     .list li + li { margin-top: 8px; }
     .command { margin-top: 12px; border: 1px solid rgba(255,255,255,.10); border-radius: 8px; background: rgba(0,0,0,.28); padding: 13px; }
+    .download-grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 10px; margin-top: 14px; }
+    .download-link {
+      display: grid;
+      min-height: 74px;
+      align-content: center;
+      gap: 4px;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      background: rgba(0,0,0,.18);
+      padding: 12px;
+      color: var(--ink);
+      text-decoration: none;
+    }
+    .download-link strong { color: var(--aqua); }
+    .download-link span { color: var(--muted); font-size: .88rem; }
     .endpoint-list { display: grid; gap: 10px; margin-top: 10px; }
     .endpoint-row { display: grid; grid-template-columns: 72px 1fr; gap: 12px; align-items: baseline; }
     .method { color: var(--success); font: 700 .78rem/1 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; }
@@ -436,6 +975,7 @@ export function buildLandingHtml(req, config, endpoint = 'root') {
       header { grid-template-columns: 1fr; }
       img.logo { width: 76px; height: 76px; border-radius: 20px; }
       .span-3, .span-4, .span-5, .span-6, .span-7, .span-8 { grid-column: span 12; }
+      .download-grid { grid-template-columns: 1fr; }
     }
     @media (min-width: 861px) and (max-width: 1120px) {
       .span-3, .span-4 { grid-column: span 6; }
@@ -456,7 +996,11 @@ export function buildLandingHtml(req, config, endpoint = 'root') {
         <p>${escapeHtml(info.description)}</p>
         <div class="hero-actions">
           <a class="button" href="/wizard/install.sh">Install wizard</a>
+          <a class="button secondary" href="/wizard/downloads.json">Downloads</a>
+          <a class="button secondary" href="/docs">Docs</a>
           <a class="button secondary" href="/server.json">Server JSON</a>
+          <a class="button secondary" href="/openapi.json">OpenAPI</a>
+          <a class="button secondary" href="/pay/provider.yml">pay.sh YAML</a>
           <a class="button secondary" href="/.well-known/agent-card.json">Agent card</a>
         </div>
       </div>
@@ -488,21 +1032,43 @@ export function buildLandingHtml(req, config, endpoint = 'root') {
         <div class="command"><code>${escapeHtml(wizardCommand)}</code></div>
       </section>
 
+      <section class="card span-5">
+        <h2>Native Downloads</h2>
+        <p>Use the desktop wizard when you want a guided setup without touching config files by hand.</p>
+        <div class="download-grid">
+          <a class="download-link" href="${escapeHtml(info.downloads.desktopWizard.windowsX64Setup)}"><strong>Windows</strong><span>x64 setup .exe</span></a>
+          <a class="download-link" href="${escapeHtml(info.downloads.desktopWizard.macosArm64Dmg)}"><strong>macOS</strong><span>Apple Silicon .dmg</span></a>
+          <a class="download-link" href="${escapeHtml(info.downloads.desktopWizard.linuxX64TarGz)}"><strong>Linux</strong><span>x64 tar.gz</span></a>
+        </div>
+        <p class="caption">Machine-readable links: <a href="${escapeHtml(info.endpoints.wizardDownloads)}">/wizard/downloads.json</a>.</p>
+      </section>
+
       <section class="card span-5">
         <h2>Payments</h2>
         <ul class="list">
           <li><strong>x402:</strong> paid MCP tool calls return HTTP 402 with payment requirements, then settle through the OOBE facilitator.</li>
-          <li><strong>pay.sh:</strong> supports pay-per-use and subscription specs for agents or dashboards that prefer checkout flows.</li>
+          <li><strong>pay.sh:</strong> public provider YAML is available at <a href="${escapeHtml(info.endpoints.payShProvider)}">/pay/provider.yml</a> for catalog and proxy workflows.</li>
           <li><strong>Local stdio:</strong> free by default; monetization applies to hosted remote usage.</li>
         </ul>
       </section>
 
+      <section class="card strong span-12">
+        <h2>x402 Paid-Call Plugin For Agents</h2>
+        <p>Agents that can reach hosted MCP but cannot replay x402 challenges natively can install the wizard addon or invoke the local paid-call helper directly. The helper signs the payment payload locally and retries the hosted tool call without sending keypair bytes to OOBE.</p>
+        <div class="command"><code>Addon path: ${escapeHtml(X402_PAID_CALL_ADDON_PATH)}</code></div>
+        <div class="command"><code>${escapeHtml(x402PaidCallCommand)}</code></div>
+      </section>
+
       <section class="card span-8">
         <h2>Endpoints</h2>
         <div class="endpoint-list">
           <div class="endpoint-row"><span class="method">POST</span><code>${escapeHtml(info.endpoints.mcp)}</code></div>
+          <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.docs)}</code></div>
           <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.health)}</code></div>
           <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.serverInfo)}</code></div>
+          <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.openApi)}</code></div>
+          <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.x402Discovery)}</code></div>
+          <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.payShProvider)}</code></div>
           <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.agentCard)}</code></div>
           <div class="endpoint-row"><span class="method">GET</span><code>${escapeHtml(info.endpoints.wizardDescriptor)}</code></div>
         </div>
@@ -522,6 +1088,115 @@ export function buildLandingHtml(req, config, endpoint = 'root') {
 </body>
 </html>`;
 }
+/**
+ * @name buildDocsHtml
+ * @description Builds the hosted SAP MCP documentation shell powered by Docsify.
+ */
+export function buildDocsHtml(req, config) {
+    const info = buildPublicServerInfo(req, config);
+    const docsUrl = info.endpoints.docs;
+    const title = 'SAP MCP Documentation | OOBE Protocol';
+    const description = 'Install, configure, and operate SAP MCP with a focus on hosted remote access, local signer setup, x402/pay.sh payments, and MCP client configuration.';
+    const docsifyConfig = JSON.stringify({
+        name: 'SAP MCP',
+        repo: 'https://github.com/OOBE-PROTOCOL/sap-mcp',
+        homepage: 'README.md',
+        loadSidebar: true,
+        alias: {
+            '/.*/_sidebar.md': '/docs/_sidebar.md',
+        },
+        subMaxLevel: 2,
+        auto2top: true,
+        themeColor: '#28d8e8',
+        search: {
+            paths: 'auto',
+            placeholder: 'Search SAP MCP docs',
+            noData: 'No results.',
+            depth: 6,
+        },
+    }, null, 2).replace(/</g, '\\u003c');
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(title)}</title>
+  <meta name="description" content="${escapeHtml(description)}">
+  <meta name="robots" content="index,follow">
+  <link rel="canonical" href="${escapeHtml(docsUrl)}">
+  <link rel="icon" type="image/x-icon" href="/favicon.ico">
+  <link rel="icon" type="image/png" href="/favicon.png">
+  <link rel="shortcut icon" href="/favicon.ico">
+  <link rel="apple-touch-icon" href="/apple-touch-icon.png">
+  <meta property="og:type" content="website">
+  <meta property="og:title" content="${escapeHtml(title)}">
+  <meta property="og:description" content="${escapeHtml(description)}">
+  <meta property="og:url" content="${escapeHtml(docsUrl)}">
+  <meta property="og:image" content="${escapeHtml(info.endpoints.favicon)}">
+  <meta name="twitter:card" content="summary">
+  <meta name="twitter:title" content="${escapeHtml(title)}">
+  <meta name="twitter:description" content="${escapeHtml(description)}">
+  <meta name="twitter:image" content="${escapeHtml(info.endpoints.favicon)}">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/themes/vue.css">
+  <style>
+    :root {
+      --theme-color: #28d8e8;
+      --sidebar-width: 310px;
+    }
+    body {
+      font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      color: #17242b;
+    }
+    .app-name-link {
+      color: #062730;
+      font-weight: 800;
+    }
+    .sidebar {
+      border-right: 1px solid rgba(6,39,48,.10);
+    }
+    .sidebar-nav strong,
+    .markdown-section h1,
+    .markdown-section h2,
+    .markdown-section h3 {
+      color: #062730;
+      letter-spacing: 0;
+    }
+    .markdown-section a {
+      color: #087f91;
+      text-underline-offset: 3px;
+    }
+    .markdown-section code {
+      color: #062730;
+      border-radius: 6px;
+    }
+    .markdown-section pre {
+      border-radius: 8px;
+      border: 1px solid rgba(6,39,48,.10);
+    }
+    .markdown-section table {
+      display: table;
+      width: 100%;
+    }
+    .markdown-section blockquote {
+      border-left-color: #28d8e8;
+      color: #49656f;
+    }
+    .cover-main,
+    section.cover {
+      background: linear-gradient(115deg, rgba(40,216,232,.13), transparent 34%), #f8fdff;
+    }
+  </style>
+</head>
+<body>
+  <div id="app">Loading SAP MCP documentation...</div>
+  <script>
+    window.$docsify = ${docsifyConfig};
+  </script>
+  <script src="https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/docsify.min.js" defer></script>
+  <script src="https://cdn.jsdelivr.net/npm/docsify@4.13.1/lib/plugins/search.min.js" defer></script>
+</body>
+</html>`;
+}
 /**
  * @name acceptsHtmlPreview
  * @description Returns true for browser-style GET previews without interfering with MCP SSE clients.
@@ -662,13 +1337,16 @@ export function buildWizardInstallDescriptor(req, config) {
         ],
         endpoints: {
             descriptor: `${baseUrl}/.well-known/sap-mcp-wizard.json`,
+            downloads: `${baseUrl}/wizard/downloads.json`,
             installScript: `${baseUrl}/wizard/install.sh`,
             mcp: `${baseUrl}/mcp`,
         },
         commands: {
-            runWizard: 'npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard',
+            runWizard: WIZARD_NPM_COMMAND,
             showConfig: 'npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config show',
             showProfile: 'npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config profile-info',
+            installX402PaidCallAddon: WIZARD_NPM_COMMAND,
+            runX402PaidCall: X402_PAID_CALL_NPX_COMMAND,
         },
         security: {
             keypairBytesExposed: false,
@@ -700,6 +1378,44 @@ export function buildWizardInstallScript(req, config) {
         '',
     ].join('\n');
 }
+/**
+ * @name extractToolNamesFromJsonRpc
+ * @description Extracts tool names from a parsed JSON-RPC 2.0 request body for request logging.
+ */
+function extractToolNamesFromJsonRpc(body) {
+    if (!body || typeof body !== 'object')
+        return undefined;
+    const record = body;
+    // tools/call request: { method: "tools/call", params: { name: "tool_name", ... } }
+    if (record.method === 'tools/call' && record.params && typeof record.params === 'object') {
+        const params = record.params;
+        if (typeof params.name === 'string')
+            return [params.name];
+    }
+    // Batch request: array of requests
+    if (Array.isArray(body)) {
+        const names = [];
+        for (const item of body) {
+            const extracted = extractToolNamesFromJsonRpc(item);
+            if (extracted)
+                names.push(...extracted);
+        }
+        return names.length > 0 ? names : undefined;
+    }
+    return undefined;
+}
+/**
+ * @name extractJsonRpcMethod
+ * @description Extracts the JSON-RPC method name from a parsed request body for request logging.
+ */
+function extractJsonRpcMethod(body) {
+    if (!body || typeof body !== 'object')
+        return undefined;
+    const record = body;
+    if (typeof record.method === 'string')
+        return record.method;
+    return undefined;
+}
 /**
  * @name RemoteMCPServer
  * @description Remote MCP server backed by the official Streamable HTTP transport.
@@ -709,7 +1425,7 @@ export class RemoteMCPServer {
     appConfig;
     authManager;
     rateLimiter;
-    transport;
+    statefulSessions = new Map();
     httpServer;
     constructor(config) {
         this.appConfig = loadConfig();
@@ -730,63 +1446,92 @@ export class RemoteMCPServer {
         this.validateAuthConfig();
         await this.rateLimiter.initialize();
         const monetizationGate = await McpMonetizationGate.create(this.appConfig);
-        // In stateful mode, create one long-lived transport and connect the server once.
-        // In stateless mode, a fresh transport + server must be created per request —
-        // the MCP SDK throws "Stateless transport cannot be reused across requests"
-        // if a stateless transport handles more than one request.
-        if (!this.config.stateless) {
-            const server = await createSapMcpServer(this.appConfig);
-            this.transport = new StreamableHTTPServerTransport({
-                sessionIdGenerator: () => randomUUID(),
-            });
-            await server.connect(this.transport);
-        }
         this.httpServer = http.createServer(async (req, res) => {
             if (this.applyCors(req, res)) {
                 return;
             }
             const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
-            if (req.method === 'GET' && url.pathname === '/') {
-                writeHtml(res, 200, buildLandingHtml(req, this.config));
+            if (isPublicReadMethod(req.method) && url.pathname === '/') {
+                writeHtml(res, 200, buildLandingHtml(req, this.config), isHeadMethod(req.method));
                 return;
             }
-            if (req.method === 'GET' && url.pathname === '/server.json') {
+            if (isPublicReadMethod(req.method) && ['/docs', '/docs/', '/docs/index.html'].includes(url.pathname)) {
+                writeHtml(res, 200, buildDocsHtml(req, this.config), isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && url.pathname === '/server.json') {
                 writeJson(res, 200, buildPublicServerInfo(req, this.config), {
                     'Cache-Control': 'public, max-age=300',
-                });
+                }, isHeadMethod(req.method));
+                return;
+            }
+            const publicLogoAsset = resolvePublicLogoAsset(req.method, url.pathname);
+            if (publicLogoAsset) {
+                writeLogoAsset(res, publicLogoAsset);
                 return;
             }
-            if (req.method === 'GET' && ['/favicon.png', '/favicon.ico', '/apple-touch-icon.png', '/og.png'].includes(url.pathname)) {
-                writePngAsset(res);
+            const publicDocsMarkdown = resolvePublicDocsMarkdown(req.method, url.pathname);
+            if (publicDocsMarkdown) {
+                writeMarkdownAsset(res, publicDocsMarkdown);
                 return;
             }
-            if (req.method === 'GET' && url.pathname === '/health') {
+            if (isPublicReadMethod(req.method) && url.pathname === '/health') {
                 writeJson(res, 200, {
                     status: 'ok',
                     service: 'sap-mcp-remote',
                     transport: 'streamable-http',
                     timestamp: new Date().toISOString(),
-                });
+                }, {}, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && url.pathname === MCP_REGISTRY_AUTH_PATH) {
+                writeMcpRegistryAuthRecord(res, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && ['/.well-known/agent-card.json', '/a2a/agent-card'].includes(url.pathname)) {
+                writeJson(res, 200, buildA2AAgentCard(req, this.config), {}, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && ['/.well-known/sap-mcp-wizard.json', '/wizard', '/wizard.json'].includes(url.pathname)) {
+                writeJson(res, 200, buildWizardInstallDescriptor(req, this.config), {}, isHeadMethod(req.method));
                 return;
             }
-            if (req.method === 'GET' && ['/.well-known/agent-card.json', '/a2a/agent-card'].includes(url.pathname)) {
-                writeJson(res, 200, buildA2AAgentCard(req, this.config));
+            if (isPublicReadMethod(req.method) && url.pathname === '/wizard/downloads.json') {
+                const info = buildPublicServerInfo(req, this.config);
+                writeJson(res, 200, info.downloads, {
+                    'Cache-Control': 'public, max-age=300',
+                }, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && url.pathname === '/openapi.json') {
+                writeJson(res, 200, buildOpenApiSpec(req, this.config), {
+                    'Cache-Control': 'public, max-age=300',
+                }, isHeadMethod(req.method));
                 return;
             }
-            if (req.method === 'GET' && ['/.well-known/sap-mcp-wizard.json', '/wizard', '/wizard.json'].includes(url.pathname)) {
-                writeJson(res, 200, buildWizardInstallDescriptor(req, this.config));
+            if (isPublicReadMethod(req.method) && url.pathname === '/pay/provider.yml') {
+                const providerYaml = buildPublicPayShProviderYaml(req, this.config, this.appConfig);
+                writeText(res, 200, providerYaml, 'application/yaml; charset=utf-8', {}, isHeadMethod(req.method));
                 return;
             }
-            if (req.method === 'GET' && url.pathname === '/wizard/install.sh') {
+            if (isPublicReadMethod(req.method) && url.pathname === '/.well-known/x402') {
+                writeJson(res, 200, buildX402DiscoveryDocument(req, this.config), {
+                    'Cache-Control': 'public, max-age=300',
+                }, isHeadMethod(req.method));
+                return;
+            }
+            if (isPublicReadMethod(req.method) && url.pathname === '/wizard/install.sh') {
+                const script = buildWizardInstallScript(req, this.config);
                 res.writeHead(200, {
                     'Content-Type': 'text/x-shellscript; charset=utf-8',
                     'Cache-Control': 'public, max-age=300',
+                    'Content-Length': Buffer.byteLength(script),
                 });
-                res.end(buildWizardInstallScript(req, this.config));
+                res.end(isHeadMethod(req.method) ? undefined : script);
                 return;
             }
-            if (req.method === 'GET' && url.pathname === '/mcp' && acceptsHtmlPreview(req)) {
-                writeHtml(res, 200, buildLandingHtml(req, this.config, 'mcp'));
+            if (isPublicReadMethod(req.method) && url.pathname === '/mcp' && (isHeadMethod(req.method) || acceptsHtmlPreview(req))) {
+                writeHtml(res, 200, buildLandingHtml(req, this.config, 'mcp'), isHeadMethod(req.method));
                 return;
             }
             if (url.pathname !== '/mcp') {
@@ -813,6 +1558,26 @@ export class RemoteMCPServer {
                 });
                 return;
             }
+            // ── Request logging ─────────────────────────────────────────────
+            const reqStart = Date.now();
+            const callerIp = getRateLimitKey(req);
+            const originalEnd = res.end.bind(res);
+            let loggedMethod;
+            let loggedToolNames;
+            res.end = ((...args) => {
+                const latencyMs = Date.now() - reqStart;
+                const statusCode = res.statusCode;
+                logger.info('MCP request', {
+                    method: req.method,
+                    path: url.pathname,
+                    status: statusCode,
+                    latencyMs,
+                    callerIp,
+                    toolNames: loggedToolNames,
+                    rpcMethod: loggedMethod,
+                });
+                return originalEnd(...args);
+            });
             try {
                 if (this.config.stateless) {
                     // Stateless mode: create a fresh transport + server per request.
@@ -824,22 +1589,32 @@ export class RemoteMCPServer {
                     await perRequestServer.connect(perRequestTransport);
                     if (monetizationGate) {
                         await monetizationGate.handle(req, res, async (mcpReq, mcpRes, parsedBody) => {
+                            // Extract tool names from parsed JSON-RPC body for logging
+                            loggedToolNames = extractToolNamesFromJsonRpc(parsedBody);
+                            loggedMethod = extractJsonRpcMethod(parsedBody);
                             await perRequestTransport.handleRequest(mcpReq, mcpRes, parsedBody);
                         });
                     }
                     else {
+                        // Parse body for logging before passing to transport
+                        // The transport will re-read it from the stream
+                        loggedToolNames = undefined; // Will be logged without tool names in free mode
                         await perRequestTransport.handleRequest(req, res);
                     }
                 }
                 else {
-                    // Stateful mode: reuse the long-lived transport.
+                    // Stateful mode: route each request to the transport created by its initialize response.
                     if (monetizationGate) {
                         await monetizationGate.handle(req, res, async (mcpReq, mcpRes, parsedBody) => {
-                            await this.transport?.handleRequest(mcpReq, mcpRes, parsedBody);
+                            loggedToolNames = extractToolNamesFromJsonRpc(parsedBody);
+                            loggedMethod = extractJsonRpcMethod(parsedBody);
+                            await this.handleStatefulMcpRequest(mcpReq, mcpRes, parsedBody);
+                        }, {
+                            validatePaidRequest: context => this.validateStatefulPaidRequest(context.request, context.parsedBody),
                         });
                     }
                     else {
-                        await this.transport?.handleRequest(req, res);
+                        await this.handleStatefulMcpRequest(req, res);
                     }
                 }
             }
@@ -878,7 +1653,9 @@ export class RemoteMCPServer {
      * @description Gracefully closes the MCP transport and HTTP listener.
      */
     async stop() {
-        await this.transport?.close();
+        const sessions = Array.from(this.statefulSessions.values());
+        this.statefulSessions.clear();
+        await Promise.allSettled(sessions.map(session => session.transport.close()));
         if (!this.httpServer) {
             return;
         }
@@ -906,6 +1683,110 @@ export class RemoteMCPServer {
             throw new Error('Remote MCP JWT auth requires SAP_MCP_AUTH_SECRET');
         }
     }
+    /**
+     * @name handleStatefulMcpRequest
+     * @description Routes a stateful MCP request to the session transport created by initialize.
+     */
+    async handleStatefulMcpRequest(req, res, parsedBody) {
+        const transport = await this.resolveStatefulTransport(req, parsedBody);
+        if (!transport) {
+            const providedSessionId = readSingleHeader(req.headers['mcp-session-id']);
+            writeMcpJsonRpcError(res, providedSessionId ? 404 : 400, providedSessionId ? -32011 : -32010, extractJsonRpcId(parsedBody), providedSessionId ? 'mcp_session_not_found' : 'mcp_session_required', {
+                requiredHeader: 'mcp-session-id',
+                ...(providedSessionId ? { providedSessionId } : {}),
+                hint: providedSessionId
+                    ? 'The mcp-session-id must come from this server initialize response. Client-generated UUIDs are not valid MCP sessions.'
+                    : 'Call initialize first and reuse the returned mcp-session-id header. Do not generate a client-side UUID.',
+            });
+            return;
+        }
+        await transport.handleRequest(req, res, parsedBody);
+    }
+    /**
+     * @name validateStatefulPaidRequest
+     * @description Fails paid tool calls before x402 verification when the MCP session is missing or unknown.
+     */
+    validateStatefulPaidRequest(req, parsedBody) {
+        if (isInitializeJsonRpcRequest(parsedBody)) {
+            return undefined;
+        }
+        const sessionId = readSingleHeader(req.headers['mcp-session-id']);
+        if (!sessionId) {
+            return {
+                code: -32010,
+                message: 'mcp_session_required',
+                data: {
+                    requiredHeader: 'mcp-session-id',
+                    hint: 'Initialize the MCP Streamable HTTP session first, then reuse the returned mcp-session-id for the unpaid payment challenge and the paid retry.',
+                },
+            };
+        }
+        if (!this.statefulSessions.has(sessionId)) {
+            return {
+                code: -32011,
+                message: 'mcp_session_not_found',
+                data: {
+                    requiredHeader: 'mcp-session-id',
+                    providedSessionId: sessionId,
+                    hint: 'The mcp-session-id must come from this server initialize response. Client-generated UUIDs are not valid MCP sessions.',
+                },
+            };
+        }
+        return undefined;
+    }
+    /**
+     * @name resolveStatefulTransport
+     * @description Returns the transport for an existing session or creates one for an initialize request.
+     */
+    async resolveStatefulTransport(req, parsedBody) {
+        const sessionId = readSingleHeader(req.headers['mcp-session-id']);
+        if (sessionId) {
+            const session = this.statefulSessions.get(sessionId);
+            if (!session) {
+                return undefined;
+            }
+            session.lastSeenAt = Date.now();
+            return session.transport;
+        }
+        if (req.method === 'POST' && (parsedBody === undefined || isInitializeJsonRpcRequest(parsedBody))) {
+            return await this.createStatefulSessionTransport();
+        }
+        return undefined;
+    }
+    /**
+     * @name createStatefulSessionTransport
+     * @description Creates one MCP server and Streamable HTTP transport for a single initialized session.
+     */
+    async createStatefulSessionTransport() {
+        const server = await createSapMcpServer(this.appConfig);
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: sessionId => {
+                this.statefulSessions.set(sessionId, {
+                    server,
+                    transport,
+                    createdAt: Date.now(),
+                    lastSeenAt: Date.now(),
+                });
+                logger.info('Stateful MCP session initialized', {
+                    sessionId,
+                    activeSessions: this.statefulSessions.size,
+                });
+            },
+        });
+        transport.onclose = () => {
+            const sessionId = transport.sessionId;
+            if (sessionId) {
+                this.statefulSessions.delete(sessionId);
+                logger.info('Stateful MCP session closed', {
+                    sessionId,
+                    activeSessions: this.statefulSessions.size,
+                });
+            }
+        };
+        await server.connect(transport);
+        return transport;
+    }
     /**
      * @name applyCors
      * @description Applies configured CORS headers and handles preflight requests.