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(connect): generate a cloud-agent connector URL with a free install token on /connect

nirholase92209633b9b
diff --git a/data/changelog.json b/data/changelog.json
index 676f87a59..6307d3c83 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,13 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-08",
+ "title": "Your own free 3D quota when you connect through Grok Bot or another cloud agent",
+ "summary": "Cloud agents like Grok Bot reach three.ws from one shared address, so every user of that agent used to share one free 3D quota. Now you can generate a free install token on the Connect page (pick 3D Studio (free), then Generate my connector URL) or with one POST to /api/mcp-studio/install, and add the connector with that URL. Your generations then count against a quota of your own: 4 a minute and 30 an hour. No account, no key, and the token works on every free studio URL, including the Grok one. When a limit is reached, the message now says which limit, exactly when it resets, and how to lift it.",
+ "tags": ["feature", "improvement"],
+ "link": "/connect?server=three-ws-studio"
+ },
{
"date": "2026-10-08",
"title": "A paid call that fails after you were charged never asks you to pay again",
diff --git a/docs/grok.md b/docs/grok.md
index f798eb499..a358444c6 100644
--- a/docs/grok.md
+++ b/docs/grok.md
@@ -123,8 +123,19 @@ session is free, so a per-IP pool cap and the platform-wide breaker still bound
the total, the same design the ChatGPT surface uses with OpenAI's per-user
subject. A client that never echoes the session falls back to per-IP limits.
-**When generation is refused.** A rate-limited request answers HTTP 429 with a
-`retry-after` header and a plain sentence Grok can relay.
+**A quota that survives reconnects.** A session lasts one connection. For a
+budget that stays yours across every Grok Bot task, add the connector with an
+install token: `curl -s -X POST https://three.ws/api/mcp-studio/install` (or
+**Generate my connector URL** on [/connect](/connect?server=three-ws-studio))
+returns a `connector_urls.grok` of the form
+`https://three.ws/api/mcp-grok?install=<token>`. The caps then key on the token,
+ahead of the session and the IP. It is free, anonymous and never expires; see
+[install tokens](./mcp-studio.md#connector-url-for-cloud-agents-install-tokens).
+
+**When generation is refused.** A capped generation answers a JSON-RPC error
+whose message Grok can relay as is: which limit was hit, when it resets, and the
+connector URL that lifts it (an install token, or the signed-in server for a
+caller that already has one).
## How it fits the platform
diff --git a/docs/mcp-studio.md b/docs/mcp-studio.md
index 49121f5e3..90ee7e5b8 100644
--- a/docs/mcp-studio.md
+++ b/docs/mcp-studio.md
@@ -59,6 +59,56 @@ curl -s https://three.ws/api/mcp-studio \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
+### Connector URL for cloud agents (install tokens)
+
+Grok Bot, the xAI Responses API and other hosted agents call MCP from their
+vendor's cloud, so every user of one agent reaches three.ws from the same few
+IPs. Keyed per IP, they would all share one free quota. An **install token**
+gives one installation its own quota, free and anonymous: no account, no key.
+
+1. Mint a token (or click **Generate my connector URL** on
+ [/connect](/connect?server=three-ws-studio) with the free studio selected):
+
+ ```bash
+ curl -s -X POST https://three.ws/api/mcp-studio/install
+ ```
+
+ ```json
+ {
+ "token": "tws_tmlst1_a2b4b...",
+ "created_at": "2026-10-08T19:29:13.000Z",
+ "connector_url": "https://three.ws/api/mcp-studio?install=tws_tmlst1_a2b4b...",
+ "connector_urls": {
+ "studio": "https://three.ws/api/mcp-studio?install=tws_tmlst1_a2b4b...",
+ "grok": "https://three.ws/api/mcp-grok?install=tws_tmlst1_a2b4b...",
+ "chatgpt": "https://three.ws/api/mcp-chatgpt?install=tws_tmlst1_a2b4b..."
+ },
+ "limits": { "generations_per_minute": 4, "generations_per_hour": 30, "requests_per_minute": 300 },
+ "note": "Keep this URL private: anyone holding the token spends its budget. It never expires and unlocks no account or payment."
+ }
+ ```
+
+2. Add the connector with that URL and **No authentication**. The same token
+ works on every studio door; Grok Bot users want the `grok` URL.
+
+How it behaves:
+
+- The transport cap and the generation burst and hourly caps key on the token
+ instead of the IP. Two tokens from one IP have independent budgets.
+- A missing, malformed or forged token is ignored and the request keys exactly
+ as it would without one (per IP, or per ChatGPT user / MCP session on those
+ doors).
+- Minting is limited to 10 tokens an hour per IP, and every token-keyed caller
+ still shares the per-IP pool (300 generations an hour) and the platform-wide
+ breaker, so tokens add per-caller fairness, never extra total GPU budget.
+- A token is self-authenticating (an HMAC over its mint time and a random
+ nonce, keyed by `MCP_INSTALL_SECRET`, else `JWT_SECRET`), so nothing is stored
+ and verifying one costs no database round trip. It unlocks no tool, account
+ or payment; it is only a rate-limit identity, and request logs redact it.
+
+`node scripts/probe-mcp-install-tokens.mjs --base <origin>` mints two tokens,
+caps the first and shows the second still admitted, end to end.
+
### ChatGPT custom GPT (Actions)
The same free lane also ships as a REST Actions surface for the **"three.ws 3D
@@ -434,15 +484,21 @@ rather than being excluded, so a free-lane outage degrades to a slower or
costlier engine instead of failing the user's request. Either way the cost lands
on the platform and never on the caller: no key, no account, no payment surface.
-The endpoint still enforces real per-IP abuse protection (`api/_lib/rate-limit.js`):
+The endpoint still enforces real per-caller abuse protection
+(`api/_lib/rate-limit.js`, numbers in its `STUDIO_LIMITS`). The caller is a
+verified [install token](#connector-url-for-cloud-agents-install-tokens) when the
+connector URL carries one, else the door's own per-user identity, else the IP:
-- **Burst:** 4 generations / minute / IP
-- **Hourly:** 30 generations / hour / IP
+- **Burst:** 4 generations / minute / caller
+- **Hourly:** 30 generations / hour / caller
+- **Install tokens:** on any door, `?install=<token>` keys the caps (and the
+ transport cap) on the token. Minting is capped at 10 / hour / IP.
- **ChatGPT users:** every ChatGPT user reaches `/api/mcp-chatgpt` from OpenAI's
shared egress IPs, so there the burst and hourly caps key on the anonymized
- per-user `openai/subject` ChatGPT sends with each tool call, and one IP is
- held to 300 generations / hour in total. Without the subject the caps key on
- the IP as above.
+ per-user `openai/subject` ChatGPT sends with each tool call. On `/api/mcp-grok`
+ they key on the `Mcp-Session-Id` the server issues. Whenever the caller is not
+ the IP (token, subject or session), one IP is still held to 300 generations /
+ hour in total. Without any of them the caps key on the IP as above.
- **Persona writes:** 20 / minute / IP (`create_agent_persona`, `persona_say`;
`get_agent_persona` is a read and rides the transport cap)
- **Transport:** 300 requests / minute / IP (discovery, never throttled by the
@@ -455,6 +511,44 @@ The generation quota is charged only when a request actually calls a generation
tool, so `initialize`, `tools/list`, `resources/list`, and `check_job` are never
throttled by it.
+A capped generation answers HTTP 200 with a JSON-RPC error, because MCP clients
+pass that message to the model while many drop a 429 body. `Retry-After` and the
+`RateLimit-*` headers are still set. The message names the limit, when it resets
+and how to lift it:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 5,
+ "error": {
+ "code": -32000,
+ "message": "Rate limited: the free 3D studio allows 4 generations per minute for your IP address, and that limit is used up. It resets at 2026-10-08T19:30:38.140Z (in 55 s). Lift it with a free install token: POST https://three.ws/api/mcp-studio/install (no account, no key) and reconnect at https://three.ws/api/mcp-studio?install=<token>, which gets its own budget. Or sign in at https://three.ws/api/mcp-3d (OAuth 2.1), metered per account.",
+ "data": {
+ "reason": "rate_limited",
+ "limit": "generation_burst",
+ "max": 4,
+ "window": "1 m",
+ "keyed_on": "ip",
+ "reset_at": "2026-10-08T19:30:38.140Z",
+ "retry_after": 55,
+ "remedy": {
+ "kind": "install_token",
+ "install_endpoint": "https://three.ws/api/mcp-studio/install",
+ "connector_url": "https://three.ws/api/mcp-studio?install=<token>"
+ }
+ }
+ }
+}
+```
+
+`data.limit` is one of `generation_burst`, `generation_hourly`,
+`generation_ip_pool` and `generation_global`; `data.keyed_on` is `install`,
+`session`, `chatgpt_user`, `ip` or `platform`. A caller that already holds a
+token, or hits the per-IP pool or the platform-wide breaker, gets
+`remedy.kind: "account"` with `oauth_server` instead, since a new token would
+not help. The transport cap (300 requests a minute) still answers HTTP 429 with
+the same `reset_at` and `remedy` fields.
+
Because the lanes are zero-cost, the **per-IP** caps **fail open** if the
rate-limiter backend has an outage: a Redis blip must never dead-end a free
feature (the same posture as the paid server's own free lane). The platform-wide
diff --git a/pages/connect.html b/pages/connect.html
index 96566dd07..7b534d732 100644
--- a/pages/connect.html
+++ b/pages/connect.html
@@ -36,7 +36,10 @@
a { color: inherit; }
code, pre, kbd { font-family: var(--font-mono, ui-monospace, monospace); }
- .cn-wrap { max-width: var(--cn-maxw); margin: 0 auto; padding: 0 18px 96px; }
+ /* body is a column flex container, where auto margins shrink-wrap an item
+ to its content: width: 100% keeps a long connector URL scrolling inside
+ its box instead of widening the page past the viewport. */
+ .cn-wrap { width: 100%; max-width: var(--cn-maxw); margin: 0 auto; padding: 0 18px 96px; }
/* ── hero ───────────────────────────────────────────────────────── */
.cn-hero { padding: 40px 0 10px; }
@@ -96,6 +99,20 @@
.cn-url-label { flex: none; display: grid; place-items: center; padding: 0 12px; font-size: 0.72rem; font-weight: 650; text-transform: uppercase; letter-spacing: 0.06em; color: var(--ink-dim); border-right: 1px solid var(--stroke); }
.cn-url code { flex: 1; min-width: 0; padding: 13px 14px; font-size: 0.95rem; color: var(--ink-bright, var(--ink)); overflow-x: auto; white-space: nowrap; }
+ /* ── cloud-agent connector URL (keyless studio servers) ──────────── */
+ .cn-cloud {
+ margin-top: 14px; padding: 16px 16px 14px; border: 1px dashed var(--stroke-strong); border-radius: var(--radius-md, 10px);
+ background: var(--surface-1, rgba(255,255,255,0.03)); animation: cn-in var(--duration-base, 180ms) var(--ease-standard) both;
+ }
+ .cn-cloud[hidden] { display: none; }
+ .cn-cloud h3 { margin: 0 0 4px; font-size: 0.95rem; color: var(--ink-bright, var(--ink)); }
+ .cn-cloud > p { margin: 0 0 12px; font-size: 0.86rem; line-height: 1.55; color: var(--ink-dim); max-width: 72ch; }
+ .cn-cloud .cn-url { margin-top: 10px; }
+ .cn-cloud .cn-url[hidden] { display: none; }
+ .cn-cloud .cn-url-label { min-width: 92px; }
+ .cn-btn[aria-busy="true"] { opacity: 0.7; cursor: progress; }
+ .cn-btn:disabled { cursor: not-allowed; }
+
/* ── buttons ────────────────────────────────────────────────────── */
.cn-btn {
display: inline-flex; align-items: center; justify-content: center; gap: 8px; text-decoration: none;
@@ -167,6 +184,8 @@
.cn-url-label { display: none; }
.cn-url code { flex-basis: 100%; }
.cn-url .cn-btn { flex: 1; border-width: 1px 0 0 0; }
+ .cn-cloud .cn-url-label { display: block; flex-basis: 100%; padding: 9px 14px 0; border-right: 0; }
+ .cn-cloud .cn-url code { padding-top: 6px; }
.cn-panel { padding: 16px 14px 18px; }
}
@media (prefers-reduced-motion: reduce) {
@@ -216,6 +235,23 @@
<span data-i18n="connect.copy_url">Copy URL</span>
</button>
</div>
+
+ <div class="cn-cloud" id="cn-cloud" aria-labelledby="cn-cloud-title" hidden>
+ <h3 id="cn-cloud-title" data-i18n="connect.connector_url_for_cloud_agents">Connector URL for cloud agents</h3>
+ <p data-i18n-html="connect.cloud_agents_share_one_ip">Grok Bot and other hosted agents reach three.ws from one shared IP, so every user of that agent shares one free quota. A free <strong>install token</strong> gives your connector a quota of its own. No account, no key.</p>
+ <button type="button" class="cn-btn" data-variant="primary" id="cn-cloud-make">Generate my connector URL</button>
+ <div class="cn-url" id="cn-cloud-any-row" hidden>
+ <span class="cn-url-label" data-i18n="connect.any_client">Any client</span>
+ <code id="cn-cloud-any"></code>
+ <button type="button" class="cn-btn" data-copy-target="cn-cloud-any"><span data-i18n="connect.copy">Copy</span></button>
+ </div>
+ <div class="cn-url" id="cn-cloud-grok-row" hidden>
+ <span class="cn-url-label" data-i18n="connect.grok_bot">Grok Bot</span>
+ <code id="cn-cloud-grok"></code>
+ <button type="button" class="cn-btn" data-copy-target="cn-cloud-grok"><span data-i18n="connect.copy">Copy</span></button>
+ </div>
+ <p class="cn-note" id="cn-cloud-note" role="status" aria-live="polite"></p>
+ </div>
</section>
<section class="cn-step" aria-labelledby="cn-step2">
@@ -478,6 +514,84 @@
for (const el of document.querySelectorAll('.cn-name')) el.textContent = name;
}
+ // ── cloud-agent connector URL ───────────────────────────────────────
+ // Keyless studio servers accept ?install=<token>, which keys their free
+ // quota on the token instead of the caller's IP. The token comes from the
+ // real mint endpoint and is kept in this browser, so a revisit shows the
+ // same URL instead of minting another (minting is rate-limited per IP).
+ const INSTALL_PATHS = new Set(['/api/mcp-studio', '/api/mcp-grok', '/api/mcp-chatgpt']);
+ const INSTALL_STORE = 'twx_mcp_install';
+ const cloudEl = document.getElementById('cn-cloud');
+ const cloudBtn = document.getElementById('cn-cloud-make');
+ const cloudNote = document.getElementById('cn-cloud-note');
+
+ function readInstall() {
+ try {
+ const saved = JSON.parse(localStorage.getItem(INSTALL_STORE) || 'null');
+ return saved && typeof saved.token === 'string' && saved.connector_urls ? saved : null;
+ } catch {
+ return null;
+ }
+ }
+ function writeInstall(minted) {
+ try {
+ localStorage.setItem(INSTALL_STORE, JSON.stringify({ token: minted.token, created_at: minted.created_at, connector_urls: minted.connector_urls }));
+ } catch {
+ // Private mode: the URL is still shown, it just is not remembered.
+ }
+ }
+ function setCloudNote(text, tone) {
+ cloudNote.textContent = text;
+ if (tone) cloudNote.dataset.tone = tone; else delete cloudNote.dataset.tone;
+ }
+ function showInstall(minted) {
+ const urls = minted?.connector_urls;
+ document.getElementById('cn-cloud-any').textContent = urls?.studio || '';
+ document.getElementById('cn-cloud-grok').textContent = urls?.grok || '';
+ document.getElementById('cn-cloud-any-row').hidden = !urls?.studio;
+ document.getElementById('cn-cloud-grok-row').hidden = !urls?.grok;
+ cloudBtn.textContent = urls ? 'Replace with a new token' : 'Generate my connector URL';
+ if (urls) delete cloudBtn.dataset.variant; else cloudBtn.dataset.variant = 'primary';
+ if (urls) {
+ const since = minted.created_at ? new Date(minted.created_at).toLocaleDateString() : null;
+ setCloudNote(`Keep it private: anyone with this URL uses its quota.${since ? ` Token created ${since}.` : ''} The same token works on every free studio URL.`);
+ }
+ }
+ function updateCloud(server) {
+ const path = new URL(server.endpoint).pathname;
+ const keyless = INSTALL_PATHS.has(path) && authPill(server).tone === 'free';
+ cloudEl.hidden = !keyless;
+ if (keyless) showInstall(readInstall());
+ }
+ cloudBtn.addEventListener('click', async () => {
+ cloudBtn.disabled = true;
+ cloudBtn.setAttribute('aria-busy', 'true');
+ const label = cloudBtn.textContent;
+ cloudBtn.textContent = 'Generating...';
+ setCloudNote('');
+ try {
+ const res = await fetch('/api/mcp-studio/install', { method: 'POST', headers: { accept: 'application/json' } });
+ const body = await res.json().catch(() => null);
+ if (!res.ok || !body?.token) {
+ cloudBtn.textContent = label;
+ const wait = Number(res.headers.get('retry-after'));
+ const msg = res.status === 429
+ ? `You've made several tokens from this network in the last hour.${wait > 0 ? ` Try again in ${Math.ceil(wait / 60)} min,` : ''} or reuse one you already have: it works on every free studio URL.`
+ : body?.error_description || `Couldn't create a token (HTTP ${res.status}). Try again in a moment.`;
+ setCloudNote(msg, 'error');
+ return;
+ }
+ writeInstall(body);
+ showInstall(body);
+ } catch {
+ cloudBtn.textContent = label;
+ setCloudNote("Couldn't reach three.ws. Check your connection and try again.", 'error');
+ } finally {
+ cloudBtn.disabled = false;
+ cloudBtn.removeAttribute('aria-busy');
+ }
+ });
+
function select(server, updateUrl) {
state.selected = server;
for (const btn of serversEl.querySelectorAll('.cn-server')) {
@@ -486,6 +600,7 @@
btn.tabIndex = on ? 0 : -1;
}
applyServer(server);
+ updateCloud(server);
if (updateUrl) writeQuery();
}
diff --git a/public/locales/en.json b/public/locales/en.json
index 351a2597f..1a0f7e15e 100644
--- a/public/locales/en.json
+++ b/public/locales/en.json
@@ -3415,6 +3415,7 @@
"add_three_ws_to_claude_chatgpt_cursor": "Add three.ws to Claude, ChatGPT, Cursor, VS Code or Claude Code and your assistant can generate 3D models and avatars, run your agents, read their wallets and pay for services over x402. Sign in once in your browser: there is no API key to copy. Every tool is listed in the <a href=\"/mcp-tools\">MCP tool catalog</a>.",
"add_to_cursor": "Add to Cursor",
"add_to_vs_code": "Add to VS Code",
+ "any_client": "Any client",
"any_client_that_speaks_streamable_http_mcp": "Any client that speaks <strong>Streamable HTTP</strong> MCP can connect. Clients with OAuth support sign you in automatically from the server's <code>WWW-Authenticate</code> header. Clients without it can send an API key from <a href=\"/dashboard/api\">Dashboard → API</a> as <code>Authorization: Bearer</code>.",
"back_in_apps_connectors_click_create_name": "Back in <strong>Apps &amp; Connectors</strong>, click <strong>Create</strong>. Name it <code class=\"cn-name\">three.ws</code>, paste the URL, choose <strong>OAuth</strong>, and create it.",
"browse_every_tool": "Browse every tool",
@@ -3424,8 +3425,10 @@
"claude_code": "Claude Code",
"click_connect_and_sign_in_to_three": "Click <strong>Connect</strong> and sign in to three.ws. Read the permissions before you approve.",
"click_the_button_above_check_the_name": "Click the button above, check the name and URL, then click <strong>Add</strong>. Adding it by hand instead: <strong>Customize → Connectors</strong> (Settings → Connectors on some accounts), <strong>Add custom connector</strong>, paste the URL.",
+ "cloud_agents_share_one_ip": "Grok Bot and other hosted agents reach three.ws from one shared IP, so every user of that agent shares one free quota. A free <strong>install token</strong> gives your connector a quota of its own. No account, no key.",
"command_line_setup": "Command-line setup",
"connector": "Connector",
+ "connector_url_for_cloud_agents": "Connector URL for cloud agents",
"copy": "Copy",
"copy_2": "Copy",
"copy_3": "Copy",
@@ -3438,6 +3441,7 @@
"every_hosted_server_with_its_auth_and": "Every hosted server, with its auth and resources, is listed machine-readably at <a href=\"/.well-known/mcp.json\">/.well-known/mcp.json</a>.",
"every_tool_is_labelled": "Every tool is labelled",
"for_github_copilot_agent_mode_in_vs": "For GitHub Copilot agent mode in VS Code. The button opens VS Code's install prompt; the server signs you in on first use.",
+ "grok_bot": "Grok Bot",
"in_a_chat_open_the_menu_then": "In a chat, open the <kbd>+</kbd> menu, then <strong>Connectors</strong>, and switch three.ws on for that conversation.",
"in_a_new_chat_open_the_menu": "In a new chat, open the <kbd>+</kbd> menu, choose <strong>Developer mode</strong>, and tick three.ws.",
"in_claude_code_type_pick_the_server": "In Claude Code, type <code>/mcp</code>, pick the server you just added and choose <strong>Authenticate</strong>.",
diff --git a/scripts/probe-mcp-install-tokens.mjs b/scripts/probe-mcp-install-tokens.mjs
new file mode 100644
index 000000000..d0898d09b
--- /dev/null
+++ b/scripts/probe-mcp-install-tokens.mjs
@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// Probe free-studio install tokens end to end against a running server.
+//
+// node scripts/probe-mcp-install-tokens.mjs --base http://localhost:3107 --catalog https://three.ws
+// node scripts/probe-mcp-install-tokens.mjs --base https://three.ws
+//
+// Mints two install tokens from this machine's IP (POST /api/mcp-studio/install),
+// spends token A's per-minute generation burst with real look_at_model renders of
+// a catalog GLB, shows token A refused with the JSON-RPC denial, then shows token
+// B, same IP, still admitted. Spends 5 generation-quota units and 2 of this IP's
+// 10 hourly mints. Exits non-zero when the server does not behave that way.
+
+const args = process.argv.slice(2);
+const flag = (name, fallback) => {
+ const i = args.indexOf(`--${name}`);
+ return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+};
+const BASE = flag('base', 'http://localhost:3107').replace(/\/+$/, '');
+const SURFACE = flag('surface', '/api/mcp-studio');
+
+let rpcId = 0;
+async function rpc(url, method, params) {
+ const res = await fetch(url, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
+ body: JSON.stringify({ jsonrpc: '2.0', id: ++rpcId, method, params }),
+ });
+ const text = await res.text();
+ let body;
+ try {
+ body = JSON.parse(text);
+ } catch {
+ throw new Error(`${method} at ${url}: HTTP ${res.status}, non-JSON body: ${text.slice(0, 200)}`);
+ }
+ return { status: res.status, retryAfter: res.headers.get('retry-after'), body };
+}
+
+async function mint() {
+ const res = await fetch(`${BASE}/api/mcp-studio/install`, { method: 'POST', headers: { accept: 'application/json' } });
+ const body = await res.json();
+ if (res.status !== 201) throw new Error(`mint: HTTP ${res.status} ${JSON.stringify(body)}`);
+ return body;
+}
+
+// The GLB to render: --glb, else the first chair in the catalog at --catalog
+// (a local dev server ships an empty catalog, so point it at https://three.ws).
+async function catalogGlb() {
+ if (flag('glb')) return flag('glb');
+ const catalog = flag('catalog', BASE).replace(/\/+$/, '');
+ const r = await rpc(`${catalog}/api/mcp-studio`, 'tools/call', { name: 'search_catalog', arguments: { q: 'chair', limit: 1 } });
+ const item = r.body?.result?.structuredContent?.items?.[0];
+ const glb = item?.format === 'glb' ? item.url : null;
+ if (!glb) throw new Error(`search_catalog at ${catalog} returned no GLB; pass --glb <https url>`);
+ return glb;
+}
+
+function outcome(r) {
+ if (r.body?.error) return `REFUSED ${r.body.error.code} ${r.body.error.data?.limit} keyed_on=${r.body.error.data?.keyed_on}`;
+ const res = r.body?.result;
+ return `ADMITTED ${res?.isError ? 'tool error: ' + (res.content?.[0]?.text || '').slice(0, 80) : 'ok, ' + (res?.structuredContent?.views?.length ?? 0) + ' frames rendered'}`;
+}
+
+const look = (token, glb) =>
+ rpc(`${BASE}${SURFACE}?install=${encodeURIComponent(token)}`, 'tools/call', {
+ name: 'look_at_model',
+ arguments: { glb_url: glb, views: ['front'], size: 256 },
+ });
+
+const glb = await catalogGlb();
+const a = await mint();
+const b = await mint();
+console.log(`base ${BASE}${SURFACE}`);
+console.log(`minted token A ${a.token.slice(0, 16)}... and token B ${b.token.slice(0, 16)}... from the same IP`);
+console.log(`connector URL A: ${a.connector_url.replace(a.token, a.token.slice(0, 16) + '...')}`);
+console.log(`GLB: ${glb}`);
+
+let failed = false;
+for (let i = 1; i <= 5; i++) {
+ const r = await look(a.token, glb);
+ console.log(`token A call ${i}: ${outcome(r)}`);
+ if (i <= 4 && r.body?.error) failed = true;
+ if (i === 5) {
+ if (!r.body?.error) failed = true;
+ else {
+ console.log(` denial message: ${r.body.error.message}`);
+ console.log(` denial data: ${JSON.stringify(r.body.error.data)}`);
+ console.log(` HTTP ${r.status}, retry-after ${r.retryAfter}`);
+ }
+ }
+}
+const rb = await look(b.token, glb);
+console.log(`token B call 1: ${outcome(rb)}`);
+if (rb.body?.error) failed = true;
+
+console.log(failed ? 'FAIL: token budgets are not independent' : 'PASS: token A capped, token B from the same IP still admitted');
+process.exit(failed ? 1 : 0);