Webweaver MCP Server

WebWeaver Nexus MCP Server

An MCP server that exposes WebWeaver Nexus services — a contact form (rendered as an interactive MCP App), 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.

The bare hostname serves a static signposting page (public/index.html). Only /mcp is routed to the function, so opening the endpoint itself in a browser returns 406 Not Acceptable — that is correct content negotiation, not a fault.

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

Tools

The form is rendered in the App's own document and makes no external requests. It submits through the MCP bridge (app.callServerTool) to submit_contact_form, which POSTs server-to-server to the landing page's /api/contact with a bearer secret. That shape is why it works where the previous Tally iframe did not — see Known Limitations.

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

Environment variables

Two, both for the contact API, both read only in server.ts. Copy .env.example to .env for local development.

The secret must never reach the client bundle. src/mcp-app.ts is compiled into a single ~246 KB HTML string served to every user. After any build:

grep -c 'CONTACT_FORM_SHARED_SECRET' generated/mcp-app-html.ts   # must print 0

Going through callServerTool rather than fetching the API from the App is precisely what keeps the credential server-side.

Point `CONTACT_API_BASE_URL` at a local landing page while developing. Against production, every test submission writes a real row to the production Supabase table and sends two real emails. Vercel *preview* deployments of this server do point at production — use them sparingly and clean up the rows afterwards (they carry source='mcp').

npm run serve loads .env from the working directory. The stdio entry point runs with cwd=/ and cannot find it, so a stdio host config needs its own env block — see Claude Desktop.

The form contract

The landing page owns the form contract and publishes it at GET /api/contact/schema. This repo holds a generated, committed copy in src/contact-contract.ts:

npm run sync:contract    # regenerate from the endpoint

npm run check:contract # fail if the copy has drifted

Never hand-edit that file. The 8 goal option strings are also the keys of GOAL_PARAGRAPHS in the landing page's welcome email, so a single byte of drift silently drops the personalised paragraph with no error anywhere. The copy is committed rather than fetched at build time so that npm run build works offline and on a fresh clone; check:contract is a release step, not a build step.

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 — get_contact_form, get_product_overview, get_contact_info and submit_contact_form all appear. The last is marked app-only; Inspector lists it because filtering by `visibility` is the host's job, not the server's. The two plain tools return their text when called.
2. Resources — ui://get-contact-form/mcp-app.html lists; reading it returns ~246 KB of bundled HTML and carries _meta.ui.prefersBorder with no `csp` key at all.
3. Apps — select get_contact_form. The form renders with live, interactive controls and the network panel stays empty. Inspector strips allow-same-origin, so working controls here also prove the old Tally breakage was Tally's own storage access rather than a structural sandbox limit.

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 get_contact_form --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 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 get_contact_form means a real submission — it writes a row and fires notification emails. Point CONTACT_API_BASE_URL at a local landing page and use throwaway details.

When to use which

Host support, as verified

Re-check per release; these are observations, not guarantees.

| Claude Desktop | ✅ | ✅ | ✅ | ✅ | *(re-verified on v2.1.0, 6 Oct 2026)* | tools/basic-host | ✅ | ✅ | ✅ | n/a (shows all tools) | | MCP Inspector | ✅ | ✅ | ✅ | ❌ lists it | | claude.ai connector | ✅ | ✅ | ✅ | ✅ |

Claude Desktop and Inspector verified 5 October 2026 and re-verified on v2.1.0 on 6 October; claude.ai verified 6 October over a cloudflared tunnel. Inspector additionally cannot receive ui/update-model-context.

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:// /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: get_contact_form declares no CSP at all, so the frameDomains bug that blocked the previous Tally embed no longer applies. What to watch for instead is whether the host declares the serverTools capability — without it the App shows its "continue on the web" fallback rather than a submit button. See Known Limitations.

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 ~246 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://webweave