web3-tools-mcp 1.6.0 → 2.0.0

package/src/chain-meta.ts

@@ -3,8 +3,9 @@
  * human labels for addresses. Kept apart from the preview and the clear-signing registry
  * so both can use it without importing each other.
  */
-import { type Abi, type Address, parseAbiItem } from 'viem'
+
 import { whatsabi } from '@shazow/whatsabi'
+import { type Abi, type Address, parseAbiItem } from 'viem'
 import { getClientManager } from './client.js'
 import type { ChainName } from './types.js'
 
@@ -26,7 +27,9 @@ export async function loadAbi(chain: ChainName, address: string) {
   const client = clientManager.getClient(chain)
   const etherscanApiKey = clientManager.getConfig().etherscanApiKey
 
-  const loaders: whatsabi.loaders.ABILoader[] = [new whatsabi.loaders.SourcifyABILoader({ chainId: clientManager.getChainId(chain) })]
+  const loaders: whatsabi.loaders.ABILoader[] = [
+    new whatsabi.loaders.SourcifyABILoader({ chainId: clientManager.getChainId(chain) })
+  ]
   if (etherscanApiKey) {
     loaders.push(new whatsabi.loaders.EtherscanV2ABILoader({ apiKey: etherscanApiKey, chainId: clientManager.getChainId(chain) }))
   }
@@ -83,7 +86,9 @@ export async function addressLabel(chain: ChainName, address: string): Promise<s
 
   let label: string | undefined
   try {
-    const code = await getClientManager().getClient(chain).getBytecode({ address: address as Address })
+    const code = await getClientManager()
+      .getClient(chain)
+      .getBytecode({ address: address as Address })
     if (code && code !== '0x') {
       label = (await tokenMeta(chain, address).catch(() => ({ symbol: undefined }))).symbol
       if (!label) label = (await loadAbi(chain, address)).name
@@ -96,7 +101,6 @@ export async function addressLabel(chain: ChainName, address: string): Promise<s
   return label
 }
 
-
 /** uint256 max and anything near it means "infinite" in an approval. */
 export const MAX_UINT256 = (1n << 256n) - 1n
 export const UNLIMITED_THRESHOLD = MAX_UINT256 / 2n

package/src/chains.ts

@@ -0,0 +1,145 @@
+import type { Chain } from 'viem'
+import {
+  arbitrum,
+  avalanche,
+  base,
+  bsc,
+  gnosis,
+  linea,
+  localhost,
+  mainnet,
+  optimism,
+  polygon,
+  sonic,
+  unichain,
+  zksync
+} from 'viem/chains'
+
+/**
+ * Every chain this server knows, in one table. Adding one here is the whole change: the
+ * `ChainName` union, the tool schemas, RPC selection, explorer links, Hypersync routing and
+ * the `--help` listing are all derived from it.
+ */
+interface ChainInfo {
+  chain: Chain
+  /** Subdomain under g.alchemy.com; absent where Alchemy has no endpoint. */
+  alchemy?: string
+  /** Subdomain under infura.io; absent where Infura has no endpoint. */
+  infura?: string
+  /** Used when no provider key is configured. */
+  fallback: string
+  /** Block explorer domain, for links. Absent where there is nothing to link to. */
+  explorer?: string
+  hypersync?: string
+}
+
+const TABLE = {
+  mainnet: {
+    chain: mainnet,
+    alchemy: 'eth-mainnet',
+    infura: 'mainnet',
+    fallback: 'https://ethereum-rpc.publicnode.com',
+    explorer: 'etherscan.io',
+    hypersync: 'https://eth.hypersync.xyz'
+  },
+  arbitrum: {
+    chain: arbitrum,
+    alchemy: 'arb-mainnet',
+    infura: 'arbitrum-mainnet',
+    fallback: 'https://arb1.arbitrum.io/rpc',
+    explorer: 'arbiscan.io',
+    hypersync: 'https://arbitrum.hypersync.xyz'
+  },
+  avalanche: {
+    chain: avalanche,
+    alchemy: 'avax-mainnet',
+    infura: 'avalanche-mainnet',
+    fallback: 'https://api.avax.network/ext/bc/C/rpc',
+    explorer: 'snowtrace.io',
+    hypersync: 'https://avalanche.hypersync.xyz'
+  },
+  base: {
+    chain: base,
+    alchemy: 'base-mainnet',
+    // publicnode refuses receipts and anything else it calls an archive request
+    fallback: 'https://mainnet.base.org',
+    explorer: 'basescan.org',
+    hypersync: 'https://base.hypersync.xyz'
+  },
+  bnb: {
+    chain: bsc,
+    alchemy: 'bnb-mainnet',
+    infura: 'bsc-mainnet',
+    fallback: 'https://bsc-dataseed.bnbchain.org',
+    explorer: 'bscscan.com',
+    hypersync: 'https://bsc.hypersync.xyz'
+  },
+  gnosis: {
+    chain: gnosis,
+    alchemy: 'gnosis-mainnet',
+    fallback: 'https://rpc.gnosischain.com',
+    explorer: 'gnosisscan.io',
+    hypersync: 'https://gnosis.hypersync.xyz'
+  },
+  sonic: {
+    chain: sonic,
+    alchemy: 'sonic-mainnet',
+    fallback: 'https://rpc.soniclabs.com',
+    explorer: 'sonicscan.org',
+    hypersync: 'https://sonic.hypersync.xyz'
+  },
+  optimism: {
+    chain: optimism,
+    alchemy: 'opt-mainnet',
+    infura: 'optimism-mainnet',
+    fallback: 'https://mainnet.optimism.io',
+    explorer: 'optimistic.etherscan.io',
+    hypersync: 'https://optimism.hypersync.xyz'
+  },
+  polygon: {
+    chain: polygon,
+    alchemy: 'polygon-mainnet',
+    infura: 'polygon-mainnet',
+    // polygon-rpc.com now answers 401 "API key disabled" to anonymous callers
+    fallback: 'https://polygon-bor-rpc.publicnode.com',
+    explorer: 'polygonscan.com',
+    hypersync: 'https://polygon.hypersync.xyz'
+  },
+  zksync: {
+    chain: zksync,
+    alchemy: 'zksync-mainnet',
+    infura: 'zksync-mainnet',
+    fallback: 'https://mainnet.era.zksync.io',
+    explorer: 'era.zksync.network',
+    hypersync: 'https://zksync.hypersync.xyz'
+  },
+  linea: {
+    chain: linea,
+    alchemy: 'linea-mainnet',
+    infura: 'linea-mainnet',
+    fallback: 'https://rpc.linea.build',
+    explorer: 'lineascan.build',
+    hypersync: 'https://linea.hypersync.xyz'
+  },
+  unichain: {
+    chain: unichain,
+    alchemy: 'unichain-mainnet',
+    infura: 'unichain-mainnet',
+    fallback: 'https://mainnet.unichain.org',
+    explorer: 'uniscan.xyz',
+    hypersync: 'https://unichain.hypersync.xyz'
+  },
+  localhost: {
+    chain: localhost,
+    fallback: 'http://localhost:8545'
+  }
+} as const satisfies Record<string, ChainInfo>
+
+export type ChainName = keyof typeof TABLE
+
+// Widened: `as const` above is only there to infer ChainName from the keys, and reading a
+// literal entry would otherwise lose the fields that not every chain sets.
+export const CHAINS: Record<ChainName, ChainInfo> = TABLE
+
+/** Tuple rather than array, because `z.enum` needs a non-empty literal list. */
+export const SUPPORTED_CHAINS = Object.keys(CHAINS) as [ChainName, ...ChainName[]]

package/src/client.ts

@@ -1,280 +1,65 @@
-import { http, createPublicClient } from 'viem'
-import {
-  arbitrum,
-  avalanche,
-  base,
-  bsc,
-  gnosis,
-  linea,
-  localhost,
-  mainnet,
-  optimism,
-  polygon,
-  sonic,
-  unichain,
-  zksync
-} from 'viem/chains'
-import type { ChainName, Config } from './types.js'
+import { createPublicClient, http } from 'viem'
+import { CHAINS, type ChainName } from './chains.js'
+import type { Config } from './types.js'
 
-// Enhanced RPC configuration with API keys
-function getRpcUrl(chainName: string, config: Config): string {
-  // Check for custom RPC URLs first
-  if (config.customRpcUrls?.[chainName]) {
-    return config.customRpcUrls[chainName]
-  }
-
-  // Enhanced RPC URLs with API keys
-  const enhancedRpcs: Record<string, string> = {
-    mainnet: config.alchemyApiKey
-      ? `https://eth-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
-      : config.infuraApiKey
-        ? `https://mainnet.infura.io/v3/${config.infuraApiKey}`
-        : 'https://ethereum-rpc.publicnode.com',
-
-    base: config.alchemyApiKey
-      ? `https://base-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
-      // publicnode refuses receipts and anything else it calls an archive request
-      : 'https://mainnet.base.org',
-
-    arbitrum: config.alchemyApiKey
-      ? `https://arb-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
-      : config.infuraApiKey
-        ? `https://arbitrum-mainnet.infura.io/v3/${config.infuraApiKey}`
-        : 'https://arb1.arbitrum.io/rpc',
-
-    polygon: config.alchemyApiKey
-      ? `https://polygon-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
-      : config.infuraApiKey
-        ? `https://polygon-mainnet.infura.io/v3/${config.infuraApiKey}`
-        // polygon-rpc.com now answers 401 "API key disabled" to anonymous callers
-        : 'https://polygon-bor-rpc.publicnode.com',
-
-    optimism: config.alchemyApiKey
-      ? `https://opt-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
-      : config.infuraApiKey
-        ? `https://optimism-mainnet.infura.io/v3/${config.infuraApiKey}`
-        : 'https://mainnet.optimism.io',
-
-    avalanche: config.alchemyApiKey
-      ? `https://avax-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
-      : config.infuraApiKey
-        ? `https://avalanche-mainnet.infura.io/v3/${config.infuraApiKey}`
-        : 'https://api.avax.network/ext/bc/C/rpc',
+export { SUPPORTED_CHAINS } from './chains.js'
 
-    bnb: config.alchemyApiKey
-      ? `https://bnb-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
-      : config.infuraApiKey
-        ? `https://bsc-mainnet.infura.io/v3/${config.infuraApiKey}`
-        : 'https://bsc-dataseed.bnbchain.org',
+/** Custom URL first, then whichever provider key is configured, then the public endpoint. */
+function getRpcUrl(chainName: ChainName, config: Config): string {
+  const custom = config.customRpcUrls?.[chainName]
+  if (custom) return custom
 
-    gnosis: config.alchemyApiKey
-      ? `https://gnosis-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
-      : 'https://rpc.gnosischain.com',
-
-    sonic: config.alchemyApiKey
-      ? `https://sonic-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
-      : 'https://rpc.soniclabs.com',
-
-    zksync: config.alchemyApiKey
-      ? `https://zksync-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
-      : config.infuraApiKey
-        ? `https://zksync-mainnet.infura.io/v3/${config.infuraApiKey}`
-        : 'https://mainnet.era.zksync.io',
-
-    linea: config.alchemyApiKey
-      ? `https://linea-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
-      : config.infuraApiKey
-        ? `https://linea-mainnet.infura.io/v3/${config.infuraApiKey}`
-        : 'https://rpc.linea.build',
-
-    unichain: config.alchemyApiKey
-      ? `https://unichain-mainnet.g.alchemy.com/v2/${config.alchemyApiKey}`
-      : config.infuraApiKey
-        ? `https://unichain-mainnet.infura.io/v3/${config.infuraApiKey}`
-        : 'https://sepolia.unichain.org',
-
-    localhost: 'http://localhost:8545'
-  }
-
-  return enhancedRpcs[chainName] ?? 'https://eth.llamarpc.com'
+  const { alchemy, infura, fallback } = CHAINS[chainName]
+  if (alchemy && config.alchemyApiKey) return `https://${alchemy}.g.alchemy.com/v2/${config.alchemyApiKey}`
+  if (infura && config.infuraApiKey) return `https://${infura}.infura.io/v3/${config.infuraApiKey}`
+  return fallback
 }
 
-// Supported chains with their RPC endpoints (now dynamic)
-export const CHAINS = (config: Config) => ({
-  mainnet: {
-    chain: mainnet,
-    get rpc() {
-      return getRpcUrl('mainnet', config)
-    }
-  },
-  base: {
-    chain: base,
-    get rpc() {
-      return getRpcUrl('base', config)
-    }
-  },
-  arbitrum: {
-    chain: arbitrum,
-    get rpc() {
-      return getRpcUrl('arbitrum', config)
-    }
-  },
-  polygon: {
-    chain: polygon,
-    get rpc() {
-      return getRpcUrl('polygon', config)
-    }
-  },
-  optimism: {
-    chain: optimism,
-    get rpc() {
-      return getRpcUrl('optimism', config)
-    }
-  },
-  avalanche: {
-    chain: avalanche,
-    get rpc() {
-      return getRpcUrl('avalanche', config)
-    }
-  },
-  bnb: {
-    chain: bsc,
-    get rpc() {
-      return getRpcUrl('bnb', config)
-    }
-  },
-  gnosis: {
-    chain: gnosis,
-    get rpc() {
-      return getRpcUrl('gnosis', config)
-    }
-  },
-  sonic: {
-    chain: sonic,
-    get rpc() {
-      return getRpcUrl('sonic', config)
-    }
-  },
-  zksync: {
-    chain: zksync,
-    get rpc() {
-      return getRpcUrl('zksync', config)
-    }
-  },
-  linea: {
-    chain: linea,
-    get rpc() {
-      return getRpcUrl('linea', config)
-    }
-  },
-  unichain: {
-    chain: unichain,
-    get rpc() {
-      return getRpcUrl('unichain', config)
-    }
-  },
-  localhost: {
-    chain: localhost,
-    get rpc() {
-      return getRpcUrl('localhost', config)
-    }
-  }
-})
+/** Named so declaration emit can refer to it: node_modules is hoisted above this package. */
+type PublicClient = ReturnType<typeof createPublicClient>
 
-// Hypersync URLs for supported chains (localhost is not supported)
-export const HYPERSYNC_URLS: Partial<Record<ChainName, string>> = {
-  mainnet: 'https://eth.hypersync.xyz', // Chain ID 1
-  arbitrum: 'https://arbitrum.hypersync.xyz', // Chain ID 42161
-  avalanche: 'https://avalanche.hypersync.xyz', // Chain ID 43114
-  base: 'https://base.hypersync.xyz', // Chain ID 8453
-  bnb: 'https://bsc.hypersync.xyz', // Chain ID 56
-  gnosis: 'https://gnosis.hypersync.xyz', // Chain ID 100
-  sonic: 'https://sonic.hypersync.xyz', // Chain ID 146
-  optimism: 'https://optimism.hypersync.xyz', // Chain ID 10
-  polygon: 'https://polygon.hypersync.xyz', // Chain ID 137
-  zksync: 'https://zksync.hypersync.xyz', // Chain ID 324
-  linea: 'https://linea.hypersync.xyz', // Chain ID 59144
-  unichain: 'https://unichain.hypersync.xyz' // Chain ID 130
-  // localhost is not supported by hypersync
-}
+export class ClientManager {
+  private clients = new Map<ChainName, PublicClient>()
 
-export const SUPPORTED_CHAINS = [
-  'mainnet',
-  'arbitrum',
-  'avalanche',
-  'base',
-  'bnb',
-  'gnosis',
-  'sonic',
-  'optimism',
-  'polygon',
-  'zksync',
-  'linea',
-  'unichain',
-  'localhost'
-] as const
+  constructor(private config: Config) {}
 
-// Client manager
-export class ClientManager {
-  private clients: Map<ChainName, unknown> = new Map()
-  private config: Config
+  getClient(chainName: ChainName): PublicClient {
+    const cached = this.clients.get(chainName)
+    if (cached) return cached
 
-  constructor(config: Config) {
-    this.config = config
-  }
+    // Cast because a client built for a concrete chain is not assignable to the generic one.
+    const client = createPublicClient({
+      chain: CHAINS[chainName].chain,
+      transport: http(this.getRpcUrl(chainName))
+    }) as PublicClient
 
-  getClient(chainName: ChainName) {
-    if (!this.clients.has(chainName)) {
-      const chains = CHAINS(this.config)
-      const { chain, rpc } = chains[chainName]
-      const client = createPublicClient({
-        chain,
-        transport: http(rpc)
-      })
-      this.clients.set(chainName, client)
-    }
-    const client = this.clients.get(chainName)
-    if (!client) {
-      throw new Error(`Failed to create client for chain: ${chainName}`)
-    }
-    return client as ReturnType<typeof createPublicClient>
+    this.clients.set(chainName, client)
+    return client
   }
 
   getConfig(): Config {
     return this.config
   }
 
-  getEtherscanDomain(chainName: ChainName): string {
-    const domains: Record<ChainName, string> = {
-      mainnet: 'etherscan.io',
-      base: 'basescan.org',
-      arbitrum: 'arbiscan.io',
-      polygon: 'polygonscan.com',
-      optimism: 'optimistic.etherscan.io',
-      avalanche: 'snowtrace.io',
-      bnb: 'bscscan.com',
-      gnosis: 'gnosisscan.io',
-      sonic: 'sonicscan.org',
-      zksync: 'era.zksync.network',
-      linea: 'lineascan.build',
-      unichain: 'uniscan.xyz',
-      localhost: 'etherscan.io'
-    }
-    return domains[chainName] || 'etherscan.io'
-  }
-
   getRpcUrl(chainName: ChainName): string {
-    const chains = CHAINS(this.config)
-    return chains[chainName].rpc
+    return getRpcUrl(chainName, this.config)
   }
 
   getChainId(chainName: ChainName): number {
-    const chains = CHAINS(this.config)
-    return chains[chainName].chain.id
+    return CHAINS[chainName].chain.id
+  }
+
+  getHypersyncUrl(chainName: ChainName): string | undefined {
+    return CHAINS[chainName].hypersync
+  }
+
+  /** Undefined where the chain has no explorer — a local node, for one. */
+  explorerUrl(chainName: ChainName, path = ''): string | undefined {
+    const domain = CHAINS[chainName].explorer
+    return domain ? `https://${domain}${path}` : undefined
   }
 }
 
-// Export a global client manager instance
 let clientManager: ClientManager | null = null
 
 export function initializeClientManager(config: Config): ClientManager {

package/src/http-server.ts

@@ -1,12 +1,20 @@
-import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
-import { timingSafeEqual } from 'node:crypto'
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js'
+import { getOAuthProtectedResourceMetadataUrl, mcpAuthRouter } from '@modelcontextprotocol/sdk/server/auth/router.js'
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import express from 'express'
+import type { WalletRelay } from 'web3-wallet-relay'
+import { SingleUserOAuthProvider } from './oauth.js'
 
 /**
  * Serve the MCP over HTTP instead of stdio, so the server can live somewhere other than the
- * machine running the agent. Only worth doing alongside WalletConnect: a hosted server has
- * no browser to open, so a phone wallet is the only way it can have anything signed.
+ * machine running the agent. Signing still reaches you: a paired phone over WalletConnect,
+ * or the signing page, which is mounted on this same server so one platform port carries
+ * both it and /mcp.
+ *
+ * Two ways in, because clients differ: a static `Authorization: Bearer <MCP_TOKEN>` header
+ * (Claude Code), and the OAuth flow the MCP spec defines (claude.ai connectors, which offer
+ * no way to send a header). Both end up at the same single credential.
  *
  * Stateless — a server per request — because every tool here is a one-shot call and the
  * signing state lives in the WalletConnect session, not in the transport.
@@ -14,28 +22,20 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 
 const DEFAULT_PORT = 3457
 
-function unauthorized(res: ServerResponse) {
-  res.writeHead(401, { 'content-type': 'application/json', 'www-authenticate': 'Bearer' })
-  res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32001, message: 'Unauthorized' } }))
-}
-
-/** Constant-time compare, so the token cannot be guessed a character at a time. */
-function tokenMatches(presented: string, expected: string): boolean {
-  const a = Buffer.from(presented)
-  const b = Buffer.from(expected)
-  return a.length === b.length && timingSafeEqual(a, b)
-}
-
 export interface HttpServerOptions {
   port?: number
   host?: string
   token?: string
+  /** Public URL clients reach this server on; OAuth metadata must advertise it. */
+  publicUrl?: string
+  /** Serve the signing page on this same server, so browser signing works when hosted. */
+  walletRelay?: WalletRelay
   createMcpServer: () => McpServer
 }
 
-export async function startHttpServer(options: HttpServerOptions): Promise<{ url: string; port: number }> {
+export async function startHttpServer(options: HttpServerOptions): Promise<{ url: string; port: number; walletUrl?: string }> {
   const port = options.port ?? Number(process.env.MCP_HTTP_PORT) ?? DEFAULT_PORT
-  const host = options.host ?? process.env.HOST ?? (process.env.MCP_HTTP_HOST ? process.env.MCP_HTTP_HOST : '0.0.0.0')
+  const host = options.host ?? process.env.MCP_HTTP_HOST ?? '0.0.0.0'
   const token = options.token ?? process.env.MCP_TOKEN
 
   // A reachable MCP server with a paired phone can push signing prompts at that phone. It
@@ -44,24 +44,41 @@ export async function startHttpServer(options: HttpServerOptions): Promise<{ url
     throw new Error('MCP_TOKEN is required to serve MCP over HTTP — anyone reaching the URL could request signatures')
   }
 
-  const server = createServer(async (req: IncomingMessage, res: ServerResponse) => {
-    if (req.url === '/health') {
-      res.writeHead(200, { 'content-type': 'application/json' })
-      res.end(JSON.stringify({ status: 'ok' }))
-      return
-    }
+  const publicUrl = options.publicUrl ?? process.env.MCP_PUBLIC_URL ?? `http://localhost:${port}`
+  const issuer = new URL(publicUrl)
+  const provider = new SingleUserOAuthProvider(token)
 
-    if (!req.url?.startsWith('/mcp')) {
-      res.writeHead(404).end()
-      return
-    }
+  const app = express()
+  app.use(express.json())
+  // The login form posts a token, so the authorize route needs form bodies too.
+  app.use(express.urlencoded({ extended: false }))
 
-    const presented = req.headers.authorization?.replace(/^Bearer /i, '') ?? ''
-    if (!tokenMatches(presented, token)) {
-      unauthorized(res)
-      return
-    }
+  app.get('/health', (_req, res) => {
+    res.json({ status: 'ok' })
+  })
 
+  // /authorize, /token, /register, /revoke and the metadata documents a client discovers
+  // after a 401.
+  app.use(
+    mcpAuthRouter({
+      provider,
+      issuerUrl: issuer,
+      baseUrl: issuer,
+      resourceServerUrl: new URL('/mcp', issuer),
+      resourceName: 'web3-tools-mcp',
+      scopesSupported: []
+    })
+  )
+
+  // The metadata document is mounted under the resource path, so the 401 has to advertise
+  // that exact URL — a bare /.well-known/oauth-protected-resource 404s, and a client that
+  // follows it gives up right where discovery should have started.
+  const authenticate = requireBearerAuth({
+    verifier: provider,
+    resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(new URL('/mcp', issuer))
+  })
+
+  app.all('/mcp', authenticate, async (req, res) => {
     const mcp = options.createMcpServer()
     const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true })
 
@@ -72,23 +89,29 @@ export async function startHttpServer(options: HttpServerOptions): Promise<{ url
 
     try {
       await mcp.connect(transport)
-      await transport.handleRequest(req, res)
+      await transport.handleRequest(req, res, req.body)
     } catch (error) {
       console.error('[MCP] Request failed:', error)
       if (!res.headersSent) {
-        res.writeHead(500, { 'content-type': 'application/json' })
-        res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32603, message: 'Internal error' } }))
+        res.status(500).json({ jsonrpc: '2.0', error: { code: -32603, message: 'Internal error' } })
       }
     }
   })
 
-  await new Promise<void>((resolve, reject) => {
-    server.once('error', reject)
-    server.listen(port, host, () => {
-      server.removeListener('error', reject)
-      resolve()
-    })
+  const server = await new Promise<ReturnType<typeof app.listen>>((resolve, reject) => {
+    const listening = app.listen(port, host, () => resolve(listening))
+    listening.once('error', reject)
   })
 
-  return { url: `http://${host}:${port}/mcp`, port }
+  // The signing page rides on this same server, so a hosted deployment can offer browser
+  // signing without a second service: one platform port serves both /mcp and the page.
+  // Mounted last, so the routes above keep their paths — the relay only claims what is
+  // left, which is the static page at the root.
+  let walletUrl: string | undefined
+  if (options.walletRelay) {
+    options.walletRelay.attach(server, (relayApp) => app.use(relayApp))
+    walletUrl = `${publicUrl.replace(/\/$/, '')}/#t=${options.walletRelay.token}`
+  }
+
+  return { url: `${publicUrl.replace(/\/$/, '')}/mcp`, port: (server.address() as { port: number }).port, walletUrl }
 }