Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

test(mcp): add a connector compatibility probe that drives every hosted MCP server like a cloud client

nirholas62903ced4af4
diff --git a/package.json b/package.json
index c0e71f897..9f3f6ae7d 100644
--- a/package.json
+++ b/package.json
@@ -428,6 +428,7 @@
"smoke:prod": "node scripts/check-pages.mjs --base https://three.ws",
"check:asset-encoding": "node scripts/check-asset-encoding.mjs",
"probe:generation": "node scripts/probe-generation-suite.mjs --base https://three.ws",
+ "probe:mcp-clients": "node scripts/mcp-client-probe.mjs",
"event:watch": "node scripts/event-watch.mjs",
"event:capacity": "node scripts/play-capacity-smoke.mjs",
"event:failover": "node --env-file=.env scripts/event-dependency-failover.mjs",
diff --git a/scripts/mcp-client-probe.mjs b/scripts/mcp-client-probe.mjs
new file mode 100644
index 000000000..7ff6a82f5
--- /dev/null
+++ b/scripts/mcp-client-probe.mjs
@@ -0,0 +1,515 @@
+#!/usr/bin/env node
+// Connector compatibility probe for every hosted three.ws MCP server.
+//
+// Behaves like a cloud MCP client (Grok Bot, claude.ai connectors, the xAI
+// Responses API): it drives the official MCP SDK client over Streamable HTTP,
+// falls back to the legacy SSE transport when Streamable HTTP fails for a
+// reason other than auth, and checks the raw handshake details a connector
+// trips on silently: the GET a client opens for its server-to-client stream,
+// protocol-version negotiation, Mcp-Session-Id issue and echo, and the 401
+// that must point an OAuth client at the protected-resource metadata.
+//
+// The server list is public/.well-known/mcp.json, so a server added there is
+// probed with no change here. Three modes per server:
+//
+// anonymous no credentials. Must fully work when the server's auth names
+// `none`; otherwise must answer with an OAuth-shaped 401.
+// api key Authorization: Bearer $THREE_WS_API_KEY, when that is set.
+// oauth asserts the challenge shape only: WWW-Authenticate carries
+// resource_metadata, that document resolves, its `resource`
+// is one the MCP SDK accepts for this server URL, and the
+// authorization server metadata supports PKCE S256. An
+// invalid bearer must earn the same challenge (re-auth path).
+//
+// Records initialize, tools/list count, prompts/list count, and one free
+// tools/call where a free tool exists (search_catalog, getting_started).
+// No paid tool is ever called and no payment header is ever sent.
+//
+// node scripts/mcp-client-probe.mjs # https://three.ws
+// node scripts/mcp-client-probe.mjs --base http://localhost:3000
+// node scripts/mcp-client-probe.mjs --json prompts/x-grok/_generated/connector-probe.json
+// node scripts/mcp-client-probe.mjs --only mcp-studio --timeout 45000
+//
+// Exit code 0 when every server passes, 1 otherwise.
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { checkResourceAllowed, resourceUrlFromServerUrl } from '@modelcontextprotocol/sdk/shared/auth-utils.js';
+import { LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS } from '@modelcontextprotocol/sdk/types.js';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const CLIENT_INFO = { name: 'three-ws-connector-probe', version: '1.0.0' };
+
+// Free tools a probe may call: read-only, no GPU, no spend. First match wins.
+const FREE_CALLS = [
+ { name: 'search_catalog', arguments: { q: 'chair', limit: 3 } },
+ { name: 'getting_started', arguments: {} },
+];
+
+// Versions a real client may open with. The SDK's latest leads; the rest are
+// what older connectors still send.
+const NEGOTIATION_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+
+function parseArgs(argv) {
+ const out = { base: 'https://three.ws', json: null, only: null, timeout: 30_000 };
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i];
+ const next = () => {
+ const v = argv[++i];
+ if (v === undefined) throw new Error(`${a} needs a value`);
+ return v;
+ };
+ if (a === '--base') out.base = next().replace(/\/+$/, '');
+ else if (a === '--json') out.json = next();
+ else if (a === '--only') out.only = next();
+ else if (a === '--timeout') out.timeout = Number(next());
+ else if (a === '--help' || a === '-h') {
+ console.log('usage: node scripts/mcp-client-probe.mjs [--base <origin>] [--json <path>] [--only <substring>] [--timeout <ms>]');
+ process.exit(0);
+ } else throw new Error(`unknown argument ${a}`);
+ }
+ return out;
+}
+
+function loadApiKey() {
+ if (process.env.THREE_WS_API_KEY) return process.env.THREE_WS_API_KEY;
+ for (const f of ['.env', '.env.local']) {
+ const p = resolve(ROOT, f);
+ if (!existsSync(p)) continue;
+ try {
+ process.loadEnvFile(p);
+ } catch {
+ continue;
+ }
+ if (process.env.THREE_WS_API_KEY) return process.env.THREE_WS_API_KEY;
+ }
+ return null;
+}
+
+// What the manifest's free-text `auth` promises, as flags the checks key on.
+export function authExpectations(auth) {
+ const s = String(auth || '');
+ return {
+ anonymous: /\bnone\b/i.test(s),
+ oauth: /oauth/i.test(s),
+ apiKey: /api key|authenticated three\.ws principals/i.test(s),
+ };
+}
+
+export function serverUrlFor(endpoint, base) {
+ const u = new URL(endpoint);
+ return new URL(u.pathname + u.search, `${base}/`).href;
+}
+
+// RFC 9110 auth-param parsing, enough for `Bearer k="v", k2="v2"`.
+export function parseWwwAuthenticate(header) {
+ if (!header) return null;
+ const m = /^\s*(\S+)\s*(.*)$/.exec(header);
+ if (!m) return null;
+ const params = {};
+ const re = /([a-zA-Z0-9_-]+)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|([^\s,]+))/g;
+ let p;
+ while ((p = re.exec(m[2]))) params[p[1].toLowerCase()] = p[2] !== undefined ? p[2].replace(/\\(.)/g, '$1') : p[3];
+ return { scheme: m[1], params };
+}
+
+async function timedFetch(url, init, timeout) {
+ return fetch(url, { ...init, signal: AbortSignal.timeout(timeout) });
+}
+
+function initBody(protocolVersion, id = 1) {
+ return JSON.stringify({
+ jsonrpc: '2.0',
+ id,
+ method: 'initialize',
+ params: { protocolVersion, capabilities: {}, clientInfo: CLIENT_INFO },
+ });
+}
+
+const PROTOCOL_HEADERS = { 'content-type': 'application/json', accept: 'application/json, text/event-stream' };
+
+// A Streamable HTTP response body is either one JSON object or an SSE stream
+// whose `data:` lines carry the JSON-RPC messages.
+export function parseRpcBody(text, contentType) {
+ if (String(contentType || '').includes('text/event-stream')) {
+ for (const line of text.split(/\r?\n/)) {
+ if (!line.startsWith('data:')) continue;
+ try {
+ const msg = JSON.parse(line.slice(5).trim());
+ if (msg && (msg.result || msg.error)) return msg;
+ } catch {
+ continue;
+ }
+ }
+ return null;
+ }
+ try {
+ return JSON.parse(text);
+ } catch {
+ return null;
+ }
+}
+
+async function rawInitialize(url, { headers = {}, protocolVersion = LATEST_PROTOCOL_VERSION, timeout }) {
+ const res = await timedFetch(url, { method: 'POST', headers: { ...PROTOCOL_HEADERS, ...headers }, body: initBody(protocolVersion) }, timeout);
+ const contentType = res.headers.get('content-type') || '';
+ const text = await res.text();
+ const msg = parseRpcBody(text, contentType);
+ return {
+ status: res.status,
+ contentType,
+ sessionId: res.headers.get('mcp-session-id'),
+ wwwAuthenticate: res.headers.get('www-authenticate'),
+ protocolVersion: msg?.result?.protocolVersion ?? null,
+ rpcError: msg?.error ? { code: msg.error.code, message: msg.error.message } : null,
+ };
+}
+
+async function probeGetStream(url, { headers = {}, timeout }) {
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), timeout);
+ try {
+ const res = await fetch(url, { method: 'GET', headers: { accept: 'text/event-stream', ...headers }, signal: controller.signal });
+ const out = {
+ status: res.status,
+ contentType: res.headers.get('content-type') || '',
+ allow: res.headers.get('allow'),
+ wwwAuthenticate: res.headers.get('www-authenticate'),
+ };
+ // A live stream never ends on its own; the headers are the answer.
+ controller.abort();
+ await res.body?.cancel().catch(() => {});
+ return out;
+ } finally {
+ clearTimeout(timer);
+ }
+}
+
+// What a connector needs from a GET: an event stream, a 405 that says which
+// methods do work, or an auth challenge it can act on.
+export function judgeGetStream(get) {
+ if (get.status === 200 && get.contentType.includes('text/event-stream')) return null;
+ if (get.status === 405) return get.allow ? null : 'GET answered 405 without an Allow header';
+ if (get.status === 401) return get.wwwAuthenticate ? null : 'GET answered 401 without WWW-Authenticate';
+ return `GET with accept: text/event-stream answered ${get.status} ${get.contentType}`.trim();
+}
+
+async function probeChallenge(url, { timeout }) {
+ const out = { failures: [] };
+ const anon = await rawInitialize(url, { timeout });
+ out.status = anon.status;
+ out.wwwAuthenticate = anon.wwwAuthenticate;
+ if (anon.status !== 401) {
+ out.failures.push(`unauthenticated initialize answered ${anon.status}, an OAuth client needs 401 to start sign-in`);
+ return out;
+ }
+ const parsed = parseWwwAuthenticate(anon.wwwAuthenticate);
+ if (!parsed || parsed.scheme.toLowerCase() !== 'bearer') {
+ out.failures.push('401 carries no Bearer WWW-Authenticate challenge');
+ return out;
+ }
+ out.resourceMetadataUrl = parsed.params.resource_metadata || null;
+ if (!out.resourceMetadataUrl) {
+ out.failures.push('WWW-Authenticate does not name resource_metadata');
+ return out;
+ }
+ const mdRes = await timedFetch(out.resourceMetadataUrl, { headers: { accept: 'application/json' } }, timeout);
+ const mdType = mdRes.headers.get('content-type') || '';
+ const md = mdType.includes('json') ? await mdRes.json().catch(() => null) : null;
+ if (!mdType.includes('json')) await mdRes.body?.cancel().catch(() => {});
+ out.metadata = {
+ status: mdRes.status,
+ resource: md?.resource ?? null,
+ authorizationServers: md?.authorization_servers ?? null,
+ };
+ if (mdRes.status !== 200 || !md) {
+ out.failures.push(`protected-resource metadata at ${out.resourceMetadataUrl} answered ${mdRes.status} ${mdType}`);
+ return out;
+ }
+ // The exact gate the MCP SDK client runs before it redirects anyone to sign in.
+ out.resourceAllowed = Boolean(md.resource) && checkResourceAllowed({ requestedResource: resourceUrlFromServerUrl(url), configuredResource: md.resource });
+ if (!out.resourceAllowed) {
+ out.failures.push(`protected resource ${md.resource} does not cover ${url}, so an MCP SDK client refuses to sign in`);
+ }
+ if (parsed.params.resource && parsed.params.resource !== md.resource) {
+ out.failures.push(`WWW-Authenticate resource ${parsed.params.resource} disagrees with the metadata resource ${md.resource}`);
+ }
+ const as = Array.isArray(md.authorization_servers) ? md.authorization_servers[0] : null;
+ if (!as) {
+ out.failures.push('protected-resource metadata lists no authorization_servers');
+ return out;
+ }
+ const asUrl = new URL('/.well-known/oauth-authorization-server', as).href;
+ const asRes = await timedFetch(asUrl, { headers: { accept: 'application/json' } }, timeout);
+ const asMd = await asRes.json().catch(() => null);
+ out.authorizationServer = {
+ url: asUrl,
+ status: asRes.status,
+ issuer: asMd?.issuer ?? null,
+ pkceS256: Boolean(asMd?.code_challenge_methods_supported?.includes('S256')),
+ dynamicRegistration: Boolean(asMd?.registration_endpoint),
+ };
+ if (asRes.status !== 200 || !asMd?.authorization_endpoint || !asMd?.token_endpoint) {
+ out.failures.push(`authorization server metadata at ${asUrl} is incomplete (${asRes.status})`);
+ } else if (!out.authorizationServer.pkceS256) {
+ out.failures.push('authorization server does not advertise PKCE S256, which OAuth 2.1 requires');
+ }
+ // A connector holding an expired token must be told to re-authenticate, not
+ // handed a dead end.
+ const stale = await rawInitialize(url, { headers: { authorization: 'Bearer probe.invalid.token' }, timeout });
+ out.invalidBearer = { status: stale.status, wwwAuthenticate: stale.wwwAuthenticate };
+ const staleParsed = parseWwwAuthenticate(stale.wwwAuthenticate);
+ if (stale.status !== 401 || !staleParsed?.params.resource_metadata) {
+ out.failures.push(`an invalid bearer answered ${stale.status} without a resource_metadata challenge`);
+ }
+ return out;
+}
+
+async function probeNegotiation(url, { headers = {}, timeout }) {
+ const rows = [];
+ for (const v of NEGOTIATION_VERSIONS) {
+ const r = await rawInitialize(url, { headers, protocolVersion: v, timeout }).catch((err) => ({ error: err.message }));
+ rows.push({
+ requested: v,
+ status: r.status ?? null,
+ negotiated: r.protocolVersion ?? null,
+ echoed: r.protocolVersion === v,
+ clientSupportsAnswer: r.protocolVersion ? SUPPORTED_PROTOCOL_VERSIONS.includes(r.protocolVersion) : false,
+ error: r.error ?? r.rpcError?.message ?? null,
+ });
+ }
+ return rows;
+}
+
+// Raw session check, run only when the server issued an id: the echoed id
+// must work, and an id the server never issued should earn 404 (spec MUST for
+// a session the server does not hold).
+async function probeSession(url, sessionId, { headers = {}, negotiated, timeout }) {
+ const call = (sid) =>
+ timedFetch(
+ url,
+ {
+ method: 'POST',
+ headers: { ...PROTOCOL_HEADERS, ...headers, 'mcp-session-id': sid, 'mcp-protocol-version': negotiated },
+ body: JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }),
+ },
+ timeout,
+ ).then(async (r) => {
+ await r.body?.cancel().catch(() => {});
+ return r.status;
+ });
+ return { echoed: await call(sessionId), unknown: await call(`probe-unknown-${Date.now()}`) };
+}
+
+function errorStatus(err) {
+ if (!err) return null;
+ if (typeof err.code === 'number' && err.code >= 100 && err.code < 600) return err.code;
+ const m = /\b(4\d\d|5\d\d)\b/.exec(String(err.message || ''));
+ return m ? Number(m[1]) : null;
+}
+
+function isAuthError(err) {
+ return err?.name === 'UnauthorizedError' || errorStatus(err) === 401 || /unauthori[sz]ed/i.test(String(err?.message));
+}
+
+async function runSdk(url, { headers = {}, transport: kind, timeout }) {
+ const client = new Client(CLIENT_INFO, { capabilities: {} });
+ const warnings = [];
+ let closing = false;
+ // Closing aborts the open GET stream; that abort is the probe's own doing.
+ client.onerror = (e) => {
+ if (!closing) warnings.push(String(e?.message || e));
+ };
+ const requestInit = { headers };
+ const transport =
+ kind === 'sse'
+ ? new SSEClientTransport(new URL(url), {
+ requestInit,
+ eventSourceInit: { fetch: (u, init) => fetch(u, { ...init, headers: { ...(init?.headers || {}), ...headers } }) },
+ })
+ : new StreamableHTTPClientTransport(new URL(url), { requestInit });
+ const out = { transport: kind, ok: false };
+ const opts = { timeout };
+ try {
+ await client.connect(transport, opts);
+ out.serverInfo = client.getServerVersion() ?? null;
+ out.protocolVersion = transport.protocolVersion ?? null;
+ out.sessionId = transport.sessionId ?? null;
+ const caps = client.getServerCapabilities() || {};
+ out.capabilities = Object.keys(caps);
+ const tools = await client.listTools(undefined, opts);
+ out.tools = tools.tools.length;
+ out.toolNames = tools.tools.map((t) => t.name);
+ out.prompts = caps.prompts ? (await client.listPrompts(undefined, opts)).prompts.length : null;
+ const free = FREE_CALLS.find((c) => out.toolNames.includes(c.name));
+ if (free) {
+ const started = Date.now();
+ const r = await client.callTool(free, undefined, opts);
+ out.call = {
+ name: free.name,
+ ok: !r.isError,
+ ms: Date.now() - started,
+ contentItems: Array.isArray(r.content) ? r.content.length : 0,
+ structured: r.structuredContent !== undefined,
+ };
+ }
+ out.ok = !out.call || out.call.ok;
+ } catch (err) {
+ out.error = String(err?.message || err).slice(0, 400);
+ out.status = errorStatus(err);
+ out.authRequired = isAuthError(err);
+ } finally {
+ closing = true;
+ if (out.sessionId && kind !== 'sse') await transport.terminateSession().catch((e) => warnings.push(`terminate: ${e.message}`));
+ await client.close().catch(() => {});
+ }
+ delete out.toolNames;
+ if (warnings.length) out.warnings = [...new Set(warnings)].slice(0, 5);
+ return out;
+}
+
+// Streamable HTTP first; the legacy SSE transport only when Streamable HTTP
+// failed for a reason other than auth (an auth failure is an answer, not a
+// transport problem).
+async function runMode(url, { headers, timeout }) {
+ const primary = await runSdk(url, { headers, transport: 'streamable-http', timeout });
+ if (primary.ok || primary.authRequired) return primary;
+ const fallback = await runSdk(url, { headers, transport: 'sse', timeout });
+ return { ...primary, fallback };
+}
+
+export function judgeServer(r) {
+ const failures = [];
+ const { expects, modes, http } = r;
+ if (http.getStreamProblem) failures.push(http.getStreamProblem);
+ if (expects.anonymous) {
+ const a = modes.anonymous;
+ if (!a.ok && !a.fallback?.ok) failures.push(`anonymous connect failed: ${a.error || a.call?.name + ' call errored'}`);
+ else if (!(a.tools > 0 || a.fallback?.tools > 0)) failures.push('anonymous tools/list returned no tools');
+ if (http.initialize && !/application\/json|text\/event-stream/.test(http.initialize.contentType)) {
+ failures.push(`initialize answered content-type ${http.initialize.contentType}`);
+ }
+ } else {
+ if (modes.anonymous.ok) failures.push('anonymous MCP client was served on a server that requires auth');
+ for (const f of modes.oauth?.failures || []) failures.push(f);
+ }
+ if (modes.apiKey && !modes.apiKey.skipped && (expects.apiKey || expects.oauth)) {
+ const k = modes.apiKey;
+ if (!k.ok) failures.push(`api key connect failed: ${k.error || k.call?.name + ' call errored'}`);
+ else if (!(k.tools > 0)) failures.push('api key tools/list returned no tools');
+ }
+ for (const n of http.negotiation || []) {
+ if (n.negotiated && !n.clientSupportsAnswer) failures.push(`requested ${n.requested}, server answered ${n.negotiated} which no SDK client supports`);
+ }
+ return failures;
+}
+
+async function probeServer(server, { base, timeout, apiKey }) {
+ const url = serverUrlFor(server.endpoint, base);
+ const expects = authExpectations(server.auth);
+ const r = { name: server.name, endpoint: server.endpoint, url, auth: server.auth, expects, http: {}, modes: {} };
+ const guard = async (label, fn) => {
+ try {
+ return await fn();
+ } catch (err) {
+ return { error: `${label}: ${String(err?.message || err).slice(0, 300)}` };
+ }
+ };
+
+ r.http.initialize = await guard('initialize', () => rawInitialize(url, { timeout }));
+ // One retry on a timeout: a cold instance can hold the first GET past the
+ // budget, and a connector retries that too.
+ r.http.getStream = await guard('get', () => probeGetStream(url, { timeout: Math.min(timeout, 15_000) }));
+ if (r.http.getStream.error) {
+ r.http.getStream = await guard('get', () => probeGetStream(url, { timeout: Math.min(timeout, 15_000) }));
+ r.http.getStream.retried = true;
+ }
+ r.http.getStreamProblem = r.http.getStream.error || judgeGetStream(r.http.getStream);
+
+ r.modes.anonymous = await runMode(url, { headers: {}, timeout });
+ if (!expects.anonymous) r.modes.oauth = await guard('oauth', () => probeChallenge(url, { timeout }));
+ if (!apiKey) r.modes.apiKey = { skipped: 'THREE_WS_API_KEY is not set' };
+ else r.modes.apiKey = await runMode(url, { headers: { authorization: `Bearer ${apiKey}` }, timeout });
+
+ // Negotiation and session checks run on whichever mode actually connects.
+ const authed = expects.anonymous ? {} : apiKey && r.modes.apiKey.ok ? { authorization: `Bearer ${apiKey}` } : null;
+ const working = expects.anonymous ? r.modes.anonymous : r.modes.apiKey;
+ if (authed) {
+ r.http.negotiation = await guard('negotiation', () => probeNegotiation(url, { headers: authed, timeout }));
+ if (working?.sessionId) {
+ r.http.session = await guard('session', () =>
+ probeSession(url, working.sessionId, { headers: authed, negotiated: working.protocolVersion, timeout }),
+ );
+ }
+ r.http.sessionIssued = Boolean(working?.sessionId);
+ }
+ if (Array.isArray(r.http.negotiation) === false && r.http.negotiation?.error) r.http.negotiation = [{ error: r.http.negotiation.error }];
+
+ r.failures = judgeServer(r);
+ r.pass = r.failures.length === 0;
+ return r;
+}
+
+function summaryLine(r) {
+ const a = r.modes.anonymous;
+ const k = r.modes.apiKey;
+ const bits = [
+ r.pass ? 'PASS' : 'FAIL',
+ r.url,
+ `init ${r.http.initialize?.status ?? 'err'}`,
+ `GET ${r.http.getStream?.status ?? 'err'}`,
+ `anon ${a.ok ? `ok tools=${a.tools} prompts=${a.prompts ?? '-'}` : a.authRequired ? '401' : 'fail'}`,
+ `key ${k.skipped ? 'skipped' : k.ok ? `ok tools=${k.tools} prompts=${k.prompts ?? '-'}` : 'fail'}`,
+ ];
+ if (r.modes.oauth) bits.push(`oauth ${r.modes.oauth.failures?.length ? 'bad' : r.modes.oauth.error ? 'err' : 'ok'}`);
+ const call = (a.ok && a.call) || (k.ok && k.call);
+ if (call) bits.push(`call ${call.name}=${call.ok ? 'ok' : 'error'} ${call.ms}ms`);
+ return bits.join(' | ');
+}
+
+async function main() {
+ const args = parseArgs(process.argv.slice(2));
+ const manifest = JSON.parse(readFileSync(resolve(ROOT, 'public/.well-known/mcp.json'), 'utf8'));
+ const servers = manifest.servers.filter((s) => !args.only || s.endpoint.includes(args.only) || s.name.includes(args.only));
+ if (!servers.length) throw new Error(`no server in public/.well-known/mcp.json matches --only ${args.only}`);
+ const apiKey = loadApiKey();
+ const startedAt = new Date().toISOString();
+ const results = [];
+ for (const s of servers) {
+ const r = await probeServer(s, { base: args.base, timeout: args.timeout, apiKey });
+ results.push(r);
+ console.log(summaryLine(r));
+ for (const f of r.failures) console.log(` - ${f}`);
+ }
+ const report = {
+ probe: 'scripts/mcp-client-probe.mjs',
+ base: args.base,
+ startedAt,
+ finishedAt: new Date().toISOString(),
+ sdkVersion: JSON.parse(readFileSync(resolve(ROOT, 'node_modules/@modelcontextprotocol/sdk/package.json'), 'utf8')).version,
+ clientProtocolVersion: LATEST_PROTOCOL_VERSION,
+ apiKeyMode: apiKey ? 'ran' : 'skipped (THREE_WS_API_KEY not set)',
+ pass: results.every((r) => r.pass),
+ servers: results,
+ };
+ if (args.json) {
+ const out = resolve(process.cwd(), args.json);
+ mkdirSync(dirname(out), { recursive: true });
+ writeFileSync(out, `${JSON.stringify(report, null, '\t')}\n`);
+ console.log(`wrote ${args.json}`);
+ }
+ const failed = results.filter((r) => !r.pass).length;
+ console.log(failed ? `${failed} of ${results.length} servers failed` : `all ${results.length} servers passed`);
+ process.exitCode = failed ? 1 : 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+ main().catch((err) => {
+ console.error(err?.stack || err);
+ process.exit(2);
+ });
+}
diff --git a/scripts/smoke-mcp-remotes.mjs b/scripts/smoke-mcp-remotes.mjs
index 4aade2f8e..c155b045c 100644
--- a/scripts/smoke-mcp-remotes.mjs
+++ b/scripts/smoke-mcp-remotes.mjs
@@ -38,6 +38,13 @@ const ENDPOINTS = [
type: 'free',
requireTools: ['mesh_forge', 'rig_mesh', 'forge_avatar', 'text_to_avatar', 'check_job'],
},
+ {
+ // The same free studio behind the door Grok Bot and the xAI API connect to.
+ // Catalog only, like /api/mcp-studio, so the probe never spends a generation.
+ path: '/api/mcp-grok',
+ type: 'free',
+ requireTools: ['forge_free', 'forge_avatar', 'check_job', 'create_agent_persona', 'persona_say'],
+ },
{ path: '/api/mcp', type: 'paid' },
{ path: '/api/mcp-3d', type: 'paid' },
{ path: '/api/mcp-agent', type: 'paid' },
diff --git a/tests/mcp-client-probe.test.js b/tests/mcp-client-probe.test.js
new file mode 100644
index 000000000..24e5b01e0
--- /dev/null
+++ b/tests/mcp-client-probe.test.js
@@ -0,0 +1,102 @@
+// The connector probe's verdicts, pinned so a change to it cannot quietly
+// start passing a server a cloud MCP client would fail on.
+import { describe, it, expect } from 'vitest';
+import {
+ authExpectations,
+ serverUrlFor,
+ parseWwwAuthenticate,
+ parseRpcBody,
+ judgeGetStream,
+ judgeServer,
+} from '../scripts/mcp-client-probe.mjs';
+
+describe('authExpectations', () => {
+ it('reads the free-text auth field of /.well-known/mcp.json', () => {
+ expect(authExpectations('none')).toEqual({ anonymous: true, oauth: false, apiKey: false });
+ expect(authExpectations('OAuth 2.1 (end-user), API key (server-to-server), or x402 pay-per-call')).toEqual({
+ anonymous: false,
+ oauth: true,
+ apiKey: true,
+ });
+ expect(authExpectations('none for the read-only tools; API key or x402 for pumpfun_upload_metadata').anonymous).toBe(true);
+ expect(authExpectations('x402 pay-per-call (authenticated three.ws principals call without per-call payment)').apiKey).toBe(true);
+ });
+});
+
+describe('serverUrlFor', () => {
+ it('moves a published endpoint onto another origin', () => {
+ expect(serverUrlFor('https://three.ws/api/mcp-3d', 'http://localhost:3000')).toBe('http://localhost:3000/api/mcp-3d');
+ });
+});
+
+describe('parseWwwAuthenticate', () => {
+ it('parses a quoted Bearer challenge', () => {
+ const c = parseWwwAuthenticate(
+ 'Bearer resource_metadata="https://three.ws/.well-known/oauth-protected-resource/api/mcp-3d", resource="https://three.ws/api/mcp-3d"',
+ );
+ expect(c.scheme).toBe('Bearer');
+ expect(c.params.resource_metadata).toBe('https://three.ws/.well-known/oauth-protected-resource/api/mcp-3d');
+ expect(c.params.resource).toBe('https://three.ws/api/mcp-3d');
+ });
+
+ it('returns null for no header', () => {
+ expect(parseWwwAuthenticate(null)).toBeNull();
+ });
+});
+
+describe('parseRpcBody', () => {
+ it('reads a JSON-RPC result from an SSE body', () => {
+ const body = 'event: message\ndata: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18"}}\n\n';
+ expect(parseRpcBody(body, 'text/event-stream').result.protocolVersion).toBe('2025-06-18');
+ });
+});
+
+describe('judgeGetStream', () => {
+ it('accepts a stream, a 405 with Allow, or an auth challenge', () => {
+ expect(judgeGetStream({ status: 200, contentType: 'text/event-stream' })).toBeNull();
+ expect(judgeGetStream({ status: 405, contentType: '', allow: 'POST, OPTIONS' })).toBeNull();
+ expect(judgeGetStream({ status: 401, contentType: '', wwwAuthenticate: 'Bearer resource_metadata="x"' })).toBeNull();
+ });
+
+ it('fails a 405 without Allow and anything else', () => {
+ expect(judgeGetStream({ status: 405, contentType: '', allow: null })).toMatch(/Allow/);
+ expect(judgeGetStream({ status: 404, contentType: 'text/html' })).toMatch(/404/);
+ });
+});
+
+describe('judgeServer', () => {
+ const base = { http: { initialize: { contentType: 'application/json' }, getStreamProblem: null, negotiation: [] } };
+
+ it('passes an open server that connects and lists tools', () => {
+ const r = { ...base, expects: { anonymous: true }, modes: { anonymous: { ok: true, tools: 14 }, apiKey: { skipped: 'x' } } };
+ expect(judgeServer(r)).toEqual([]);
+ });
+
+ it('fails a protected server whose OAuth metadata the SDK would refuse', () => {
+ const r = {
+ ...base,
+ expects: { anonymous: false, oauth: true },
+ modes: {
+ anonymous: { ok: false, authRequired: true },
+ oauth: { failures: ['protected resource https://three.ws/api/mcp does not cover https://three.ws/api/mcp-3d'] },
+ apiKey: { skipped: 'x' },
+ },
+ };
+ expect(judgeServer(r)).toHaveLength(1);
+ });
+
+ it('fails a protected server that serves an anonymous MCP client', () => {
+ const r = { ...base, expects: { anonymous: false, oauth: true }, modes: { anonymous: { ok: true, tools: 3 }, oauth: { failures: [] }, apiKey: { skipped: 'x' } } };
+ expect(judgeServer(r)[0]).toMatch(/requires auth/);
+ });
+
+ it('fails a negotiated version no SDK client supports', () => {
+ const r = {
+ ...base,
+ http: { ...base.http, negotiation: [{ requested: '2025-06-18', negotiated: '1999-01-01', clientSupportsAnswer: false }] },
+ expects: { anonymous: true },
+ modes: { anonymous: { ok: true, tools: 1 }, apiKey: { skipped: 'x' } },
+ };
+ expect(judgeServer(r)[0]).toMatch(/1999-01-01/);
+ });
+});