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.

feat(grok-bot): prove a Grok model drives three.ws MCP end to end over the xAI Responses API

nirholascfb34e0d4bd0
diff --git a/docs/grok-bot.md b/docs/grok-bot.md
index 9eff37bad..f48ff1094 100644
--- a/docs/grok-bot.md
+++ b/docs/grok-bot.md
@@ -503,6 +503,49 @@ can print under a failing server, what it means, and the fix:
| `api key tools/list returned no tools` | The key connected but listed nothing. | Same as above: check the key's scopes and your MCP tool settings. |
| `requested …, server answered … which no SDK client supports` | The server negotiated a protocol version current SDKs do not know. | Server-side defect; three.ws answers `2025-06-18` to every version a client opens with. |
+### Prove a real Grok model drives it (xAI Responses API)
+
+`npm run probe:mcp-clients` proves the connector itself works; it never calls
+a real Grok model. `scripts/xai-mcp-e2e.mjs` closes that gap: it sends an xAI
+Responses API request with `https://three.ws/api/mcp-grok` as a remote MCP
+tool and the instruction "find a ready-made chair in the three.ws catalog and
+give me its viewer link", then asserts the response contains an `mcp_call`
+output item for `search_catalog` and that the final text carries a
+`three.ws` viewer URL. With a `GROK_API_KEY` or `XAI_API_KEY` in the
+environment, `.env`/`.env.local`, or the `three-ws-api` Cloud Run service (read
+in that order, never printed), run it live with `npm run e2e:xai-mcp`:
+
+```text
+sending request (key from process.env, model grok-4.7, server mcp-grok)
+mcp_call items: 1 (search_catalog)
+final text:
+...
+PASSED: search_catalog called (name "search_catalog"), viewer link https://three.ws/...
+```
+
+With no key anywhere, run the dry run instead, which needs no key, sends
+nothing, and prints the exact request xAI's docs describe, field for field:
+
+```bash
+npm run e2e:xai-mcp -- --dry-run
+```
+
+```json
+{
+ "model": "grok-4.7",
+ "input": [{ "role": "user", "content": "Find a ready-made chair in the three.ws catalog and give me its viewer link." }],
+ "tools": [{ "type": "mcp", "server_url": "https://three.ws/api/mcp-grok", "server_label": "three-ws", "server_description": "three.ws: ready-made 3D/avatar catalog, generation, agents and personas." }]
+}
+```
+
+`--server mcp-studio` runs the same proof against the free studio server
+instead of the Grok-specific one; `--base`, `--model` and `--prompt` override
+the target and the ask. If the model connects but never calls the tool, that
+is a defect in our tool descriptions (every agent client reads the same
+descriptions), not a prompt to work around: tighten `search_catalog`'s
+description in [`api/_mcp/tools/library.js`](../api/_mcp/tools/library.js) and
+record the before/after in the commit.
+
### Errors a connected Grok Bot can see
| Error | Meaning | Fix |
diff --git a/package.json b/package.json
index d647fa36f..3e30f9681 100644
--- a/package.json
+++ b/package.json
@@ -430,6 +430,7 @@
"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",
+ "e2e:xai-mcp": "node --env-file-if-exists=.env --env-file-if-exists=.env.local scripts/xai-mcp-e2e.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/xai-mcp-e2e.mjs b/scripts/xai-mcp-e2e.mjs
new file mode 100644
index 000000000..b6941f69a
--- /dev/null
+++ b/scripts/xai-mcp-e2e.mjs
@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// Prove a real Grok model drives three.ws end to end over the xAI Responses
+// API's remote MCP tool, the same connector mechanics Grok Bot uses.
+//
+// We cannot script Grok Bot itself (it is a hosted, browser-driven agent with
+// no API), but the Responses API lets any Grok model call a remote MCP server
+// directly: same model family, same "type": "mcp" tool, same tool discovery
+// and invocation path. A passing run here is evidence that a Grok model can
+// find our tools, call one correctly, and return a working three.ws link.
+//
+// Request shape is xAI's documented one, field for field
+// (https://docs.x.ai/developers/tools/remote-mcp): a "mcp" tool with
+// server_url and server_label. Response shape is the OpenAI-compatible
+// Responses API: output items of type "mcp_call" carry the tool name and
+// server_label; a final "message" item carries the assistant's answer as
+// "output_text" content parts.
+//
+// USAGE
+// npm run e2e:xai-mcp # send the real request, assert, exit non-zero on failure
+// npm run e2e:xai-mcp -- --dry-run # print the exact request, send nothing, needs no key
+// node scripts/xai-mcp-e2e.mjs --server mcp-studio --base http://localhost:3107
+// node scripts/xai-mcp-e2e.mjs --prompt "..." --model grok-4.3
+//
+// The key (GROK_API_KEY or XAI_API_KEY) is read from this process's env, then
+// from .env/.env.local (via --env-file in the npm script), then from the
+// three-ws-api Cloud Run service. It is only ever sent to api.x.ai and is
+// never printed.
+
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { GROK_DEFAULT_MODEL } from '../api/_lib/chat-models.js';
+import { serviceEnvValue } from './lib/service-env.mjs';
+
+const RESPONSES_URL = 'https://api.x.ai/v1/responses';
+const TIMEOUT_MS = 120_000;
+const DEFAULT_PROMPT = 'Find a ready-made chair in the three.ws catalog and give me its viewer link.';
+const SERVER_LABEL = 'three-ws';
+const SERVERS = {
+ 'mcp-grok': '/api/mcp-grok',
+ 'mcp-studio': '/api/mcp-studio',
+};
+
+export function parseArgs(argv) {
+ const args = { dryRun: false, server: 'mcp-grok', base: 'https://three.ws', model: GROK_DEFAULT_MODEL, prompt: DEFAULT_PROMPT };
+ for (let i = 0; i < argv.length; i += 1) {
+ const a = argv[i];
+ if (a === '--dry-run') args.dryRun = true;
+ else if (a === '--server') args.server = argv[++i];
+ else if (a === '--base') args.base = argv[++i];
+ else if (a === '--model') args.model = argv[++i];
+ else if (a === '--prompt') args.prompt = argv[++i];
+ else if (a === '--allow-tools') args.allowTools = argv[++i].split(',').map((s) => s.trim()).filter(Boolean);
+ }
+ if (!SERVERS[args.server]) {
+ throw new Error(`unknown --server "${args.server}", expected one of: ${Object.keys(SERVERS).join(', ')}`);
+ }
+ return args;
+}
+
+export function buildRequest(args) {
+ const serverUrl = `${args.base.replace(/\/$/, '')}${SERVERS[args.server]}`;
+ const tool = {
+ type: 'mcp',
+ server_url: serverUrl,
+ server_label: SERVER_LABEL,
+ server_description: 'three.ws: ready-made 3D/avatar catalog, generation, agents and personas.',
+ };
+ if (args.allowTools?.length) tool.allowed_tools = args.allowTools;
+ return {
+ model: args.model,
+ input: [{ role: 'user', content: args.prompt }],
+ tools: [tool],
+ };
+}
+
+export function resolveKey() {
+ const fromEnv = process.env.GROK_API_KEY || process.env.XAI_API_KEY;
+ if (fromEnv) return { key: fromEnv, source: 'process.env' };
+ const fromService = serviceEnvValue('GROK_API_KEY') || serviceEnvValue('XAI_API_KEY');
+ if (fromService) return { key: fromService, source: 'cloud-run:three-ws-api' };
+ return { key: null, source: null };
+}
+
+export function mcpCalls(output) {
+ return (output || []).filter((item) => item?.type === 'mcp_call');
+}
+
+export function finalText(output) {
+ return (output || [])
+ .filter((item) => item?.type === 'message' && item?.role === 'assistant')
+ .flatMap((item) => item.content || [])
+ .filter((part) => part?.type === 'output_text')
+ .map((part) => part.text || '')
+ .join('\n')
+ .trim();
+}
+
+export function matchesToolName(call, name) {
+ return call.name === name || call.name === `${SERVER_LABEL}.${name}`;
+}
+
+async function sendRequest(body, key) {
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+ try {
+ const res = await fetch(RESPONSES_URL, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+ body: JSON.stringify(body),
+ signal: controller.signal,
+ });
+ const text = await res.text();
+ let json;
+ try {
+ json = JSON.parse(text);
+ } catch {
+ throw new Error(`xAI returned non-JSON (HTTP ${res.status}): ${text.slice(0, 500)}`);
+ }
+ return { status: res.status, json };
+ } finally {
+ clearTimeout(timer);
+ }
+}
+
+async function main() {
+ const args = parseArgs(process.argv.slice(2));
+ const request = buildRequest(args);
+
+ if (args.dryRun) {
+ console.log('POST https://api.x.ai/v1/responses');
+ console.log('content-type: application/json');
+ console.log('authorization: Bearer <XAI_API_KEY>');
+ console.log(JSON.stringify(request, null, '\t'));
+ return 0;
+ }
+
+ const { key, source } = resolveKey();
+ if (!key) {
+ console.error('No GROK_API_KEY or XAI_API_KEY in process.env, .env/.env.local, or the three-ws-api Cloud Run service.');
+ console.error('Order 927 (prompts/finish/927-x-grok-46-owner-grok-api-key.md) owns creating one.');
+ console.error('Printing the dry-run request instead:');
+ console.error(JSON.stringify(request, null, '\t'));
+ return 1;
+ }
+
+ console.log(`sending request (key from ${source}, model ${request.model}, server ${args.server})`);
+ const { status, json } = await sendRequest(request, key);
+
+ if (status !== 200) {
+ console.error(`xAI answered HTTP ${status}:`);
+ console.error(JSON.stringify(json, null, '\t'));
+ return 1;
+ }
+
+ const output = json.output || [];
+ const calls = mcpCalls(output);
+ const searchCall = calls.find((c) => matchesToolName(c, 'search_catalog'));
+ const text = finalText(output);
+ const urlMatch = text.match(/https?:\/\/[^\s)]*three\.ws[^\s)]*/i);
+
+ console.log(`mcp_call items: ${calls.length} (${calls.map((c) => c.name).join(', ') || 'none'})`);
+ console.log(`final text:\n${text || '(empty)'}`);
+
+ const problems = [];
+ if (!searchCall) problems.push('no mcp_call to search_catalog in response.output');
+ if (!urlMatch) problems.push('final text has no three.ws viewer URL');
+
+ if (problems.length) {
+ console.error('FAILED:');
+ for (const p of problems) console.error(` - ${p}`);
+ console.error('If the model never called the tool, tighten the tool description (a real defect for every agent client), not the prompt.');
+ return 1;
+ }
+
+ console.log(`PASSED: search_catalog called (name "${searchCall.name}"), viewer link ${urlMatch[0]}`);
+ return 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+ main()
+ .then((code) => process.exit(code))
+ .catch((err) => {
+ console.error(err?.stack || String(err));
+ process.exit(1);
+ });
+}
diff --git a/tests/xai-mcp-e2e.test.js b/tests/xai-mcp-e2e.test.js
new file mode 100644
index 000000000..4f25ca309
--- /dev/null
+++ b/tests/xai-mcp-e2e.test.js
@@ -0,0 +1,121 @@
+// The xAI Responses API remote-MCP proof (order 039): request shape, response
+// parsing and key resolution, pinned so a field rename in the script cannot
+// quietly stop matching xAI's documented request or our server's response.
+import { describe, it, expect, afterEach } from 'vitest';
+import { parseArgs, buildRequest, mcpCalls, finalText, matchesToolName, resolveKey } from '../scripts/xai-mcp-e2e.mjs';
+
+describe('parseArgs', () => {
+ it('defaults to the Grok connector server and the catalog-chair prompt', () => {
+ const args = parseArgs([]);
+ expect(args.server).toBe('mcp-grok');
+ expect(args.base).toBe('https://three.ws');
+ expect(args.dryRun).toBe(false);
+ expect(args.prompt).toMatch(/chair/i);
+ });
+
+ it('reads every flag', () => {
+ const args = parseArgs(['--dry-run', '--server', 'mcp-studio', '--base', 'http://localhost:3107', '--model', 'grok-4.3', '--prompt', 'hi', '--allow-tools', 'search_catalog, get_job']);
+ expect(args).toMatchObject({ dryRun: true, server: 'mcp-studio', base: 'http://localhost:3107', model: 'grok-4.3', prompt: 'hi' });
+ expect(args.allowTools).toEqual(['search_catalog', 'get_job']);
+ });
+
+ it('rejects an unknown server', () => {
+ expect(() => parseArgs(['--server', 'mcp-nope'])).toThrow(/unknown --server/);
+ });
+});
+
+describe('buildRequest', () => {
+ it('matches xAI\'s documented remote MCP tool shape field for field', () => {
+ const req = buildRequest(parseArgs(['--base', 'https://three.ws']));
+ expect(req.tools).toHaveLength(1);
+ const tool = req.tools[0];
+ expect(tool.type).toBe('mcp');
+ expect(tool.server_url).toBe('https://three.ws/api/mcp-grok');
+ expect(tool.server_label).toBe('three-ws');
+ expect(tool.allowed_tools).toBeUndefined();
+ expect(req.input).toEqual([{ role: 'user', content: expect.stringContaining('chair') }]);
+ });
+
+ it('points mcp-studio at the free studio server, not the grok one', () => {
+ const req = buildRequest(parseArgs(['--server', 'mcp-studio']));
+ expect(req.tools[0].server_url).toBe('https://three.ws/api/mcp-studio');
+ });
+
+ it('strips a trailing slash from --base', () => {
+ const req = buildRequest(parseArgs(['--base', 'http://localhost:3107/']));
+ expect(req.tools[0].server_url).toBe('http://localhost:3107/api/mcp-grok');
+ });
+
+ it('only sets allowed_tools when given one', () => {
+ const req = buildRequest(parseArgs(['--allow-tools', 'search_catalog']));
+ expect(req.tools[0].allowed_tools).toEqual(['search_catalog']);
+ });
+});
+
+describe('mcpCalls / matchesToolName', () => {
+ it('picks out mcp_call output items and matches a bare or server-prefixed name', () => {
+ const output = [
+ { type: 'reasoning' },
+ { type: 'mcp_call', name: 'search_catalog', server_label: 'three-ws' },
+ { type: 'mcp_call', name: 'three-ws.get_job', server_label: 'three-ws' },
+ ];
+ const calls = mcpCalls(output);
+ expect(calls).toHaveLength(2);
+ expect(matchesToolName(calls[0], 'search_catalog')).toBe(true);
+ expect(matchesToolName(calls[1], 'get_job')).toBe(true);
+ expect(matchesToolName(calls[0], 'get_job')).toBe(false);
+ });
+
+ it('returns no calls when the output has none', () => {
+ expect(mcpCalls([{ type: 'message' }])).toEqual([]);
+ expect(mcpCalls(null)).toEqual([]);
+ });
+});
+
+describe('finalText', () => {
+ it('joins output_text parts of the final assistant message', () => {
+ const output = [
+ { type: 'mcp_call', name: 'search_catalog' },
+ {
+ type: 'message',
+ role: 'assistant',
+ content: [{ type: 'output_text', text: 'Here is a chair: https://three.ws/object/adjustable-chair' }],
+ },
+ ];
+ expect(finalText(output)).toContain('three.ws/object/adjustable-chair');
+ });
+
+ it('ignores non-assistant messages and non-text content', () => {
+ const output = [
+ { type: 'message', role: 'user', content: [{ type: 'output_text', text: 'ignored' }] },
+ { type: 'message', role: 'assistant', content: [{ type: 'reasoning_text', text: 'ignored too' }] },
+ ];
+ expect(finalText(output)).toBe('');
+ });
+});
+
+describe('resolveKey', () => {
+ const KEYS = ['GROK_API_KEY', 'XAI_API_KEY'];
+ const saved = {};
+ afterEach(() => {
+ for (const k of KEYS) {
+ if (saved[k] === undefined) delete process.env[k];
+ else process.env[k] = saved[k];
+ delete saved[k];
+ }
+ });
+
+ it('prefers GROK_API_KEY from the environment over XAI_API_KEY', () => {
+ for (const k of KEYS) saved[k] = process.env[k];
+ process.env.GROK_API_KEY = 'grok-key';
+ process.env.XAI_API_KEY = 'xai-key';
+ expect(resolveKey()).toEqual({ key: 'grok-key', source: 'process.env' });
+ });
+
+ it('falls back to XAI_API_KEY', () => {
+ for (const k of KEYS) saved[k] = process.env[k];
+ delete process.env.GROK_API_KEY;
+ process.env.XAI_API_KEY = 'xai-key';
+ expect(resolveKey()).toEqual({ key: 'xai-key', source: 'process.env' });
+ });
+});