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(mcp): serve the 3D studio to Grok Bot and the xAI Responses API at /api/mcp-grok

nirholas2fa7988cabdb
diff --git a/api/_mcp-studio/dispatch.js b/api/_mcp-studio/dispatch.js
index 198f17db5..514c9ec9a 100644
--- a/api/_mcp-studio/dispatch.js
+++ b/api/_mcp-studio/dispatch.js
@@ -53,6 +53,24 @@ const CHATGPT_INSTRUCTIONS = [
// response's own trip back through ChatGPT.
export const CHATGPT_CALL_BUDGET_MS = 40_000;
+// Grok Bot and the xAI Responses API call MCP tools from xAI's cloud, render no
+// widget, and give no published tool-call timeout. Grok Bot runs tasks
+// unattended for as long as they take, so on that surface a slow render comes
+// back as a pending job inside GROK_CALL_BUDGET_MS and the model is told to keep
+// collecting it, then hand the user links, since nothing renders inline.
+const GROK_INSTRUCTIONS = [
+ 'Nothing renders inline in Grok, so always give the user the viewerUrl (an interactive 3D viewer that opens in any',
+ 'browser) and the glbUrl (the downloadable model). A pending result is normal: wait the suggested seconds, then call',
+ 'check_job(job_id) again until it is done, and keep going without asking the user; a Grok Bot task should finish',
+ 'with the finished model, not the pending handle. To give yourself a body, forge_avatar a character, then',
+ 'create_agent_persona(glb_url, name) and share its embed_url; persona_say makes that body speak your reply and',
+ 'returns an embed_url that plays it.',
+];
+
+// The same headroom as ChatGPT: a call that outlives an unpublished host
+// timeout is lost work, while a pending handle costs one check_job round trip.
+export const GROK_CALL_BUDGET_MS = 40_000;
+
const CATALOG_INSTRUCTIONS = [
'Before generating a prop, character or animation, search_catalog(q) checks the thousands of ready-made CC0 props,',
'rigged characters and motion clips three.ws already publishes; get_item_source(id) returns paste-ready code for a',
@@ -80,6 +98,11 @@ const PERSONA_INSTRUCTIONS = [
// for broad distribution". Framing our own page is not that case, so
// the plugin listing leaves the persona tools out rather than ask
// review for an exception.
+// grok /api/mcp-grok: every tool of the full surface for Grok Bot and the
+// xAI Responses API, with a per-call budget and instructions that
+// hand out links in place of the widgets Grok does not render.
+// ./handler.js keys its generation caps on the MCP session, because
+// every Grok user reaches us from xAI's shared egress.
// check_job and the persona tools stay out of the generation quota on both; see
// ./handler.js callsGenerationTool. look_at_model renders frames server-side, so
// it rides that quota.
@@ -99,6 +122,14 @@ const SURFACES = {
instructions: [...BASE_INSTRUCTIONS, ...CHATGPT_INSTRUCTIONS].join(' '),
callBudgetMs: CHATGPT_CALL_BUDGET_MS,
},
+ grok: {
+ server: 'mcp-grok',
+ catalog: [...TOOL_CATALOG, ...CATALOG_TOOL_CATALOG, ...PERSONA_TOOL_CATALOG],
+ tools: { ...TOOLS, ...CATALOG_TOOLS, ...PERSONA_TOOLS },
+ personas: true,
+ instructions: [...BASE_INSTRUCTIONS, ...CATALOG_INSTRUCTIONS, ...PERSONA_INSTRUCTIONS, ...GROK_INSTRUCTIONS].join(' '),
+ callBudgetMs: GROK_CALL_BUDGET_MS,
+ },
};
export const SURFACE_NAMES = Object.keys(SURFACES);
diff --git a/api/_mcp-studio/handler.js b/api/_mcp-studio/handler.js
index 76f918342..ad94f8c24 100644
--- a/api/_mcp-studio/handler.js
+++ b/api/_mcp-studio/handler.js
@@ -7,7 +7,8 @@
// Parameterized by the tool surface it serves (SURFACES in ./dispatch.js):
// api/mcp-studio.js surface 'full' every tool, both widgets
// api/mcp-chatgpt.js surface 'chatgpt' generation tools, model viewer only
-// Both front doors share one transport cap, one per-IP generation quota and one
+// api/mcp-grok.js surface 'grok' every tool, for Grok Bot and the xAI API
+// Every front door shares one transport cap, one per-IP generation quota and one
// platform-wide circuit breaker, so a second door never doubles the free GPU
// budget.
//
@@ -19,6 +20,7 @@
// generation caps fail OPEN on a Redis outage, so a Redis blip never dead-ends a
// free feature; real paid spend stays fail-closed one layer down in /api/forge.
+import { randomUUID } from 'node:crypto';
import { cors, wrap, readJson, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { dispatch, PROTOCOL_VERSION } from './dispatch.js';
@@ -62,6 +64,33 @@ export function chatgptSubject(body) {
return null;
}
+// Grok Bot and the xAI Responses API also reach us from one shared egress pool,
+// and send no per-user id of their own. MCP Streamable HTTP has one: a server
+// may assign an Mcp-Session-Id on initialize, and a conforming client echoes it
+// on every later request of that connection. The grok surface issues one and
+// keys the per-caller caps on it. Minting is free, so a forged or rotated id
+// buys nothing past the per-IP pool cap that bounds the ChatGPT subject too.
+const SESSION_RE = /^grk_[0-9a-f-]{36}$/;
+export function grokSession(req) {
+ const sid = req?.headers?.['mcp-session-id'];
+ return typeof sid === 'string' && SESSION_RE.test(sid) ? sid : null;
+}
+
+function initializes(body) {
+ const batch = Array.isArray(body) ? body : [body];
+ return batch.some((m) => m && m.method === 'initialize');
+}
+
+/** The per-user identity a shared-egress surface carries, or null for per-IP keying. */
+export function callerSubject(surface, body, req) {
+ if (surface === 'chatgpt') {
+ const sub = chatgptSubject(body);
+ return sub ? `oai:${sub}` : null;
+ }
+ if (surface === 'grok') return grokSession(req);
+ return null;
+}
+
export function studioHandler({ surface = 'full' } = {}) {
return wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,HEAD,POST,OPTIONS', origins: '*', payments: false })) return;
@@ -95,12 +124,12 @@ export function studioHandler({ surface = 'full' } = {}) {
// Generation quota, burst then hourly, per IP. Applied only when the request
// actually calls a generation tool, so discovery is never throttled by it.
if (callsGenerationTool(body)) {
- const subject = surface === 'chatgpt' ? chatgptSubject(body) : null;
+ const subject = callerSubject(surface, body, req);
if (subject) {
const pool = await limits.studioGenPoolHourly(ip);
if (!pool.success) return rateLimited(res, pool, 'the free 3D studio is at capacity right now, please try again later');
}
- const caller = subject ? `oai:${subject}` : ip;
+ const caller = subject || ip;
const burst = await limits.studioGenBurst(caller);
if (!burst.success) return rateLimited(res, burst, 'generation rate limit, slow down and try again shortly');
const hourly = await limits.studioGenHourly(caller);
@@ -124,6 +153,12 @@ export function studioHandler({ surface = 'full' } = {}) {
res.statusCode = 200;
res.setHeader('content-type', 'application/json; charset=utf-8');
res.setHeader('mcp-protocol-version', PROTOCOL_VERSION);
+ if (surface === 'grok' && initializes(body)) {
+ res.setHeader('mcp-session-id', `grk_${randomUUID()}`);
+ // A browser MCP client cannot echo a header it is not allowed to read.
+ const exposed = res.getHeader('access-control-expose-headers');
+ res.setHeader('access-control-expose-headers', exposed ? `${exposed}, mcp-session-id` : 'mcp-session-id');
+ }
res.end(JSON.stringify(Array.isArray(body) ? responses : (responses[0] ?? null)));
});
}
diff --git a/api/mcp-grok.js b/api/mcp-grok.js
new file mode 100644
index 000000000..b1c6b49e4
--- /dev/null
+++ b/api/mcp-grok.js
@@ -0,0 +1,13 @@
+// three.ws 3D Studio for Grok Bot and the xAI Responses API.
+//
+// POST /api/mcp-grok JSON-RPC (initialize, tools/list, tools/call, resources/*)
+//
+// Every free studio tool, including the persona tools that give Grok a body.
+// Grok calls MCP from xAI's cloud with no published timeout and renders no
+// widget, so each call answers inside a budget with the model or a pending job,
+// and the instructions tell Grok to collect it and share links. Generation caps
+// key on the Mcp-Session-Id this surface issues, since every Grok user shares
+// xAI's egress. Transport, quota and breaker: ./_mcp-studio/handler.js.
+import { studioHandler } from './_mcp-studio/handler.js';
+
+export default studioHandler({ surface: 'grok' });
diff --git a/tests/mcp-grok.test.js b/tests/mcp-grok.test.js
new file mode 100644
index 000000000..075e15f9a
--- /dev/null
+++ b/tests/mcp-grok.test.js
@@ -0,0 +1,172 @@
+// The Grok surface (/api/mcp-grok). Grok Bot and the xAI Responses API call MCP
+// from xAI's cloud: no published tool-call timeout, no inline widget, and one
+// shared egress pool for every Grok user. These tests pin the three answers to
+// that: every call is bounded and hands back a pending job instead of hanging,
+// the model is told to collect it and share links, and the generation caps key
+// on the Mcp-Session-Id this surface issues rather than on xAI's IP.
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+
+vi.mock('../api/_mcp-studio/gpt-forge-client.js', async (importOriginal) => {
+ const real = await importOriginal();
+ return { ...real, generate: vi.fn(), rig: vi.fn(), directPrompt: vi.fn(async () => null) };
+});
+
+const limitCalls = [];
+vi.mock('../api/_lib/rate-limit.js', async (importOriginal) => {
+ const real = await importOriginal();
+ const pass = (name) => async (key) => {
+ limitCalls.push([name, key]);
+ return { success: true, limit: 1, remaining: 1, reset: Date.now() + 1000 };
+ };
+ return {
+ ...real,
+ limits: {
+ ...real.limits,
+ studioIp: pass('ip'),
+ studioGenBurst: pass('burst'),
+ studioGenHourly: pass('hourly'),
+ studioGenPoolHourly: pass('pool'),
+ studioGenerateGlobal: pass('global'),
+ },
+ };
+});
+
+import { generate } from '../api/_mcp-studio/gpt-forge-client.js';
+import { dispatch, toolCatalogFor, GROK_CALL_BUDGET_MS } from '../api/_mcp-studio/dispatch.js';
+import { callerSubject, grokSession } from '../api/_mcp-studio/handler.js';
+import grokHandler from '../api/mcp-grok.js';
+
+const req = { headers: { host: 'three.ws', 'x-forwarded-proto': 'https' } };
+const auth = { userId: null, rateKey: '127.0.0.1', scope: '' };
+const SID = 'grk_0f8e2c1a-5b6d-4e7f-8a9b-0c1d2e3f4a5b';
+
+function callMsg(name, args) {
+ return { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } };
+}
+
+// A minimal node-style req/res pair for driving the real HTTP handler.
+function httpPair(body, headers = {}) {
+ const payload = Buffer.from(JSON.stringify(body));
+ const req = {
+ method: 'POST',
+ url: '/api/mcp-grok',
+ headers: { host: 'three.ws', 'content-type': 'application/json', 'x-forwarded-for': '203.0.113.9', ...headers },
+ socket: { remoteAddress: '203.0.113.9' },
+ async *[Symbol.asyncIterator]() {
+ yield payload;
+ },
+ on(event, cb) {
+ if (event === 'data') cb(payload);
+ if (event === 'end') cb();
+ return this;
+ },
+ };
+ const out = { headers: {}, body: '' };
+ const res = {
+ statusCode: 200,
+ headersSent: false,
+ setHeader(k, v) {
+ out.headers[k.toLowerCase()] = v;
+ },
+ getHeader(k) {
+ return out.headers[k.toLowerCase()];
+ },
+ removeHeader(k) {
+ delete out.headers[k.toLowerCase()];
+ },
+ end(chunk) {
+ if (chunk) out.body += chunk;
+ this.headersSent = true;
+ },
+ write(chunk) {
+ out.body += chunk;
+ },
+ };
+ return { req, res, out };
+}
+
+afterEach(() => {
+ vi.mocked(generate).mockReset();
+ limitCalls.length = 0;
+});
+
+describe('grok surface catalog', () => {
+ it('offers every tool the full studio surface offers, persona tools included', () => {
+ const names = (s) => toolCatalogFor(s).map((t) => t.name).sort();
+ expect(names('grok')).toEqual(names('full'));
+ expect(names('grok')).toContain('create_agent_persona');
+ expect(names('grok')).toContain('check_job');
+ });
+
+ it('tells Grok to share links and collect pending jobs on initialize', async () => {
+ const r = await dispatch({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} }, auth, req, { surface: 'grok' });
+ const text = r.result.instructions;
+ expect(text).toContain('viewerUrl');
+ expect(text).toContain('check_job(job_id)');
+ expect(text).toContain('embed_url');
+ });
+});
+
+describe('grok call budget', () => {
+ it('bounds each generation with a deadline inside the budget', async () => {
+ vi.mocked(generate).mockResolvedValue({ status: 'done', glb_url: 'https://three.ws/cdn/a.glb' });
+ const before = Date.now();
+ await dispatch(callMsg('forge_free', { prompt: 'a reusable rocket booster' }), auth, req, { surface: 'grok' });
+ const opts = vi.mocked(generate).mock.calls[0][2];
+ expect(opts.deadline).toBeGreaterThan(before);
+ expect(opts.deadline).toBeLessThanOrEqual(Date.now() + GROK_CALL_BUDGET_MS);
+ });
+
+ it('returns a pending job with a check_job hint when the render outlives the budget', async () => {
+ vi.mocked(generate).mockResolvedValue({ _timedOut: true, job_id: 'job-abc123', status: 'running' });
+ const r = await dispatch(callMsg('forge_free', { prompt: 'a reusable rocket booster' }), auth, req, { surface: 'grok' });
+ expect(r.result.structuredContent.status).toBe('pending');
+ expect(r.result.structuredContent.jobId).toBe('job-abc123');
+ expect(r.result.content[0].text).toContain('check_job');
+ });
+});
+
+describe('grok per-session generation limits', () => {
+ it('reads a well-formed session id and rejects anything else', () => {
+ expect(grokSession({ headers: { 'mcp-session-id': SID } })).toBe(SID);
+ expect(grokSession({ headers: { 'mcp-session-id': 'grk_not-a-uuid' } })).toBeNull();
+ expect(grokSession({ headers: { 'mcp-session-id': 'oai:spoof' } })).toBeNull();
+ expect(grokSession({ headers: {} })).toBeNull();
+ });
+
+ it('keys only shared-egress surfaces on a subject, and the full surface stays per IP', () => {
+ const grokReq = { headers: { 'mcp-session-id': SID } };
+ expect(callerSubject('grok', callMsg('forge_free', {}), grokReq)).toBe(SID);
+ expect(callerSubject('full', callMsg('forge_free', {}), grokReq)).toBeNull();
+ const oai = { ...callMsg('forge_free', {}), params: { name: 'forge_free', arguments: {}, _meta: { 'openai/subject': 'v1/abcDEF123456' } } };
+ expect(callerSubject('chatgpt', oai, req)).toBe('oai:v1/abcDEF123456');
+ });
+
+ it('issues a session id on initialize and exposes it to browser clients', async () => {
+ const { req: r, res, out } = httpPair({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} });
+ await grokHandler(r, res);
+ expect(out.headers['mcp-session-id']).toMatch(/^grk_[0-9a-f-]{36}$/);
+ expect(out.headers['access-control-expose-headers']).toContain('mcp-session-id');
+ expect(JSON.parse(out.body).result.serverInfo.name).toBe('three-ws-3d-studio-free');
+ });
+
+ it('charges a generation to the session, behind the per-IP pool cap', async () => {
+ vi.mocked(generate).mockResolvedValue({ status: 'done', glb_url: 'https://three.ws/cdn/a.glb' });
+ const { req: r, res } = httpPair(callMsg('forge_free', { prompt: 'a lunar lander' }), { 'mcp-session-id': SID });
+ await grokHandler(r, res);
+ const byName = Object.fromEntries(limitCalls.map(([n, k]) => [n, k]));
+ expect(byName.pool).toBeDefined();
+ expect(byName.burst).toBe(SID);
+ expect(byName.hourly).toBe(SID);
+ });
+
+ it('falls back to per-IP caps when the client never echoes a session', async () => {
+ vi.mocked(generate).mockResolvedValue({ status: 'done', glb_url: 'https://three.ws/cdn/a.glb' });
+ const { req: r, res } = httpPair(callMsg('forge_free', { prompt: 'a lunar lander' }));
+ await grokHandler(r, res);
+ const byName = Object.fromEntries(limitCalls.map(([n, k]) => [n, k]));
+ expect(byName.pool).toBeUndefined();
+ expect(byName.burst).not.toBe(SID);
+ });
+});
diff --git a/vercel.json b/vercel.json
index f7af5dc7b..2f66fe0e1 100644
--- a/vercel.json
+++ b/vercel.json
@@ -118,7 +118,7 @@
"includeFiles": "{src/solana/vanity/wasm/**,examples/skills/**,data/pages.json,data/archives/**,data/rss/**,data/_generated/**,sdk/src/sas-config.json}",
"maxDuration": 60
},
- "{api/mcp-studio,api/mcp-chatgpt,api/forge-nim,api/nim-forge,api/launch/mm,api/cron/avaturn-seed-cron,api/irl/interactions-stream}.js": {
+ "{api/mcp-studio,api/mcp-chatgpt,api/mcp-grok,api/forge-nim,api/nim-forge,api/launch/mm,api/cron/avaturn-seed-cron,api/irl/interactions-stream}.js": {
"maxDuration": 300
},
"api/x402/remix-asset.js": {