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

Why CI rather than publishing from your laptop. mcp-publisher login github grants an org namespace only when GitHub reports you as an org Owner via GET /user/memberships/orgs?state=active — the registry requires role == "admin" (see internal/api/handlers/v0/auth/github_at.go upstream). That lookup returns nothing for this org even though the account is an Owner with public membership and the org's third-party policy is not the cause, so a personal login yields only io.github.<user>/* and the publish fails with 403.

GitHub Actions OIDC sidesteps it: the registry derives the namespace from the repository_owner claim, which is webweaver-nexus for this repo, granting io.github.webweaver-nexus/* directly. The workflow needs id-token: write.

Bump version in server.json before dispatching — the registry rejects a re-publish of an existing version.

Install in your MCP client

All clients connect to the same endpoint:

https://webweaver-nexus-mcp.vercel.app/mcp

Transport is Streamable HTTP. No authentication; all three tools are publicly callable.

Hosts that speak Streamable HTTP natively (claude.ai, ChatGPT, MCP Inspector, basic-host) take the URL directly. stdio-only hosts (Claude Desktop, Cursor today) use the mcp-remote npm shim — a small package that launches as a local stdio process and proxies JSON-RPC to the remote URL.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "webweaver-nexus": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://webweaver-nexus-mcp.vercel.app/mcp"]
    }
  }
}

Restart Claude Desktop; the three tools appear in the tools menu.

The two read-only tools work. join_waitlist renders its App shell — heading, subtitle, host theme — but the embedded Tally form does not load, because Claude Desktop ignores frameDomains; see Hosts that ignore frameDomains. Note this config proxies to the deployed server over HTTP via mcp-remote, so it never exercised the stdio cwd bug fixed in v1.0.1 — that bug only applied to a config launching this server as a local stdio process.

claude.ai (Custom Connector)

claude.ai speaks Streamable HTTP natively — no shim.

1. Open Settings → Connectors (or Feature Preview → MCP, depending on rollout).
2. Add custom connector → paste https://webweaver-nexus-mcp.vercel.app/mcp.
3. Save.

The two read-only tools work. join_waitlist's Tally form is blocked by an upstream frameDomains bug — see Known Limitations.

Cursor

Edit ~/.cursor/mcp.json, or use Settings → MCP Servers in the Cursor UI:

{
  "mcpServers": {
    "webweaver-nexus": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://webweaver-nexus-mcp.vercel.app/mcp"]
    }
  }
}

Reload the Cursor window (Cmd+Shift+P → Reload Window).

ChatGPT

Available on plan tiers that support MCP / custom connectors.

1. Settings → Connectors (or Apps) → Add custom MCP server.
2. Paste https://webweaver-nexus-mcp.vercel.app/mcp.
3. Enable for a conversation.

Verifying the connection (any client)

Ask the host something like:

Use the WebWeaver Nexus connector to get the product overview.

If the tool fires and returns text, the wire is good. For join_waitlist, the embedded Tally form renders directly in the conversation on hosts that have shipped MCP Apps rendering (Inspector Apps tab, basic-host) — see the per-client caveats above for the others.

Known Limitations

Claude Desktop stdio integration — fixed in v1.0.1

Previously: join_waitlist failed under Claude Desktop with ENOENT: no such file or directory, open '/dist/mcp-app.html'. Claude Desktop launches MCP server processes with the working directory set to / on macOS, and server.ts located the bundled HTML via path.join(process.cwd(), "dist", "mcp-app.html"). The cwd field in claude_desktop_config.json was tried as a workaround but is silently ignored on the version tested.

Fix: the Vite build now writes the bundled HTML into generated/mcp-app-html.ts, which server.ts imports as a string constant. Nothing resolves a filesystem path at runtime, so the App resource behaves identically under stdio, local HTTP, and Vercel. Verified by running the server from / and reading the resource over stdio.

Two earlier attempts are preserved in the history for context: a path probe (added in e73484f, reverted in 32dc1aa) that resolved to an unbundled source file on Vercel, and a Vite 8 → 7 downgrade (2e33c8e, reverted in c8ad36d) that chased the wrong cause. The build now fails loudly if the unbundled source HTML is ever inlined by mistake.

MCP Inspector strips allow-same-origin

In Inspector's Apps tab the Tally form renders and text inputs work, but the dropdown has no default and will not open, and the checkboxes cannot be ticked. The form cannot be completed there.

Cause — host-side, not ours. Inspector's sandbox proxy states it in its own source: the app iframe is sandboxed without allow-same-origin, so the app runs under an opaque (null) origin, and allow-same-origin is "always stripped from a server-supplied value". Sandbox flags are inherited by nested iframes, so Tally's own iframe inherits the opaque origin, its client-side JS cannot reach same-origin storage, and its interactive controls fail. Native text inputs need no JS, which is why they still work.

Confirmed by an A/B test: two iframes loading the same Tally embed URL, differing only in allow-same-origin. With the flag, the dropdown carries its default and the controls work; without it, the dropdown shows "Please Select an Option" and the controls are dead — matching Inspector exactly. The same embed works in tools/basic-host (allow-scripts allow-same-origin allow-forms) and on the landing page (no sandbox).

Do not "fix" this with _meta.ui.domain. Inspector does grant allow-same-origin to apps declaring that field, but the spec is explicit that its format is host-dependent ({hash}.claudemcpcontent.com, www-example-com.oaiusercontent.com). The value is assigned by each host, so guessing one satisfies Inspector at the risk of breaking others.

Use Inspector to confirm the App renders and the CSP is honoured. Use tools/basic-host or the live site to exercise the form itself.

Hosts that ignore frameDomains

Affects claude.ai custom connectors and Claude Desktop. Both render the join_waitlist App shell correctly but leave the Tally form as blank space: the host ignores the frameDomains we declare in _meta.ui.csp, so the nested tally.so iframe is blocked. Upstream issue anthropics/claude-ai-mcp#40. The two read-only tools are unaffected.

Claude Desktop is the same stack — its initialize sends clientInfo.name: "claude-ai (via mcp-remote …)" — so it inherits the same bug. It does advertise MCP Apps support (extensions["io.modelcontextprotocol/ui"] with text/html;profile=mcp-app), and the MCP log shows resources/read and tools/call both returning normally, which is why this presents as a rendering failure rather than a protocol one.

Confirmed from Claude Desktop's DevTools console:

Framing 'https://tally.so/' violates the following Content Security Policy
directive: "frame-src 'self' blob: data:". The request has been blocked.

Only frameDomains is dropped — the other two declarations survive. The App frame is loaded with them in its query string:

mcp_apps?connect-src=https%3A%2F%2Ftally.so&resource-src=https%3A%2F%2Ftally.so+https%3A%2F%2Fassets.claude.ai

There is no frame-src parameter, so the policy falls back to frame-src 'self' blob: data:. Tally's loader does run (iframe-resizer v5.5.9 appears in the console) and the app requests the correct embed URL — the host blocks the frame, nothing upstream of it. Identical on both transports, mcp-remote over HTTP and a local stdio config, as expected for a renderer-side block.

Don't attempt to work around it server-side — there is nothing to fix in this repo.

The wider pattern. Every host that has been tried degrades the third-party embed somehow: Inspector strips allow-same-origin so Tally's controls die, and these two block the frame outright. Only tools/basic-host and the landing page render it fully. If join_waitlist needs to work in Anthropic's own clients, the durable answer is a native form in the App posting to Tally's API — connectDomains already permits tally.so — rather than embedding Tally's iframe.

Project Structure

├── api/ │ └── mcp.ts # Vercel serverless entry — exports Express app ├── main.ts # Local-dev entry — HTTP & stdio transports ├── server.ts # Tool & resource registration (shared) ├── mcp-app.html # App UI template (Vite entry, source) ├── src/ │ ├── mcp-app.ts # Client-side App lifecycle + Tally integration │ ├── mcp-app.css # App-specific styles │ └── global.css # Host variable fallbacks & reset ├── tools/ │ └── basic-host/ # Vendored MCP host harness (model context updates) ├── generated/ # Build artifact — bundled HTML as a TS constant (git-ignored) ├── dist/ # Build output — function code + bundled mcp-app.html ├── vite.config.ts # Vite + singlefile plugin config ├── tsconfig.json # Client + shared type-checking ├── tsconfig.server.json # Server declaration emit ├── vercel.json # Vercel deployment config └── package.json

Version History

• v1.0.2 — Fixed join_waitlist rendering an empty panel in every host: the app loaded Tally's embed.js but never called Tally.loadEmbeds(), so the form iframe was never given a src. Also guards updateModelContext behind the host capability, and vendors the basic-host harness into tools/basic-host/ so the ext-apps clone is no longer needed.
• v1.0.1 — join_waitlist now works over stdio (Claude Desktop). The App HTML is compiled into the server instead of read from disk, removing the process.cwd() dependency. Rate limiting is now per-client: trust proxy was unset, so every caller shared a single 60/min bucket behind Vercel's proxy. Host validation now accepts Vercel preview deployments and *.trycloudflare.com, which the documented tunnel workflow needs. Dependencies updated to clear all npm audit advisories (MCP SDK 1.29 → 1.30).
• v1.0.0 — Published to the official MCP registry as io.github.webweaver-nexus/webweaver-mcp-server. Endpoint hardened with a CORS allowlist and rate limiting.
• v0.1.0 — First working production deployment. Three tools live; join_waitlist works on Streamable HTTP hosts. Claude Desktop stdio integration deferred.