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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Shared HTTP handler for the free three.ws 3D Studio MCP surfaces.
//
// POST JSON-RPC (initialize, tools/list, tools/call, resources/*). A single
// tools/call that carries `_meta.progressToken`, from a client that
// accepts text/event-stream, is answered as an SSE stream: progress
// notifications while the job runs, then the result.
// GET not offered (no server-initiated stream), answers 405
// OPTIONS CORS preflight
//
// 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
// api/mcp-grok.js surface 'grok' every tool, for Grok Bot and the xAI API,
// plus the account's agent tools once
// the caller signs in
// 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.
//
// There is no payment path anywhere in this server: generation runs
// operator-funded over /api/forge, whose server-side keys cover provider cost.
// Only the grok surface reads a credential (signedInAccount below), and only to
// add the account's agent tools; the free tools never need one.
// Abuse protection is real: a per-caller transport cap plus a per-caller
// generation burst and hourly quota (../_lib/rate-limit.js), enforced whenever
// Redis is healthy. The caller is, in order: a verified install token on the
// connector URL (./install-token.js), the per-user subject a shared-egress
// surface carries, else the IP. A capped generation answers a JSON-RPC error
// that names the limit, when it resets and the connector URL that lifts it.
// Because every studio tool routes through a zero-cost free lane, these
// 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 { cors, wrap, readJson, rateLimited, setRateLimitHeaders } from '../_lib/http.js';
import { limits, clientIp, STUDIO_LIMITS } from '../_lib/rate-limit.js';
import { dispatch, PROTOCOL_VERSION, surfaceServer, surfaceServesAccounts } from './dispatch.js';
import { authenticateBearer, extractBearer } from '../_lib/auth.js';
import { acceptedAudiences, mcpResourceFor } from '../_lib/mcp-resources.js';
import { send401 } from '../_mcp/auth.js';
import { TOOL_NAMES } from './tools.js';
import { isIdempotentRepeat, progressReporter } from './jobs.js';
import { installTokenFrom, studioOrigin, INSTALL_PARAM } from './install-token.js';
import { trackMcpRequest, authKindOf } from '../_lib/mcp-client-analytics.js';
// check_job collects a job that is already running rather than starting one: it
// must never burn the caller's generation quota, or collecting a pending job
// could be rate-blocked by the very generation that created it. It rides the
// transport cap only.
const GEN_TOOLS = new Set(TOOL_NAMES.filter((name) => name !== 'check_job'));
/** Does calling this tool start a generation that counts against the quota? */
export function isGenerationTool(name) {
return GEN_TOOLS.has(name);
}
function rpcError(res, status, code, message, extra = {}) {
res.statusCode = status;
res.setHeader('content-type', 'application/json; charset=utf-8');
res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code, message, ...(Object.keys(extra).length ? { data: extra } : {}) } }));
}
// The progress token a single tools/call asked to be updated on, or null. A
// batch is answered as one JSON array, so it never streams.
export function progressTokenOf(body) {
if (!body || Array.isArray(body) || body.method !== 'tools/call') return null;
const token = body.params?._meta?.progressToken;
return (typeof token === 'string' && token.length > 0 && token.length <= 256) || Number.isInteger(token) ? token : null;
}
function acceptsEventStream(req) {
return /\btext\/event-stream\b/i.test(String(req?.headers?.accept || ''));
}
// An idle proxy can close a quiet stream between status frames (a submit can run
// 40 s before the first one), so a comment line goes out this often.
const SSE_KEEPALIVE_MS = 15_000;
// Answer one tools/call as a Streamable HTTP SSE response: each status frame of
// the job becomes a notifications/progress message (./jobs.js
// progressReporter), and the JSON-RPC result is the last event.
async function streamToolCall(res, msg, auth, req, { surface, caller, token, account = null }) {
res.statusCode = 200;
res.setHeader('content-type', 'text/event-stream; charset=utf-8');
res.setHeader('cache-control', 'no-cache, no-transform');
res.setHeader('x-accel-buffering', 'no');
res.setHeader('mcp-protocol-version', PROTOCOL_VERSION);
res.flushHeaders?.();
const send = (message) => {
if (!res.writableEnded) res.write(`event: message\ndata: ${JSON.stringify(message)}\n\n`);
};
const keepAlive = setInterval(() => {
if (!res.writableEnded) res.write(': keep-alive\n\n');
}, SSE_KEEPALIVE_MS);
keepAlive.unref?.();
try {
const report = progressReporter(token, send);
report({ status: 'queued', stage: 'submit' }, 'request');
const response = await dispatch(msg, auth, req, { surface, caller, onProgress: report, account });
if (response !== null) send(response);
} finally {
clearInterval(keepAlive);
res.end();
}
}
// Does the (possibly batched) body invoke any generation tool? Used to apply the
// cost-bearing generation quota only to calls that actually generate.
function callsGenerationTool(body) {
const batch = Array.isArray(body) ? body : [body];
return batch.some((m) => m && m.method === 'tools/call' && isGenerationTool(m?.params?.name));
}
// Is every generation call in the body a repeat of an idempotency_key its
// caller already used? Those return the first call's job and start nothing, so
// a scheduled agent's retry never spends its generation quota.
async function onlyRepeats(body, caller) {
const batch = Array.isArray(body) ? body : [body];
const calls = batch.filter((m) => m && m.method === 'tools/call' && isGenerationTool(m?.params?.name));
const repeats = await Promise.all(calls.map((m) => isIdempotentRepeat(m, caller)));
return repeats.every(Boolean);
}
// ChatGPT sends an anonymized, per-user `openai/subject` on every tool call and
// documents it for rate limiting. All ChatGPT traffic shares OpenAI's egress
// IPs, so on that surface the per-caller caps key on it. Bounded to a sane
// token shape; anything else falls back to the IP.
const SUBJECT_RE = /^[A-Za-z0-9_.:/+=-]{8,256}$/;
export function chatgptSubject(body) {
const batch = Array.isArray(body) ? body : [body];
for (const m of batch) {
const sub = m?.params?._meta?.['openai/subject'];
if (typeof sub === 'string' && SUBJECT_RE.test(sub)) return sub;
}
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;
}
/** 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;
}
/**
* Who the per-caller caps charge, on every surface: a verified install token
* first, then a signed-in account, then the surface's own subject, then the IP.
* An unknown or forged token is ignored, so the request keys exactly as it
* would with no token at all.
* @returns {{ key: string, kind: 'install'|'account'|'session'|'chatgpt_user'|'ip' }}
*/
export function studioCaller(surface, body, req, ip, install = installTokenFrom(req), account = null) {
if (install) return { key: `inst:${install.id}`, kind: 'install' };
if (account?.userId) return { key: `acct:${account.userId}`, kind: 'account' };
const subject = callerSubject(surface, body, req);
if (subject) return { key: subject, kind: surface === 'chatgpt' ? 'chatgpt_user' : 'session' };
return { key: ip, kind: 'ip' };
}
// JSON-RPC implementation-defined server error, the code the authenticated MCP
// server uses for rate_limited too (api/_mcp/tools/agents.js).
export const STUDIO_RATE_LIMITED = -32000;
const CALLER_SCOPE = {
install: 'this install token',
account: 'this three.ws account',
session: 'this MCP session',
chatgpt_user: 'this ChatGPT user',
ip: 'your IP address',
};
const WINDOW_WORDS = { '1 m': 'minute', '1 h': 'hour' };
// Each generation bucket a denial can name: the numbers come from the limiter's
// own table, so the message can never drift from what is enforced.
const GEN_BUCKETS = {
pool: { id: 'generation_ip_pool', spec: STUDIO_LIMITS.genPoolHourly, scope: () => 'one source IP, across every caller on it' },
burst: { id: 'generation_burst', spec: STUDIO_LIMITS.genBurst, scope: (kind) => CALLER_SCOPE[kind] },
hourly: { id: 'generation_hourly', spec: STUDIO_LIMITS.genHourly, scope: (kind) => CALLER_SCOPE[kind] },
global: { id: 'generation_global', spec: STUDIO_LIMITS.genGlobal, scope: () => 'the whole free studio, every caller combined' },
};
function resetAt(result) {
const reset = Number(result?.reset);
return Number.isFinite(reset) && reset > Date.now() ? new Date(reset) : new Date(Date.now() + 1000);
}
/**
* The remedy for a capped caller. A per-IP caller is told to get an install
* token (one URL of its own); a caller that already has its own budget (a token
* or an account), or hit a cap no token lifts, is pointed at the signed-in
* server, whose free lane is metered per account.
*/
export function studioRemedy(kind, bucket, surfacePath) {
const origin = studioOrigin();
const installEndpoint = `${origin}/api/mcp-studio/install`;
const accountServer = `${origin}/api/mcp-3d`;
if (bucket !== 'global' && bucket !== 'pool' && kind !== 'install' && kind !== 'account') {
return {
kind: 'install_token',
install_endpoint: installEndpoint,
connector_url: `${origin}${surfacePath}?${INSTALL_PARAM}=<token>`,
text:
`Lift it with a free install token: POST ${installEndpoint} (no account, no key) and reconnect at ` +
`${origin}${surfacePath}?${INSTALL_PARAM}=<token>, which gets its own budget. Or sign in at ${accountServer} ` +
'(OAuth 2.1), metered per account.',
};
}
return {
kind: 'account',
oauth_server: accountServer,
text: `Wait for the reset, or sign in at ${accountServer} (OAuth 2.1), whose generation is metered per account instead.`,
};
}
/**
* The JSON-RPC error for a capped generation: what limit, when it resets, and
* the connector URL that lifts it. Exported for tests and docs.
*/
export function studioDenial({ bucket, kind, result, surfacePath, now = Date.now() }) {
const b = GEN_BUCKETS[bucket];
const at = resetAt(result);
const retryAfter = Math.max(1, Math.ceil((at.getTime() - now) / 1000));
const remedy = studioRemedy(kind, bucket, surfacePath);
const per = WINDOW_WORDS[b.spec.window] || b.spec.window;
const message =
`Rate limited: the free 3D studio allows ${b.spec.limit} generations per ${per} for ${b.scope(kind)}, ` +
`and that limit is used up. It resets at ${at.toISOString()} (in ${retryAfter} s). ${remedy.text}`;
return {
code: STUDIO_RATE_LIMITED,
message,
data: {
reason: 'rate_limited',
limit: b.id,
max: b.spec.limit,
window: b.spec.window,
keyed_on: bucket === 'global' ? 'platform' : bucket === 'pool' ? 'ip' : kind,
reset_at: at.toISOString(),
retry_after: retryAfter,
...(result?.reason ? { limiter: result.reason } : {}),
remedy: remedyData(remedy),
},
};
}
// The machine-readable half of a remedy; its text already rides the message.
function remedyData({ text: _text, ...rest }) {
return rest;
}
// Every request in the body that expects a response gets the same denial, so a
// client matching responses by id sees its own call refused, never a stray id.
function rpcDenial(res, body, denial, result) {
setRateLimitHeaders(res, result);
res.setHeader('retry-after', String(denial.data.retry_after));
res.statusCode = 200;
res.setHeader('content-type', 'application/json; charset=utf-8');
res.setHeader('mcp-protocol-version', PROTOCOL_VERSION);
const one = (m) => ({ jsonrpc: '2.0', id: m?.id ?? null, error: denial });
if (Array.isArray(body)) {
res.end(JSON.stringify(body.filter((m) => m && m.id !== undefined).map(one)));
return;
}
res.end(JSON.stringify(one(body)));
}
// `?auth=oauth` on the connector URL asks for sign-in: an MCP client only
// starts OAuth when a server answers 401, and an anonymous request here is
// otherwise served, so a connector set to OAuth 2.1 needs a URL that refuses it.
export const SIGN_IN_PARAM = 'auth';
function wantsSignIn(req) {
try {
return new URL(req.url || '/', 'http://localhost').searchParams.get(SIGN_IN_PARAM) === 'oauth';
} catch {
return false;
}
}
/**
* The account a request on an account-serving surface signed in as. Returns
* { account } (null when anonymous) or { refused: true } after answering 401:
* a bearer that does not verify (expired, revoked, wrong audience) is refused
* rather than quietly served anonymously, so the client re-authenticates
* instead of losing its account tools without a word.
*/
export async function signedInAccount(req, res, surfacePath) {
const bearer = extractBearer(req);
const refuse = (message) => {
// A browser MCP client cannot start OAuth off a header it may not read.
const exposed = res.getHeader('access-control-expose-headers');
res.setHeader('access-control-expose-headers', exposed ? `${exposed}, www-authenticate` : 'www-authenticate');
send401(res, message, { req, resourcePath: surfacePath });
return { refused: true };
};
if (!bearer) {
if (wantsSignIn(req)) {
return refuse('sign in to add your three.ws agent tools to this connector');
}
return { account: null };
}
const account = await authenticateBearer(bearer, { audience: acceptedAudiences(mcpResourceFor(surfacePath)) });
if (!account) return refuse('missing or invalid access token');
return { account };
}
export function studioHandler({ surface = 'full' } = {}) {
const servesAccounts = surfaceServesAccounts(surface);
return wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,HEAD,POST,OPTIONS', origins: '*', payments: false })) return;
// No server-initiated SSE stream, this server answers requests synchronously.
if (req.method === 'GET' || req.method === 'HEAD') {
res.statusCode = 405;
res.setHeader('allow', 'POST, OPTIONS');
res.setHeader('content-type', 'application/json; charset=utf-8');
res.end(JSON.stringify({ error: 'method_not_allowed', error_description: 'POST JSON-RPC to this MCP endpoint' }));
return;
}
if (req.method !== 'POST') return rpcError(res, 405, -32600, 'method not supported');
const ip = clientIp(req);
const install = installTokenFrom(req);
const surfacePath = new URL(req.url || '/api/mcp-studio', 'http://localhost').pathname;
// Cheap transport cap on every request (discovery + calls), per install
// token when the connector URL carries one, so callers sharing a cloud
// agent's egress do not share one flood guard either.
const ipRl = await limits.studioIp(install ? `inst:${install.id}` : ip);
if (!ipRl.success) {
const at = resetAt(ipRl);
const remedy = studioRemedy(install ? 'install' : 'ip', 'transport', surfacePath);
return rateLimited(
res,
ipRl,
`too many requests: ${STUDIO_LIMITS.transport.limit} per minute for ${install ? 'this install token' : 'your IP address'}, resets at ${at.toISOString()}. ${remedy.text}`,
{ reset_at: at.toISOString(), remedy: remedyData(remedy) },
);
}
let body;
try {
body = await readJson(req, 1_000_000);
} catch (err) {
return rpcError(res, err.status || 400, -32700, err.message || 'invalid JSON');
}
const batch = Array.isArray(body) ? body : [body];
if (batch.length > 16) return rpcError(res, 400, -32600, 'batch too large (max 16)');
let account = null;
if (servesAccounts) {
const signIn = await signedInAccount(req, res, surfacePath);
if (signIn.refused) return;
account = signIn.account;
// The same per-account flood guard /api/mcp applies to these tools.
if (account) {
const userRl = await limits.mcpUser(account.userId);
if (!userRl.success) {
const at = resetAt(userRl);
return rateLimited(res, userRl, `too many requests for this three.ws account, resets at ${at.toISOString()}`, {
reset_at: at.toISOString(),
});
}
}
}
// Who this request is: the key the per-caller caps charge, and the owner of
// any idempotency_key it sends (./jobs.js).
const caller = studioCaller(surface, body, req, ip, install, account);
// Generation quota, burst then hourly, per caller. Applied only when the
// request actually calls a generation tool, so discovery is never throttled
// by it. A denial is a JSON-RPC error on HTTP 200: an MCP client hands that
// message to the model, where a 429 body is often dropped by the transport.
if (callsGenerationTool(body) && !(await onlyRepeats(body, caller.key))) {
const deny = (bucket, result) =>
rpcDenial(res, body, studioDenial({ bucket, kind: caller.kind, result, surfacePath }), result);
// Any caller key other than the IP is one the client chose, so one source
// IP is still held to a pool across all of them.
if (caller.kind !== 'ip') {
const pool = await limits.studioGenPoolHourly(ip);
if (!pool.success) return deny('pool', pool);
}
const burst = await limits.studioGenBurst(caller.key);
if (!burst.success) return deny('burst', burst);
const hourly = await limits.studioGenHourly(caller.key);
if (!hourly.success) return deny('hourly', hourly);
// Platform-wide circuit breaker across ALL free-studio callers, backstops
// the shared GPU/provider budget when many distinct IPs, each under their
// own hourly cap, would collectively drain it.
const global = await limits.studioGenerateGlobal();
if (!global.success) return deny('global', global);
}
// Anonymous principal, no auth, no scope. rateKey carries the IP for usage logs.
const auth = { userId: null, rateKey: ip, scope: '' };
// Issues the Mcp-Session-Id on initialize (grk_ on the grok surface, where
// the per-caller caps key on it) and records which client opened the
// session and what it calls (../_lib/mcp-client-analytics.js).
trackMcpRequest({
body,
req,
res,
surface: surfaceServer(surface),
authKind: install ? 'install' : account ? authKindOf(account) : 'anonymous',
sessionPrefix: surface === 'grok' ? 'grk' : 'mcs',
});
const token = progressTokenOf(body);
if (token !== null && acceptsEventStream(req)) {
return streamToolCall(res, body, auth, req, { surface, caller: caller.key, token, account });
}
const responses = [];
for (const msg of batch) {
const r = await dispatch(msg, auth, req, { surface, caller: caller.key, account });
if (r !== null) responses.push(r);
}
res.statusCode = 200;
res.setHeader('content-type', 'application/json; charset=utf-8');
res.setHeader('mcp-protocol-version', PROTOCOL_VERSION);
res.end(JSON.stringify(Array.isArray(body) ? responses : (responses[0] ?? null)));
});
}