WebWeaver Nexus MCP Server

An MCP server that exposes WebWeaver Nexus services — waitlist signup (with an embedded form UI), product overview, and contact info — to MCP-enabled hosts (Claude Desktop, claude.ai, ChatGPT, Cursor, MCP Inspector, basic-host).

Production URL: https://webweaver-nexus-mcp.vercel.app/mcp — Streamable HTTP, public, no authentication.

Published to the official MCP registry as io.github.webweaver-nexus/webweaver-mcp-server. See Publishing to the MCP registry.

Tools

Prerequisites

• Node.js 24.x (see engines in package.json)
• npm

engines pins 24.x deliberately: Vercel selects the function runtime from it. Newer local Node majors work fine but make npm print an EBADENGINE warning.

Install

npm install

Build

npm run build

This bundles the MCP App UI with Vite + vite-plugin-singlefile, type-checks the client and server, and emits the compiled server.

The Vite step runs first and is load-bearing: a build plugin writes the bundled HTML into generated/mcp-app-html.ts, which server.ts imports. The server type-check would fail without it. generated/ is a build artifact and is git-ignored.

During npm run dev, the watch build regenerates that module on every client change, but npm run serve loads it once at startup — restart the server to pick up UI edits.

Run

# HTTP transport (default, port 3001)
npm run serve

# Custom port
PORT=4000 npm run serve

# stdio transport (for Claude Desktop local config)
npm run serve:stdio

# Dev mode (watch + serve)
npm run dev

The server listens at http://localhost:3001/mcp by default.

Configuration

Before deploying, update the Tally form ID:

1. Open src/mcp-app.ts
2. Replace the form ID constant with your real Tally form ID
3. Also update the data-tally-src URL in mcp-app.html to match

Tally's embed.js does not populate embeds by itself — src/mcp-app.ts has to call window.Tally.loadEmbeds() once the script loads, or the iframe keeps its data-tally-src, never gets a src, and the form silently renders as blank space.

Two settings keep the form readable in dark hosts and should be changed together: transparentBackground=0 in the data-tally-src URL, and color-scheme: light on #tally-container in src/mcp-app.css. Tally's form styling does not follow the host theme, so with a transparent background its labels and inputs end up dark-on-dark. This mirrors the fix applied to the landing page embed.

Testing with MCP Inspector (default harness)

MCP Inspector is the official MCP debugger and the right tool for almost every check here. Verified against v2.5.0.

npx @modelcontextprotocol/inspector

The web UI opens on port 6274. Set:

• Transport Type: Streamable HTTP
• Connection Type: Via Proxy or Direct — both work. Proxy routes JSON-RPC through Inspector's local proxy (port 6277); Direct goes browser → server.
• URL: http://localhost:3001/mcp (local) or https://webweaver-nexus-mcp.vercel.app/mcp (production)

Click Connect, then verify across tabs:

1. Tools — all 3 tools appear (join_waitlist, get_product_overview, get_contact_info); the two plain tools return their text when called.
2. Resources — ui://join-waitlist/mcp-app.html lists; reading it returns ~435 KB of bundled HTML.
3. Apps — select join_waitlist; the Tally form renders inside its sandboxed iframe. Inspector builds a real CSP from our _meta.ui.csp, so this genuinely exercises resourceDomains / frameDomains / connectDomains. The form renders here but is not fully interactive — see Inspector strips allow-same-origin below.

There is also a CLI, which makes post-deploy checks scriptable without a browser:

npx @modelcontextprotocol/inspector --cli --transport http \
  --server-url https://webweaver-nexus-mcp.vercel.app/mcp --method tools/list

# App metadata for a UI tool
npx @modelcontextprotocol/inspector --cli --transport http \
  --server-url https://webweaver-nexus-mcp.vercel.app/mcp \
  --method tools/call --tool-name join_waitlist --app-info

The one thing Inspector cannot do: accept ui/update-model-context. As of v2.5.0 it never registers an onupdatemodelcontext handler and never declares the capability, so app.updateModelContext() has nowhere to land. Use basic-host for that one check.

Testing with basic-host (model context updates)

A vendored copy of the MCP Apps basic-host harness lives in tools/basic-host/. It is the only local host that declares the updateModelContext capability and renders a 📋 Model Context panel, which is how you confirm the waitlist form actually notifies the host model after submission.

# once
cd tools/basic-host && npm install && npm run build

# Terminal 1 — the server under test
npm run build && npm run serve

# Terminal 2 — the harness
cd tools/basic-host && SERVERS='["http://localhost:3001/mcp"]' npm run serve
# Open http://localhost:8080

Against production instead:

cd tools/basic-host && SERVERS='["https://webweaver-nexus-mcp.vercel.app/mcp"]' npm run serve

SERVERS is a JSON array, and ports 8080/8081 are effectively fixed — see tools/basic-host/README.md for provenance and the full set of caveats.

The Model Context panel stays hidden until the first update arrives, which for join_waitlist means a real Tally submission — it creates a live waitlist entry and fires notification emails. Use a throwaway entry.

When to use which

Exposing local dev to claude.ai (Cloudflare tunnel)

For iterating on the server locally against claude.ai's custom connector UI (which only accepts public HTTPS URLs, not localhost), expose your dev server via a Cloudflare tunnel:

# Terminal 1 — run the server
npm run build && npm run serve

# Terminal 2 — start the tunnel
npx cloudflared tunnel --url http://localhost:3001

Copy the https://*.trycloudflare.com URL from the tunnel output. In Claude's settings, add a custom MCP connector pointing to https://<tunnel-url>/mcp.

*.trycloudflare.com is allowlisted by the Host header check in api/mcp.ts — cloudflared forwards the public hostname rather than localhost, so without that entry every tunnelled request is rejected with 403 Invalid Host.

Note: As of writing, claude.ai's custom connectors ignore frameDomains declared in _meta.ui.csp (see GitHub issue anthropics/claude-ai-mcp#40). This will cause the Tally embed in join_waitlist to be blocked. The two read-only tools work correctly. Track that issue for the fix.

Deployment (Vercel)

The MCP server is deployed as a Vercel serverless function using the Express + Streamable HTTP pattern.

How it works:

• vercel.json routes traffic to api/mcp.ts, which exports the Express app as default.
• The Vite-bundled MCP App UI is compiled into the function as a string constant (generated/mcp-app-html.ts), so no file is read from disk at runtime.
• The function runs on Vercel's Node.js 24 runtime with maxDuration: 60 (well above what's needed; tool calls return in milliseconds).
• No environment variables are required — all configuration is hardcoded in the source.

To redeploy: Push to the main branch. Vercel auto-deploys on push.

To verify the deployment:

# Sanity check — should return a JSON-RPC tools list (~880 bytes)
curl -X POST https://webweaver-nexus-mcp.vercel.app/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Resource read — should return ~435 KB of bundled HTML.
# A response under a few KB means the unbundled source HTML was inlined
# instead of the bundle (the build guards against this — see git history).
curl -X POST https://webweaver-nexus-mcp.vercel.app/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"resources/read","params":{"uri":"ui://join-waitlist/mcp-app.html"},"id":1}' \
  | wc -c

For an interactive equivalent, run MCP Inspector against the deployed URL (see Testing with MCP Inspector above). Recommended as the first post-deploy check before bringing up basic-host.

Publishing to the MCP registry

The registry entry is io.github.webweaver-nexus/webweaver-mcp-server, defined by server.json. Publishing is manual dispatch only — run the Publish to MCP Registry workflow from the Actions tab.

# validate locally before dispatching
mcp-publisher validate