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.

docs(grok-bot): add the Grok Bot connector reference with runnable samples and a fix for every probe failure

nirholasae20babcd917
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 8eb7d7f57..df287c8c7 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -231,6 +231,7 @@ bottom.
| Escrowed knocks (pay-per-reply) | [contracts/knock-escrow/](contracts/knock-escrow) | In-repo | Anchor program making a knock's payment conditional instead of final: `knock` parks the price in a vault owned by the knock's own PDA, and only three things can happen to it. `answer` pays the owner minus a fee capped at 10% in the program itself, `refuse` refunds the sender in full and takes no fee, and `reclaim` refunds the sender once the reply window closes and can be called by anyone. Each `KnockRecord` snapshots the fee that was in force when it was made, so an authority cannot reprice money already in escrow, and it stores only the SHA-256 of the message and the reply, never their text. The trust-me version of this settles straight to the owner at [api/knock/](api/knock) (row above); this is the version that works between strangers. Both sides are reachable from a browser: senders escrow and crank their own refund from the door page, owners open their on-chain door, answer for payment or refuse for a refund from [/knock](pages/knock.html), all signed by their own wallet ([src/knock/escrow-checkout.js](src/knock/escrow-checkout.js)). Docs: [contracts/knock-escrow/README.md](contracts/knock-escrow/README.md), [docs/knock.md](docs/knock.md). Tests: [tests/knock-escrow-program.test.js](tests/knock-escrow-program.test.js), [tests/knock-escrow-pda.test.js](tests/knock-escrow-pda.test.js), [tests/api-knock-escrowed.test.js](tests/api-knock-escrowed.test.js), [tests/api-knock-escrow-sync.test.js](tests/api-knock-escrow-sync.test.js) |
| Cross-chain SDKs | [sdk/](sdk), [solana-agent-sdk/](solana-agent-sdk), [agent-payments-sdk/](agent-payments-sdk), [agent-protocol-sdk/](agent-protocol-sdk) | Published | Cross-chain agent SDKs |
| MCP integration | [mcp-server/](mcp-server), [mcp-bridge/](mcp-bridge), [packages/*-mcp/](packages) | 43 npm servers + 8 hosted remote (51 total, incl. the free `/api/mcp-studio` 3D Studio, whose ChatGPT plugin surface [api/mcp-chatgpt.js](api/mcp-chatgpt.js) `→ /api/mcp-chatgpt` serves the eight 3D tools and the model viewer without the persona tools or any `frameDomains`, and whose Grok surface [api/mcp-grok.js](api/mcp-grok.js) `→ /api/mcp-grok` serves every studio tool with no widget templates plus, for a caller signed in with OAuth 2.1 or a connector key, the account's agent tools from the core server ([api/_mcp-studio/account-tools.js](api/_mcp-studio/account-tools.js), never a value-moving tool; docs [docs/grok.md](docs/grok.md), test [tests/mcp-grok-accounts.test.js](tests/mcp-grok-accounts.test.js)); all three doors share [api/_mcp-studio/handler.js](api/_mcp-studio/handler.js), and `SURFACES` in [api/_mcp-studio/dispatch.js](api/_mcp-studio/dispatch.js) defines what each advertises), all in the [MCP registry](https://registry.modelcontextprotocol.io/?q=io.github.nirholas). Canonical metadata: [prompts/store-submissions/_generated/mcp-listing-source.json](prompts/store-submissions/_generated/mcp-listing-source.json), generated from the manifests by [scripts/build-mcp-listing-source.mjs](scripts/build-mcp-listing-source.mjs) (`npm run audit:mcp-listing` fails when it drifts) | Model Context Protocol surface, full server list in [docs/mcp.md](docs/mcp.md). One-click client setup: [pages/connect.html](pages/connect.html) `→ /connect` (Claude, Cursor and VS Code install links plus ChatGPT, Grok Bot, Claude Code and generic steps; the Grok Bot tab is the shared connector card [src/grok-connector.js](src/grok-connector.js), also mounted on the Grok landing page [pages/grok.html](pages/grok.html) `→ /grok` ([src/grok-page.js](src/grok-page.js): capabilities, a live strip of recent gallery creations, an in-page MCP demo against `/api/mcp-grok`, three scheduled recipes, the skill file); /connect is built live from [public/.well-known/mcp.json](public/.well-known/mcp.json) with tool counts from the catalog; config names match the CLI's `slugForPath`). CLI: [packages/three-ws-cli/](packages/three-ws-cli) (`npx three-ws setup`), docs [docs/cli.md](docs/cli.md) `→ /docs/cli`. Searchable index of every tool: [pages/mcp-tools.html](pages/mcp-tools.html) `→ /mcp-tools`, rendered from the generated [public/mcp-catalog.json](public/mcp-catalog.json) ([scripts/build-mcp-catalog.mjs](scripts/build-mcp-catalog.mjs), `npm run build:mcp-catalog`, staleness gated by `npm run audit:mcp-catalog`). Tool safety annotations are verified against each handler by [scripts/audit-mcp-safety.mjs](scripts/audit-mcp-safety.mjs) (`npm run audit:mcp-safety`, rules in [scripts/lib/mcp-safety-check.mjs](scripts/lib/mcp-safety-check.mjs), guarded-file list shared with the golden snapshot via [scripts/lib/mcp-tool-sources.mjs](scripts/lib/mcp-tool-sources.mjs)); docs [docs/mcp-safety.md](docs/mcp-safety.md) `→ /docs/mcp-safety`. Trust policy: [api/mcp-policy.js](api/mcp-policy.js) `-> GET /api/mcp-policy` turns those verified labels into a ready-to-paste client allowlist (profiles strict/balanced/open x formats claude/vscode/json), surfaced by the builder panel on `/mcp-tools`. Connector-review readiness (every paid stdio tool answers a clean x402 challenge, and the reviewer entitlement lifts it): [scripts/audit-mcp-reviewer-path.mjs](scripts/audit-mcp-reviewer-path.mjs), `npm run audit:mcp-reviewer`. Tests: [tests/mcp-safety-audit.test.js](tests/mcp-safety-audit.test.js), [tests/mcp-catalog.test.js](tests/mcp-catalog.test.js), [tests/api/mcp-policy.test.js](tests/api/mcp-policy.test.js) |
+| Grok Bot integration (custom MCP connector) | Connector [api/mcp-grok.js](api/mcp-grok.js) `→ /api/mcp-grok` over [api/_mcp-studio/handler.js](api/_mcp-studio/handler.js) (signed-in account tools [api/_mcp-studio/account-tools.js](api/_mcp-studio/account-tools.js), job tools [api/_mcp-studio/job-tools.js](api/_mcp-studio/job-tools.js)), install tokens [api/mcp-studio/install.js](api/mcp-studio/install.js) `→ /api/mcp-studio/install`, guided prompts [api/_mcp/prompts.js](api/_mcp/prompts.js), landing [pages/grok.html](pages/grok.html) `→ /grok`, connector card [src/grok-connector.js](src/grok-connector.js) (also on `/connect`), skill file [data/grok-skill-md.template.md](data/grok-skill-md.template.md) `→ /grok-skill.md`, connector probe [scripts/mcp-client-probe.mjs](scripts/mcp-client-probe.mjs) (`npm run probe:mcp-clients`) | In-repo (live with the next deploy) | Grok Bot adds `https://three.ws/api/mcp-grok` as a custom MCP connector: the free studio anonymously, plus the account's agent tools with a connector key or OAuth 2.1 (`?auth=oauth`), never a value-moving tool. Developer reference [docs/grok-bot.md](docs/grok-bot.md) (setup per auth mode, server choice, links contract, jobs and idempotency, limits, spend rule, prompts, probe troubleshooting; samples run by [scripts/run-doc-samples.mjs](scripts/run-doc-samples.mjs), drift test [tests/grok-bot-doc.test.js](tests/grok-bot-doc.test.js)); overview [docs/grok.md](docs/grok.md) |
| Awesome 3D Agents (curated list) | Source [data/awesome.json](data/awesome.json), generator [scripts/build-awesome.mjs](scripts/build-awesome.mjs) (`npm run build:awesome`, drift-gated by `npm run check:awesome`, publishable mirror via `npm run awesome:standalone`), outputs [awesome/README.md](awesome/README.md) + [public/awesome.json](public/awesome.json), page [pages/awesome.html](pages/awesome.html) `-> /awesome`, link checker [scripts/check-awesome-links.mjs](scripts/check-awesome-links.mjs) (`npm run awesome:links`) | Live | An awesome-list of everything needed to give an AI agent a body: text-to-3D, capture and splatting, avatars, rigging, motion, lipsync and voice, web renderers, asset pipelines, physics and networking, agent frameworks, datasets, free assets, learning. One JSON source produces both the GitHub-facing list and the searchable page, so they cannot disagree. Every url is fetched and classified (ok / moved / bot-filtered / broken) before it ships; the checker stays out of the deploy path so a third-party outage cannot redden someone else's build. The README is written to pass `npx awesome-lint`: badge on the heading line, no License section, no Contributing entry in the contents, and every description capitalised and ended with a period, all enforced by the generator and by [tests/awesome-list.test.js](tests/awesome-list.test.js). Its last two lint rules read GitHub repository topics, which a list inside a product repo cannot satisfy, so `--standalone` emits a ready-to-publish mirror repo (readme, contributing, code of conduct, license) outside this checkout. Contributing: [awesome/CONTRIBUTING.md](awesome/CONTRIBUTING.md) |
| Agent Skills pack | [.agents/skills/](.agents/skills) (canonical) → manifest [.agents/skills/SKILLS.md](.agents/skills/SKILLS.md), [.agents/skills/skills-pack.json](.agents/skills/skills-pack.json); published 3D subset [public/skills/3d-studio/](public/skills/3d-studio) `→ /skills/3d-studio/` | In-repo; bundled in the `three-ws-core` [plugin](.claude-plugin/marketplace.json); 3D subset live on the site | Portable `SKILL.md` folders (Agent Skills open standard) for any Claude surface, in five categories: 3d/creative (cross-platform-safe), platform/agents (create an agent, author and sell its skills, hire other agents, connect a client to the MCP servers), wallet/payments, intel/trading, ops/production. Counts live in the generated manifest, never here. The 3d/creative ones are also published as a public, downloadable bundle at `/skills/3d-studio/` (`three-ws-3d-skills.zip`), which is what an OpenAI Plugin Directory submission uploads on its Skills tab; a skill referencing a tool [api/_mcp-studio/](api/_mcp-studio) does not declare is dropped rather than shipped as a dead path. The same build renders the two entry-point skills from shared facts ([scripts/lib/skill-md-facts.mjs](scripts/lib/skill-md-facts.mjs)): [public/skill.md](public/skill.md) `→ /skill.md` from [data/skill-md.template.md](data/skill-md.template.md), and the Grok variant [public/grok-skill.md](public/grok-skill.md) `→ /grok-skill.md` from [data/grok-skill-md.template.md](data/grok-skill-md.template.md) (links and example calls checked by [tests/grok-skill-file.test.js](tests/grok-skill-file.test.js)). Regenerate manifest: `npm run build:skills-pack` (drift gate `npm run check:skills-pack`); regenerate the published bundle: `npm run build:openai-skills` (drift gate `npm run check:openai-skills`, wired into `npm run gate`). Docs: [docs/agent-skills.md](docs/agent-skills.md) |
| Standalone skill repos | [scripts/build-standalone-skill-repos.mjs](scripts/build-standalone-skill-repos.mjs) → `.data/standalone-repos/<repo>/` (gitignored) | Generated on demand; publishing is owner-gated | Assembles the three.ws-origin skills into small, publishable repos so an external user installs with one `/plugin marketplace add nirholas/<repo>` instead of cloning this monorepo: `three-ws-skills` (everything), `three-ws-3d-skills` (the crypto-free 3d/creative subset), `three-ws-agent-economy-skills` (wallet/payments + platform/agents). Each output is a complete one-plugin marketplace (`.claude-plugin/{marketplace,plugin}.json`, `skills/`, generated `README.md` with every trigger, `LICENSE`). Built from the same `collectSkills()` the manifest uses, so a copy cannot drift; nothing is committed here. `npm run build:skill-repos`, validate with `npm run check:skill-repos` (wired into `npm run gate`). Docs: [docs/agent-skills.md](docs/agent-skills.md) |
diff --git a/data/pages.json b/data/pages.json
index c1cade065..2f14b9ab4 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -4022,6 +4022,14 @@
"changefreq": "monthly",
"added": "2026-10-08"
},
+ {
+ "path": "/docs/grok-bot",
+ "title": "Docs · Grok Bot connector reference",
+ "description": "Connect Grok Bot to three.ws as a custom MCP connector: exact fields for each sign-in mode, which server to pick, the links every result carries, jobs and safe retries, free limits and install tokens, why a connector key can never spend, guided prompts, and a fix for every connection failure.",
+ "priority": 0.6,
+ "changefreq": "monthly",
+ "added": "2026-10-09"
+ },
{
"path": "/docs/mcp-solana-memo-media",
"title": "Docs · Solana Memo Media MCP",
diff --git a/docs/grok-bot.md b/docs/grok-bot.md
new file mode 100644
index 000000000..ba6f87b63
--- /dev/null
+++ b/docs/grok-bot.md
@@ -0,0 +1,542 @@
+# Grok Bot connector reference
+
+Grok Bot, xAI's always-on computer-use agent, takes custom MCP servers as
+connectors. This page is the developer reference for connecting it to three.ws:
+the exact connector settings for each authentication mode, which hosted server
+to pick, the contract every tool result follows, how long jobs and retries
+behave, the limits, what a key held by a cloud agent can and cannot do, the
+guided prompts, and a fix for every failure a connector can hit.
+
+For the product overview (what Grok gets, example asks, the xAI Responses API
+and the skill file), read [three.ws for Grok](./grok.md). For the live page and
+an in-browser demo, open [three.ws/grok](/grok).
+
+| | |
+|---|---|
+| **Server URL** | `https://three.ws/api/mcp-grok` |
+| **Transport** | Streamable HTTP (JSON-RPC over `POST`; `GET` answers `405` with `Allow: POST, OPTIONS`) |
+| **Authentication** | None, an API key (connector key), or OAuth 2.1 at `https://three.ws/api/mcp-grok?auth=oauth` |
+| **Protocol** | MCP `2025-06-18`, whatever version the client opens with |
+| **Session** | `initialize` issues an `Mcp-Session-Id` (`grk_…`); echo it on every later request |
+| **Tools** | 15 free studio tools anonymously; signed in, plus the account tools your scopes allow |
+| **Prompts** | 4 anonymously, 5 signed in |
+| **Handler** | [`api/mcp-grok.js`](../api/mcp-grok.js) over [`api/_mcp-studio/handler.js`](../api/_mcp-studio/handler.js) |
+
+## Connector setup
+
+Grok Bot connects from xAI's cloud, so the URL must be public: a `localhost`
+server never works. Add the server either by telling Grok Bot in chat
+("Add a custom MCP server called three-ws-grok at https://three.ws/api/mcp-grok")
+or through its connector form. The form takes four fields, and
+[three.ws/connect?client=grok](/connect?client=grok) shows them with a copy
+button for every hosted server. Use the name `three-ws-grok` so the guided
+prompts, the [skill file](https://three.ws/grok-skill.md) and the `/grok` page
+all refer to the connector by the same name.
+
+### None (free, no account)
+
+| Field | Value |
+|---|---|
+| Name | `three-ws-grok` |
+| Transport | Streamable HTTP |
+| Server URL | `https://three.ws/api/mcp-grok` |
+| Authentication | None |
+
+You get the free studio: text to 3D, image to 3D, rigging, refinement, the
+catalog of ready-made assets, and personas. The generation caps key on the MCP
+session, so they last one connection.
+
+### None, with an install token (free, a quota that survives reconnects)
+
+A scheduled Grok Bot task opens a new connection, and so a new session, on
+every run. To keep one budget across all of them, mint a free install token and
+put it in the URL. No account and no key:
+
+```bash
+curl -s -X POST https://three.ws/api/mcp-studio/install | jq -r .connector_urls.grok
+```
+
+```text
+https://three.ws/api/mcp-grok?install=tws_tmm6fp_dce3ce5583a6bd9f66889a1ef74e6a6e553ef39620867a6374fe75b9f6f039a1
+```
+
+| Field | Value |
+|---|---|
+| Server URL | the `connector_urls.grok` value above |
+| Authentication | None |
+
+The token never expires and unlocks no account, tool or payment; it is only a
+rate-limit identity, and request logs redact it. Anyone holding the URL spends
+its budget, so keep it in the connector rather than in a shared prompt. On
+[/connect](/connect?server=three-ws-studio), **Generate my connector URL** mints
+the same thing in the browser. Details:
+[install tokens](./mcp-studio.md#connector-url-for-cloud-agents-install-tokens).
+
+### API key (your agents, memory and skills)
+
+1. At [three.ws/dashboard/api](/dashboard/api) choose **New key**, then
+ **For an AI agent (Grok Bot, schedules, CI)**, name it, and copy the key it
+ shows once.
+2. Add the connector:
+
+| Field | Value |
+|---|---|
+| Server URL | `https://three.ws/api/mcp-grok` |
+| Authentication | API key |
+| Header (if asked) | `Authorization` |
+| Value | `Bearer sk_live_…`, stored as a Bot secret |
+
+Check the key before you hand it to Grok Bot. Signed in, `tools/list` grows from
+15 to the studio plus every account tool your scopes allow:
+
+```bash
+curl -s https://three.ws/api/mcp-grok \
+ -H "Authorization: Bearer $THREE_WS_API_KEY" \
+ -H 'Content-Type: application/json' \
+ -H 'Accept: application/json, text/event-stream' \
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools | length'
+```
+
+A connector key is capped on every request: it can read, generate and edit
+agent data and can never spend (see [Scoped keys and the spend rule](#scoped-keys-and-the-spend-rule)).
+
+### OAuth 2.1 (sign in once, revoke any time)
+
+| Field | Value |
+|---|---|
+| Server URL | `https://three.ws/api/mcp-grok?auth=oauth` |
+| Authentication | OAuth 2.1 |
+| Client ID | leave empty: the connector registers itself |
+
+The `?auth=oauth` form is what makes sign-in start. An MCP client only begins
+OAuth when the server answers `401`, and the plain URL serves anonymous callers,
+so it never would. With the parameter, an anonymous `initialize` answers:
+
+```bash
+curl -s -i 'https://three.ws/api/mcp-grok?auth=oauth' \
+ -H 'Content-Type: application/json' \
+ -H 'Accept: application/json, text/event-stream' \
+ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}' \
+ | grep -iE '^HTTP|^www-authenticate'
+```
+
+```text
+HTTP/1.1 401 Unauthorized
+www-authenticate: Bearer resource_metadata="https://three.ws/.well-known/oauth-protected-resource/api/mcp-grok", resource="https://three.ws/api/mcp-grok"
+```
+
+From there the client reads the protected-resource document, finds the
+authorization server, registers itself (RFC 7591 dynamic client registration),
+and sends you to a consent screen that names the app, the host of its
+`client_uri`, the host the code goes back to, and every permission in plain
+language. PKCE `S256` is required. Access tokens last an hour and refresh on
+their own; revoking the app in [Connected apps](/dashboard/settings#connected-apps)
+refuses its very next call. More:
+[Cloud connectors and revocation](./mcp.md#cloud-connectors-and-revocation).
+
+## Which server to pick
+
+Every hosted server speaks Streamable HTTP and is listed with its auth model in
+[`/.well-known/mcp.json`](https://three.ws/.well-known/mcp.json). For Grok Bot:
+
+| You want Grok Bot to | Connect | Auth |
+|---|---|---|
+| Make 3D models, avatars and personas, find ready-made assets | `https://three.ws/api/mcp-grok` | None (add an install token for scheduled tasks) |
+| Do that and also run your agents, memory, skills and avatars | `https://three.ws/api/mcp-grok` | Connector key, or OAuth 2.1 at `?auth=oauth` |
+| Use the full core server (validation, market data, a connected home) | `https://three.ws/api/mcp` | Connector key or OAuth 2.1 |
+| Use paid generation, retexture and optimization | `https://three.ws/api/mcp-3d` | Connector key or OAuth 2.1 |
+| Discover paid agent services | `https://three.ws/api/mcp-bazaar` | Connector key or OAuth 2.1 |
+
+`/api/mcp-grok` is the right default. It is the free studio with no ChatGPT
+widget templates (nothing renders inline in Grok, so every result hands back
+plain links instead), it never lets a call hang, and it keys the free quota on
+the MCP session rather than on xAI's shared egress IPs. The agent wallet server
+(`/api/mcp-agent`) is not a good fit for an unattended connector: a connector key
+there can browse and quote but every payment answers with a link back to
+three.ws, by design. x402 pay-per-call is not a connector mode at all, because
+each paid call needs a signed payment a connector cannot make for you.
+
+## Links in every result
+
+Grok Bot sees only JSON and text, so every result that carries a model also
+carries four absolute links under fixed names, both in `structuredContent` and
+as the first lines of the text content:
+
+| Field | What it is |
+|---|---|
+| `viewer_url` | The interactive 3D viewer, opens in any browser |
+| `glb_url` | The model file, to download, re-host, or pass to `rig_mesh` or `look_at_model` |
+| `poster_png_url` | A rendered 1024 px PNG (`/api/render/glb`, CDN-cached a day) to attach to a reply or a card |
+| `embed_html` | A paste-ready `<agent-3d>` or `<model-viewer>` snippet, script pinned with an integrity hash |
+
+The generators, `get_job` and `check_job` once done, `look_at_model`, the three
+catalog tools, and the three persona tools all carry them. A catalog search puts
+them on each item:
+
+```bash
+curl -s https://three.ws/api/mcp-grok \
+ -H 'Content-Type: application/json' \
+ -H 'Accept: application/json, text/event-stream' \
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_catalog","arguments":{"q":"chair","limit":1}}}' \
+ | jq '.result.structuredContent.items[0] | {id, viewer_url, glb_url, poster_png_url}'
+```
+
+```json
+{
+ "id": "object:ArmChair_01",
+ "viewer_url": "https://three.ws/viewer?src=https%3A%2F%2Fpub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev%2Fobjects%2Fpolyhaven%2Fglb%2FArmChair_01.glb&title=Arm%20Chair%2001",
+ "glb_url": "https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/objects/polyhaven/glb/ArmChair_01.glb",
+ "poster_png_url": "https://three.ws/api/render/glb?glbUrl=https%3A%2F%2Fpub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev%2Fobjects%2Fpolyhaven%2Fglb%2FArmChair_01.glb&width=1024&height=1024"
+}
+```
+
+A job that is still rendering has no GLB yet, so its result carries only a
+`viewer_url` of the form `https://three.ws/viewer?job=<job_id>`: that page waits
+for the job and opens the model the moment it lands, so Grok Bot can hand the
+link over straight away. Full field rules:
+[Links for agents that render no widget](./mcp-studio.md#links-for-agents-that-render-no-widget).
+
+## Jobs and idempotency
+
+Grok calls MCP from xAI's cloud with no published timeout, so on this URL no
+call runs longer than 40 seconds. A model usually lands inside that. When it
+does not (a GPU booting from zero, a heavy rig), the call answers with a pending
+job instead of hanging, and the server's instructions tell Grok to call
+`get_job` until it is done.
+
+Every generation tool (`forge_free`, `text_to_avatar`, `mesh_forge`, `rig_mesh`,
+`forge_avatar`, `refine_model`) takes an optional `idempotency_key`. A scheduled
+task should always pass one built from the task and the date, so a retry after a
+timeout collects the first run's job instead of generating twice:
+
+```bash
+RESULT=$(curl -s https://three.ws/api/mcp-grok \
+ -H 'Content-Type: application/json' \
+ -H 'Accept: application/json, text/event-stream' \
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"forge_free","arguments":{"prompt":"a brass ship lantern with a glass globe","idempotency_key":"lantern-brief-2026-10-09"}}}')
+echo "$RESULT" | jq '.result.structuredContent | {status, phase, job_id, progress, eta_seconds, idempotent_replay}'
+JOB=$(echo "$RESULT" | jq -r '.result.structuredContent.job_id')
+```
+
+```json
+{
+ "status": "pending",
+ "phase": "queued",
+ "job_id": "f1.eyJwIjoiZ2NwIiwiayI6bnVsbCwidCI6…",
+ "progress": 0.37,
+ "eta_seconds": 38,
+ "idempotent_replay": false
+}
+```
+
+Then collect it, as often as you like (`get_job` never starts a generation and
+never counts against the quota). Wait the `eta_seconds` it reported, then:
+
+```bash
+curl -s https://three.ws/api/mcp-grok \
+ -H 'Content-Type: application/json' \
+ -H 'Accept: application/json, text/event-stream' \
+ -d "$(jq -nc --arg job "$JOB" '{jsonrpc:"2.0",id:2,method:"tools/call",params:{name:"get_job",arguments:{job_id:$job}}}')" \
+ | jq '.result.structuredContent | {status, progress, eta_seconds, viewer_url, glb_url}'
+```
+
+```json
+{
+ "status": "done",
+ "progress": 1,
+ "eta_seconds": 0,
+ "viewer_url": "https://three.ws/viewer?src=https%3A%2F%2Fthree.ws%2Fcdn%2Fforge%2Fanon%2F45269fd0-ef73-4056-b288-0d6c5cfa8784.glb&title=a%20brass%20ship%20lantern%20with%20a%20glass%20globe",
+ "glb_url": "https://three.ws/cdn/forge/anon/45269fd0-ef73-4056-b288-0d6c5cfa8784.glb"
+}
+```
+
+What a job reports:
+
+| Field | Meaning |
+|---|---|
+| `status` | `pending`, `done` or `failed` (`unknown` when only the status check failed; retry after `retry_after`) |
+| `phase` | `submitting`, `queued`, `running`, `done` or `failed` |
+| `progress` | 0 to 1, an estimate while running, held at 0.95 until actually done |
+| `eta_seconds` | Seconds left, absent once a job runs past its estimate |
+| `reason`, `remedy` | On failure: `generation_failed`, `unknown_job` or `check_failed`, and the one action that fixes it |
+
+The key rules, in short:
+
+- **Same caller, same key, same arguments, within 24 hours:** the first call's
+ job comes back with `idempotent_replay: true`, and the repeat costs no quota.
+- **Same key, different arguments or a different tool:** refused with
+ `reason: "idempotency_key_reused"`; nothing starts. Use a new key for a new request.
+- **A call that never got a job** (a refused prompt, a rate limit) gives its key back.
+- **The caller owns the key.** It is whatever the rate limits key on (below), so
+ a task that reconnects keeps its keys only on an install-token URL or a
+ signed-in connector.
+
+A client that sends `_meta.progressToken` and accepts `text/event-stream` also
+gets `notifications/progress` while it waits. Everything else:
+[Job status](./mcp-studio.md#job-status-get_job),
+[Retries and `idempotency_key`](./mcp-studio.md#retries-and-idempotency_key),
+[Progress notifications](./mcp-studio.md#progress-notifications).
+
+## Rate limits and install tokens
+
+Every Grok user reaches three.ws from xAI's shared egress, so per-IP limits would
+ration all of Grok as one caller. The free caps therefore key on the most
+specific identity the request carries, in this order:
+
+1. the install token in the URL (`?install=`),
+2. the signed-in account (connector key or OAuth),
+3. the `Mcp-Session-Id` issued on `initialize`,
+4. the IP address, for a client that never echoes the session.
+
+| Limit | Value | Keyed on |
+|---|---|---|
+| Generation burst | 4 a minute | the caller above |
+| Generation hourly | 30 an hour | the caller above |
+| Per-IP pool | 300 generations an hour | the source IP, across every caller on it |
+| Transport | 300 requests a minute | the install token, else the IP |
+| Platform breaker | 600 generations an hour (`FORGE_PAID_GLOBAL_HOURLY`) | every free-studio caller combined |
+| Install token minting | 10 an hour | the IP |
+
+Generation means the six generators plus `look_at_model`, which renders the
+model on a GPU. `get_job`, `check_job`, the catalog and the persona tools ride
+the transport cap only. The numbers come from one table, `STUDIO_LIMITS` in
+[`api/_lib/rate-limit.js`](../api/_lib/rate-limit.js), and the refusal text is
+built from it, so the message always matches what is enforced.
+
+A capped generation answers HTTP 200 with a JSON-RPC error (the Python MCP SDK
+raises on a non-2xx before it reads the body), plus `Retry-After` and
+`RateLimit-*` headers. The message is written so Grok can relay it as is:
+
+```json
+{
+ "code": -32000,
+ "message": "Rate limited: the free 3D studio allows 30 generations per hour for this MCP session, and that limit is used up. It resets at 2026-10-09T14:25:00.000Z (in 1500 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-grok?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_hourly",
+ "max": 30,
+ "window": "1 h",
+ "keyed_on": "session",
+ "reset_at": "2026-10-09T14:25:00.000Z",
+ "retry_after": 1500,
+ "remedy": {
+ "kind": "install_token",
+ "install_endpoint": "https://three.ws/api/mcp-studio/install",
+ "connector_url": "https://three.ws/api/mcp-grok?install=<token>"
+ }
+ }
+}
+```
+
+A caller that already has its own budget (a token or an account), or that hit
+the per-IP pool or the platform breaker, gets `remedy.kind: "account"` instead:
+wait for `reset_at`, or use the signed-in server, whose generation is metered
+per account. The transport cap alone answers HTTP `429` with `reset_at` and the
+same `remedy` object.
+
+## Scoped keys and the spend rule
+
+A key that a cloud agent holds unattended can generate, read and write agent
+data. It can never move funds, pay an x402 endpoint, launch a coin, or change
+where earnings go. Spending stays a browser action on three.ws, behind its own
+confirmation.
+
+**The connector key.** **New key** then **For an AI agent** at
+[/dashboard/api](/dashboard/api) (or `POST /api/keys` with
+`{"name": "Grok Bot", "preset": "connector"}` from a signed-in browser session)
+issues these scopes:
+
+```text
+avatars:read avatars:write agents:read agents:write memory:read memory:write connector
+```
+
+The `connector` mark caps the key on every request, so no later edit to its
+stored scopes can give it `wallet:write`. The key table shows it with an
+"AI agent · cannot spend" badge.
+
+**On `/api/mcp-grok`, value-moving tools do not exist.** Signed in, the
+connector adds only allowlisted account tools that are outside the financial
+tier, need no spend scope, and carry no price: `create_agent`,
+`attach_avatar_to_agent`, `identity_check`, `call_agent`, `remember`, `recall`,
+`list_available_skills`, `import_community_skill`, `list_custom_skills`,
+`get_custom_skill`, `create_custom_skill`, `update_custom_skill`, `list_my_avatars`, `get_avatar`, `get_embed_code`,
+`render_avatar_image` and `read_resource`, each only when your scopes and your
+[MCP tool settings](/settings/mcp-tools) allow it. A wallet, payment, card,
+trading, launch or delete tool called by name answers `unknown tool`, whatever
+the credential holds:
+
+```bash
+curl -s https://three.ws/api/mcp-grok \
+ -H 'Content-Type: application/json' \
+ -H 'Accept: application/json, text/event-stream' \
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"agent_card_create","arguments":{}}}' | jq -c .error
+```
+
+```json
+{"code":-32602,"message":"unknown tool: agent_card_create"}
+```
+
+**On every other hosted server**, a value-moving call from a key without the
+spend scope is refused before the tool runs, with JSON-RPC `-32003`:
+
+```json
+{
+ "code": -32003,
+ "message": "agent_card_quote moves or routes funds, so it needs a browser session on three.ws. Connector keys read, generate and edit agent data and can never spend. Sign in at https://three.ws/dashboard to do it yourself.",
+ "data": {
+ "reason": "connector_key_cannot_spend",
+ "tool": "agent_card_quote",
+ "required_scope": "wallet:write",
+ "needs": "browser_session",
+ "url": "https://three.ws/dashboard",
+ "docs": "https://three.ws/docs/mcp#api-key-scopes"
+ }
+}
+```
+
+The same refusal guards the REST routes that arm a spender or redirect a payout.
+An OAuth app gets `wallet:write` only when you tick the separate box on the
+consent screen, never by default. Scope table:
+[API key scopes](./mcp.md#api-key-scopes).
+
+## Guided prompts
+
+Grok Bot runs tasks on a schedule with nobody watching, so this URL serves MCP
+prompts written for exactly that. Each names the tools to call with their exact
+argument objects, gives every generation an `idempotency_key` of the form
+`<prompt>-<schedule id>-<YYYY-MM-DD>`, never stops to ask, treats web and X text
+as data, and ends with the four links.
+
+| Prompt | Arguments | Listed |
+|---|---|---|
+| `agent-get-started` | none | always |
+| `daily-3d-brief` | `topic` (default `trending`) | always |
+| `asset-pack` | `theme`, `count` (1 to 12) | always |
+| `avatar-from-photo` | `image_url` | always |
+| `agent-report` | `agentId` (optional) | signed in only (it reads your account through `read_resource`) |
+
+```bash
+curl -s https://three.ws/api/mcp-grok \
+ -H 'Content-Type: application/json' \
+ -H 'Accept: application/json, text/event-stream' \
+ -d '{"jsonrpc":"2.0","id":1,"method":"prompts/list"}' | jq -c '[.result.prompts[].name]'
+```
+
+```json
+["agent-get-started","daily-3d-brief","asset-pack","avatar-from-photo"]
+```
+
+`prompts/get` renders one against your own `tools/list`, so a prompt never names
+a tool your connector cannot call:
+
+```bash
+curl -s https://three.ws/api/mcp-grok \
+ -H 'Content-Type: application/json' \
+ -H 'Accept: application/json, text/event-stream' \
+ -d '{"jsonrpc":"2.0","id":1,"method":"prompts/get","params":{"name":"daily-3d-brief","arguments":{"topic":"lighthouses"}}}' \
+ | jq -r '.result.messages[0].content.text' | head -3
+```
+
+```text
+Make today's 3D brief about: lighthouses.
+
+1. Use the topic above. If it names a real person, make an object that stands for the topic instead of a likeness.
+```
+
+In Grok Bot, a schedule such as "every morning, run the `daily-3d-brief` prompt
+from three-ws-grok and send me the links" is the whole setup.
+[three.ws/grok](/grok#gk-recipes-h) has three copy-ready recipes, and
+[MCP use cases](./mcp.md#use-cases) writes each prompt out as its calls. The
+prompts live in [`api/_mcp/prompts.js`](../api/_mcp/prompts.js).
+
+## Troubleshooting
+
+### Check the connector the way Grok Bot does
+
+From a clone of the repository, the connector probe connects with the official
+MCP SDK client over Streamable HTTP (falling back to the legacy SSE transport),
+anonymously, with `THREE_WS_API_KEY` when it is set, and against the OAuth
+challenge on the sign-in URL. It calls only free tools and never pays:
+
+```bash
+npm run probe:mcp-clients -- --only mcp-grok
+```
+
+```text
+PASS | https://three.ws/api/mcp-grok | init 200 | GET 405 | anon ok tools=15 prompts=4 | key ok tools=26 prompts=5 | oauth ok | call search_catalog=ok 228ms
+all 1 servers passed
+```
+
+Without `--only` it probes every server in
+[`/.well-known/mcp.json`](https://three.ws/.well-known/mcp.json); `--base` points
+it at your own server, and `--json <file>` keeps the full evidence. Each line it
+can print under a failing server, what it means, and the fix:
+
+| Probe says | What it means | Fix |
+|---|---|---|
+| `anonymous connect failed: …` | Neither transport finished `initialize` and `tools/list` without credentials. | Check the URL is exactly `https://three.ws/api/mcp-grok` (no trailing path), reachable from the public internet, and answering `POST`. The text after the colon is the SDK's own error. |
+| `anonymous tools/list returned no tools` | The handshake worked but the server listed nothing. | A deployment that lost its studio tool table; report it with the probe output. |
+| `initialize answered content-type …` | `initialize` came back as something other than JSON or an event stream, usually an HTML error page from a proxy. | Remove whatever sits between the client and three.ws, or point at the real origin. |
+| `GET answered 405 without an Allow header` | A `GET` was refused without saying which methods work, so some clients give up instead of switching to `POST`. | Server-side defect; three.ws always sends `Allow: POST, OPTIONS`. |
+| `GET answered 401 without WWW-Authenticate` | A protected `GET` gave the client nothing to sign in with. | Server-side defect; every 401 must carry the challenge. |
+| `GET with accept: text/event-stream answered …` | A `GET` returned neither a stream, a 405, nor a 401. | Usually a proxy or CDN rewriting the response; connect to the origin URL. |
+| `sign-in URL: unauthenticated initialize answered 200, an OAuth client needs 401 to start sign-in` | The OAuth connector was given the plain URL, which serves anonymous callers, so it never starts sign-in. | Use `https://three.ws/api/mcp-grok?auth=oauth` as the server URL for OAuth 2.1. |
+| `sign-in URL: 401 carries no Bearer WWW-Authenticate challenge` | The 401 does not tell the client how to authenticate. | Server-side defect in the challenge; report it. |
+| `sign-in URL: WWW-Authenticate does not name resource_metadata` | The client cannot find the protected-resource document, so it cannot find the authorization server. | Server-side defect; the challenge must name `resource_metadata`. |
+| `sign-in URL: protected-resource metadata at … answered …` | The protected-resource document is missing or not JSON. | It lives at `https://three.ws/.well-known/oauth-protected-resource/api/mcp-grok`; a 404 there means the route table lost its RFC 9728 rewrite. |
+| `sign-in URL: protected resource … does not cover …, so an MCP SDK client refuses to sign in` | The document names a different server than the one connected to; the MCP SDK's `checkResourceAllowed` then refuses to redirect anyone. | Server-side: each server must publish its own resource. This was the failure on four servers before the per-server metadata fix. |
+| `sign-in URL: WWW-Authenticate resource … disagrees with the metadata resource …` | The challenge and the document name different resources. | Server-side defect; both come from one resource map and must agree. |
+| `sign-in URL: protected-resource metadata lists no authorization_servers` | Nowhere to send the user to sign in. | Server-side defect in the document. |
+| `sign-in URL: authorization server metadata at … is incomplete` | `/.well-known/oauth-authorization-server` lacks an authorization or token endpoint. | Server-side defect; report it. |
+| `sign-in URL: authorization server does not advertise PKCE S256, which OAuth 2.1 requires` | A strict OAuth 2.1 client refuses an authorization server without `S256`. | Server-side defect; three.ws only accepts `S256`. |
+| `sign-in URL: an invalid bearer answered … without a resource_metadata challenge` | An expired or revoked token got an answer the client cannot recover from. | Server-side defect: a bad bearer must get `401` and the challenge so the connector signs in again, never anonymous service. |
+| `anonymous MCP client was served on a server that requires auth` | Seen when probing a protected server (`/api/mcp`, `/api/mcp-3d`, `/api/mcp-bazaar`): it answered a client with no credentials, so an OAuth connector would never be asked to sign in. | Server-side defect on that server; `/api/mcp-grok` is open by design and is judged on its `?auth=oauth` URL instead. |
+| `signing in with an API key listed N tools, no more than the M an anonymous client sees` | The key was accepted but added no account tools. | The key's scopes allow none of the account tools, or [MCP tool settings](/settings/mcp-tools) turn them all off. Make a connector key, or turn the tools on. |
+| `api key connect failed: …` | The key was refused, or the call errored. | The key is revoked, mistyped, or missing the `Bearer ` prefix. Make a new connector key and store `Bearer sk_live_…` as the secret. |
+| `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. |
+
+### Errors a connected Grok Bot can see
+
+| Error | Meaning | Fix |
+|---|---|---|
+| `-32000`, `data.reason: "rate_limited"` | A generation cap is used up. `data.limit` says which, `data.reset_at` when it lifts. | Follow `data.remedy`: reconnect with an install-token URL, or sign in. A scheduled task should wait until `reset_at` rather than retry in a loop. |
+| HTTP `429` with `reset_at` | More than 300 requests a minute from one IP or token. | Slow the polling loop; `get_job` after the `eta_seconds` it reports, never faster than every few seconds. |
+| `-32002`, `data.reason: "sign_in_required"` | An account tool was called on an anonymous connector. | Reconnect with a connector key, or OAuth at the `data.oauth_url` the error gives. |
+| `-32002`, `data.reason: "tool_not_granted"` | Signed in, but the key's scopes or your MCP tool settings leave that tool off. | Turn it on at [/settings/mcp-tools](/settings/mcp-tools), or use a key with the scope. |
+| `-32602`, `unknown tool: …` | The tool is not on this connector. On `/api/mcp-grok` every value-moving tool answers this way. | Spending happens at [three.ws/dashboard](/dashboard), not through a connector. Otherwise check the name against `tools/list`. |
+| `-32602`, `invalid params for …` | An argument is not in the tool's `inputSchema` (for example `query` where `search_catalog` takes `q`). | Read the schema from `tools/list`; the guided prompts already use the exact argument objects. |
+| `-32003`, `connector_key_cannot_spend` | A connector key tried a value-moving tool on another server. | By design. Do it yourself in a browser at the `data.url` the error gives. |
+| `idempotency_key_reused` | The key was already used for a different request. | Use a new key for a new generation (add the item or the date). |
+| `status: "failed"` with a `remedy` | The generation itself failed. | Do what `remedy` says: start a new generation with a new `idempotency_key`; the retry is routed to a healthy engine. |
+| `status: "unknown"`, `reason: "check_failed"` | Only the status check timed out; the job keeps running. | Call `get_job` again after `retry_after` seconds. |
+| `401` after working for a while | The OAuth app was revoked, or the key was revoked or rotated. | Reconnect: OAuth signs in again on its own; a key needs replacing in the Bot secret. |
+| Connector added, but account tools vanished | The bearer no longer verifies, so the server answers `401` with the challenge rather than quietly serving the free tier. | Same as above. |
+| "Cannot connect" from Grok Bot to a local server | Grok Bot connects from xAI's cloud. | Use the public `https://three.ws` URL; a `localhost` server is never reachable. |
+
+## Keeping this page true
+
+Every `bash` sample here runs as written, in order, in one shell: the job
+sample's `$JOB` feeds the `get_job` sample. To re-run them all against
+production, or against a server built from your tree:
+
+```text
+node scripts/run-doc-samples.mjs docs/grok-bot.md
+node scripts/run-doc-samples.mjs docs/grok-bot.md --base http://localhost:3108
+```
+
+Set `THREE_WS_API_KEY` to a connector key first, or the key sample counts
+anonymous tools. [`tests/grok-bot-doc.test.js`](../tests/grok-bot-doc.test.js)
+checks the rest against the code on every test run: each sample's tool and
+arguments against the served `inputSchema`, the account tools, the prompt table,
+the limit numbers against `STUDIO_LIMITS`, and that the troubleshooting table
+has a row for every failure the connector probe can print.
+
+## Related
+
+- [three.ws for Grok](./grok.md): the overview, the xAI Responses API, the skill file.
+- [three.ws/grok](/grok): the live page, demo and recipes; [three.ws/connect](/connect?client=grok): the connector card.
+- [The free 3D Studio MCP](./mcp-studio.md): every studio tool in depth.
+- [MCP integration](./mcp.md): every hosted server, authentication, client compatibility.
+- [MCP client analytics](./ops/mcp-clients.md): how three.ws counts which AI clients connect.
+- [`STRUCTURE.md`](../STRUCTURE.md): where the Grok surfaces live in the repository.
diff --git a/docs/grok.md b/docs/grok.md
index e31be4a38..21b2a828d 100644
--- a/docs/grok.md
+++ b/docs/grok.md
@@ -9,6 +9,8 @@ without ever being able to spend.
**Live page and demo:** [three.ws/grok](/grok)
+**Connector reference** (exact fields per sign-in mode, the result and job contracts, limits, troubleshooting): [Grok Bot connector reference](./grok-bot.md)
+
| | |
|---|---|
| **URL** | `https://three.ws/api/mcp-grok` |
diff --git a/docs/mcp.md b/docs/mcp.md
index ed3d93c3d..2a6df22b4 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -155,7 +155,7 @@ Ready-to-submit listing packages for each directory, plus the canonical metadata
Deep dives — every tool, argument, env var, and example:
-- **Hosted remote:** [3D Studio (free)](./mcp-studio.md) · [3D Studio (paid)](./mcp-3d-studio.md) · [Agent wallet](./mcp-agent.md) · [x402 Bazaar](./mcp-x402-bazaar.md) · [IBM x402](./ibm-x402-mcp.md)
+- **Hosted remote:** [3D Studio (free)](./mcp-studio.md) · [Grok Bot connector](./grok-bot.md) · [3D Studio (paid)](./mcp-3d-studio.md) · [Agent wallet](./mcp-agent.md) · [x402 Bazaar](./mcp-x402-bazaar.md) · [IBM x402](./ibm-x402-mcp.md)
- **Runs against your machine:** [Blender MCP](./blender-mcp.md) drives the Blender installed on your own computer, headless: inspect, convert, render and script 3D files, plus text-to-3D straight into a scene.
- **Install-and-run:** each npm server ships its usage guide (tools, arguments, env vars, examples) in its package README on [npmjs.com/org/three-ws](https://www.npmjs.com/org/three-ws). The [MCP Tools Catalog](./mcp-tools.md) maps every tool to its server and price.
- **Solana Memo Media:** [full guide](./mcp-solana-memo-media.md) for validating and rendering data URI images embedded in SPL Memo instructions.
@@ -295,6 +295,10 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
This uses the standalone npm package, which handles OAuth locally. The `--url` flag lets you point at a local dev server.
+### Grok Bot
+
+Grok Bot connects from xAI's cloud as a custom MCP connector: transport Streamable HTTP, server URL `https://three.ws/api/mcp-grok`, authentication None for the free studio, a connector key for your agents, or OAuth 2.1 at `https://three.ws/api/mcp-grok?auth=oauth`. The [Grok Bot connector reference](./grok-bot.md) has the exact fields for each mode, which server to pick, the result and job contracts, the limits, and a fix for every failure the connector probe reports.
+
### Any MCP-compatible client
Send `POST /api/mcp` with valid JSON-RPC 2.0 messages and a bearer token. The server is stateless, so no session setup is needed beyond the `initialize` handshake. `initialize` returns an `Mcp-Session-Id` header; echo it on later requests, as the MCP SDKs do, so your calls are attributed to your client in the platform's [client analytics](./ops/mcp-clients.md). It holds no state, and a request without it is served the same way.
@@ -346,7 +350,7 @@ What every hosted server does on the wire, so a connector never fails silently:
- `initialize` answers JSON (`application/json`) and negotiates protocol version `2025-06-18` whatever version the client opens with; every current MCP SDK accepts it.
- A `GET` with `accept: text/event-stream` answers a `405` with an `Allow` header where there is no server-to-client stream, a `401` with the OAuth challenge when the caller is unauthenticated, or the event stream itself (resource subscriptions on an authenticated core, 3D Studio, wallet or Bazaar connection, and the pump.fun feed).
-- These servers are stateless and issue no `Mcp-Session-Id`, so a connector has no session to echo, resume or tear down; every request stands alone.
+- `initialize` issues an `Mcp-Session-Id` (`grk_…` on `/api/mcp-grok`, `mcs_…` on the core, 3D, free studio, agent wallet, Bazaar and IBM servers) that a connector echoes on later requests. The servers hold no state on it: a request without it is served the same way. `/api/mcp-grok` also keys its free generation caps on it ([limits](./grok-bot.md#rate-limits-and-install-tokens)).
- An unauthenticated or expired-token request on a protected server gets `401` with `WWW-Authenticate: Bearer resource_metadata="…", resource="…"` naming that server, so the connector can sign in again on its own.
- On the free 3D Studio (`/api/mcp-studio` and `/api/mcp-grok`), a `tools/call` that carries `_meta.progressToken` from a client that accepts `text/event-stream` is answered as an event stream: `notifications/progress` while the job runs, then the result. Without a token it answers plain JSON.
diff --git a/docs/start-here.md b/docs/start-here.md
index fb978399b..af75cdd2c 100644
--- a/docs/start-here.md
+++ b/docs/start-here.md
@@ -92,6 +92,7 @@ Want the model in your hands rather than on a screen? [Materialize](./materializ
- **Placing agents in the real world?** → [IRL](./irl.md): pin an agent at a real GPS spot from your phone, and anyone who physically walks up can see it, talk to it, and pay it. Real crypto can be escrowed at places ([Money Drops](./irl.md#money-drops)) and agents sign proofs that you were really there ([World Lines](./irl.md#world-lines))
- **Making 3D models?** → [The free 3D Studio MCP](./mcp-studio.md) turns a prompt into a model, avatar, or rigged character — and lets you refine it by talking to it (*"make it metallic"*) with a revertable version history. Publish a model as remixable and earn on-chain royalties when others build on it: [the remix economy](./remix.md). Vote on the best community models and win the weekly board: [Forge-Off](./forge-off.md)
- **Using ChatGPT?** → [AR in ChatGPT](./chatgpt-ar.md) is how a sentence typed into ChatGPT becomes a 3D model standing in your room, from the free generation lane to the one-tap AR link; [your first prompt to 3D](/tutorials/first-prompt-to-3d) walks you through it in five minutes
+- **Using Grok Bot?** → [The Grok Bot connector reference](./grok-bot.md): add `https://three.ws/api/mcp-grok` as a custom MCP connector and Grok Bot can generate 3D models and rigged avatars, find ready-made assets, and run your agents on a schedule. It has the exact connector fields for each sign-in mode, which server to pick, how long jobs and safe retries work, the free limits, why a connector key can never spend, and a fix for every connection failure. The overview is [three.ws for Grok](./grok.md)
- **Making videos without showing your face?** → [Motion Swap](./motion-swap.md) — upload a video of yourself and get it back with your 3D avatar performing your exact motion instead of you; pose tracking and masking run server-side, compositing and export happen in your browser at [/motion-swap](https://three.ws/motion-swap)
- **Want a support chat with a face on your own site?** → [Concierge](./concierge.md) — a one-tag chat widget where a rigged 3D avatar lipsyncs streaming answers grounded in your live page, with voice in and out; [the build tutorial](./tutorials/build-a-site-concierge.md) shows how every part works
- **Want a full-body avatar assistant on your site instead?** → [Assistant widget](./assistant-widget.md) — a launcher button opens an animated 3D character standing directly on your page (or a color/gradient), with a free-lane or bring-your-own-key chatbot and a speak mode that says whatever you type, out loud, in a speech bubble
diff --git a/pages/grok.html b/pages/grok.html
index 7b934fb86..2b4710ed5 100644
--- a/pages/grok.html
+++ b/pages/grok.html
@@ -555,6 +555,7 @@ print(chat.sample().content)</pre>
</div>
<div class="gk-next">
<a class="gk-btn" href="/docs/grok">Read the Grok guide</a>
+ <a class="gk-btn" href="/docs/grok-bot">Connector reference</a>
<a class="gk-btn" href="/connect">Connect other AI clients</a>
<a class="gk-btn" href="/forge">Open the 3D studio</a>
</div>
diff --git a/public/locales/en.json b/public/locales/en.json
index 29f00261d..5d2e2df4f 100644
--- a/public/locales/en.json
+++ b/public/locales/en.json
@@ -3451,7 +3451,7 @@
"grok_key_alternative": "Running it unattended, on a schedule? A connector key from <a href=\"/dashboard/api\">Dashboard → API</a> (choose <strong>For an AI agent</strong>), stored as a Bot secret, works on this URL too and can never spend.",
"grok_localhost_never_works": "<strong>Use the public URL.</strong> Grok Bot connects from xAI's cloud, not from your computer, so a <code>localhost</code> or private-network URL never works. The three.ws URLs above are public.",
"grok_server_is_built_for_grok_bot": "The <strong>Grok</strong> server is built for Grok Bot: the free 3D studio with no sign-in, plus your own agents when you sign in, on one URL.",
- "grok_source": "Grok Bot is in beta and its connector screen still changes: if these steps drift, <a href=\"https://github.com/nirholas/three.ws/issues\" target=\"_blank\" rel=\"noopener\">tell us</a>. See what Grok Bot can do with it, live, at <a href=\"/grok\">three.ws/grok</a>, and read the full guide, with the xAI API and Grok connectors, at <a href=\"/docs/grok\">three.ws for Grok</a>.",
+ "grok_source": "Grok Bot is in beta and its connector screen still changes: if these steps drift, <a href=\"https://github.com/nirholas/three.ws/issues\" target=\"_blank\" rel=\"noopener\">tell us</a>. See what Grok Bot can do with it, live, at <a href=\"/grok\">three.ws/grok</a>, read the full guide, with the xAI API and Grok connectors, at <a href=\"/docs/grok\">three.ws for Grok</a>, and fix a connection that fails with the <a href=\"/docs/grok-bot#troubleshooting\">connector reference</a>.",
"grok_step_add_custom": "In Grok Bot, open <strong>Connectors</strong> and add a <strong>custom MCP</strong> server with the settings above. Asking in chat works too: say \"custom server\", or Grok Bot may look for a marketplace plugin instead.",
"grok_step_confirm": "Grok Bot shows the name and URL. Check both, then confirm.",
"grok_step_use": "Ask for 3D in any task, or attach the server with <code>@</code> and its name. Grok Bot runs on its own cloud computer, so it can save the GLB to its files or run the request on a schedule.",
diff --git a/scripts/run-doc-samples.mjs b/scripts/run-doc-samples.mjs
new file mode 100644
index 000000000..172b1e352
--- /dev/null
+++ b/scripts/run-doc-samples.mjs
@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// Run every ```bash block of one Markdown doc, in order, in a single shell
+// session (so a variable one sample sets is there for the next), and print each
+// sample beside its output, exit status and duration. This is how a doc's
+// "every sample runs against production as written" claim is checked.
+//
+// node scripts/run-doc-samples.mjs docs/grok-bot.md
+// node scripts/run-doc-samples.mjs docs/grok-bot.md --base http://localhost:3108 --skip 10
+//
+// --base swaps the `https://three.ws/api/` prefix for another origin, to run the
+// same samples against a local server built from this tree. --skip takes
+// 1-based sample numbers to leave out. The samples run exactly as written, so
+// only point this at a doc whose samples are safe to execute (free reads and
+// free generation); it never decides that for you. Exits non-zero when any
+// sample exits non-zero.
+
+import { readFileSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+function parseArgs(argv) {
+ const out = { file: null, base: null, skip: new Set() };
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i];
+ if (a === '--base') out.base = String(argv[++i] || '').replace(/\/+$/, '');
+ else if (a === '--skip') for (const n of String(argv[++i] || '').split(',')) out.skip.add(Number(n));
+ else if (!out.file) out.file = a;
+ else throw new Error(`unknown argument ${a}`);
+ }
+ if (!out.file) throw new Error('usage: node scripts/run-doc-samples.mjs <doc.md> [--base <origin>] [--skip 1,2]');
+ return out;
+}
+
+export function bashSamples(markdown) {
+ return [...markdown.matchAll(/```bash\n([\s\S]*?)```/g)].map((m) => m[1].trim());
+}
+
+// One script: each sample is echoed, run, and followed by a status line that
+// the summary counts. `set -o pipefail` makes a failing curl in a pipe count.
+export function sessionScript(samples, { base, skip }) {
+ const lines = ['set -o pipefail', 'FAILED=0'];
+ samples.forEach((src, i) => {
+ const n = i + 1;
+ const cmd = base ? src.replaceAll('https://three.ws/api/', `${base}/api/`) : src;
+ lines.push(`printf '\\n===== sample ${n} =====\\n'`, `cat <<'__SAMPLE_${n}__'`, src, `__SAMPLE_${n}__`);
+ if (skip.has(n)) {
+ lines.push(`echo '----- skipped'`);
+ return;
+ }
+ lines.push(
+ `echo '----- output'`,
+ 'T0=$(date +%s)',
+ cmd,
+ 'RC=$?',
+ `echo "----- exit $RC, $(( $(date +%s) - T0 )) s"`,
+ '[ "$RC" -ne 0 ] && FAILED=$((FAILED + 1))',
+ );
+ });
+ lines.push(`printf '\\n%s of ${samples.length} samples failed\\n' "$FAILED"`, 'exit $(( FAILED > 0 ))');
+ return lines.join('\n');
+}
+
+function main() {
+ const args = parseArgs(process.argv.slice(2));
+ const samples = bashSamples(readFileSync(args.file, 'utf8'));
+ if (!samples.length) throw new Error(`${args.file} has no bash samples`);
+ console.log(`${samples.length} samples in ${args.file}, against ${args.base || 'https://three.ws'}`);
+ const dir = mkdtempSync(path.join(tmpdir(), 'doc-samples-'));
+ const file = path.join(dir, 'samples.sh');
+ try {
+ writeFileSync(file, sessionScript(samples, args));
+ const r = spawnSync('bash', [file], { stdio: 'inherit', env: process.env });
+ process.exitCode = r.status ?? 1;
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+ try {
+ main();
+ } catch (err) {
+ console.error(err?.message || err);
+ process.exitCode = 1;
+ }
+}
diff --git a/src/grok-connector.js b/src/grok-connector.js
index 37873d43c..807c7a444 100644
--- a/src/grok-connector.js
+++ b/src/grok-connector.js
@@ -93,7 +93,7 @@ const TEMPLATE = `
<li data-i18n-html="connect.grok_step_use">Ask for 3D in any task, or attach the server with <code>@</code> and its name. Grok Bot runs on its own cloud computer, so it can save the GLB to its files or run the request on a schedule.</li>
</ol>
<p class="gc-callout" role="note" data-i18n-html="connect.grok_localhost_never_works"><strong>Use the public URL.</strong> Grok Bot connects from xAI's cloud, not from your computer, so a <code>localhost</code> or private-network URL never works. The three.ws URLs above are public.</p>
- <p class="gc-src" id="gc-source" data-i18n-html="connect.grok_source">Grok Bot is in beta and its connector screen still changes: if these steps drift, <a href="https://github.com/nirholas/three.ws/issues" target="_blank" rel="noopener">tell us</a>. See what Grok Bot can do with it, live, at <a href="/grok">three.ws/grok</a>, and read the full guide, with the xAI API and Grok connectors, at <a href="/docs/grok">three.ws for Grok</a>.</p>
+ <p class="gc-src" id="gc-source" data-i18n-html="connect.grok_source">Grok Bot is in beta and its connector screen still changes: if these steps drift, <a href="https://github.com/nirholas/three.ws/issues" target="_blank" rel="noopener">tell us</a>. See what Grok Bot can do with it, live, at <a href="/grok">three.ws/grok</a>, read the full guide, with the xAI API and Grok connectors, at <a href="/docs/grok">three.ws for Grok</a>, and fix a connection that fails with the <a href="/docs/grok-bot#troubleshooting">connector reference</a>.</p>
`;
async function copyFrom(btn, source) {
diff --git a/tests/grok-bot-doc.test.js b/tests/grok-bot-doc.test.js
new file mode 100644
index 000000000..e53e896d2
--- /dev/null
+++ b/tests/grok-bot-doc.test.js
@@ -0,0 +1,110 @@
+// docs/grok-bot.md is the reference a Grok Bot integrator copies from: tool
+// calls, prompt names, limit numbers and the troubleshooting table for the
+// connector probe. Each of those has a source of truth in code, and this test
+// fails when the doc and the code disagree, so a renamed tool, a retuned limit
+// or a new probe failure breaks the build instead of the integration.
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+
+process.env.PUBLIC_APP_ORIGIN ||= 'https://three.ws';
+
+const { toolCatalogFor } = await import('../api/_mcp-studio/dispatch.js');
+const { GROK_ACCOUNT_TOOLS } = await import('../api/_mcp-studio/account-tools.js');
+const { PROMPTS } = await import('../api/_mcp/prompts.js');
+const { STUDIO_LIMITS } = await import('../api/_lib/rate-limit.js');
+const { GROK_ENDPOINT, slugForEndpoint } = await import('../src/grok-connector.js');
+
+const ROOT = path.resolve(import.meta.dirname, '..');
+const doc = fs.readFileSync(path.join(ROOT, 'docs/grok-bot.md'), 'utf8');
+const bashBlocks = [...doc.matchAll(/```bash\n([\s\S]*?)```/g)].map((m) => m[1]);
+
+const STUDIO = new Map(toolCatalogFor('grok').map((t) => [t.name, t]));
+const SERVED = new Set([...STUDIO.keys(), ...GROK_ACCOUNT_TOOLS]);
+// The one sample that calls a tool on purpose to show it is not served.
+const REFUSED_SAMPLE = 'agent_card_create';
+
+// Every JSON-RPC body a sample sends with -d '...'.
+const sentBodies = bashBlocks.flatMap((src) => [...src.matchAll(/-d '(\{"jsonrpc"[^']*)'/g)].map((m) => JSON.parse(m[1])));
+
+describe('docs/grok-bot.md samples call what /api/mcp-grok serves', () => {
+ it('has runnable samples for every contract the doc covers', () => {
+ const methods = sentBodies.map((b) => (b.method === 'tools/call' ? b.params.name : b.method));
+ expect(methods).toEqual(expect.arrayContaining(['initialize', 'tools/list', 'prompts/list', 'prompts/get', 'search_catalog', 'forge_free']));
+ expect(bashBlocks.some((src) => src.includes('name:"get_job"'))).toBe(true);
+ expect(bashBlocks.some((src) => src.includes('/api/mcp-studio/install'))).toBe(true);
+ });
+
+ it('every tools/call names a served tool with arguments its inputSchema accepts', () => {
+ for (const body of sentBodies.filter((b) => b.method === 'tools/call')) {
+ const { name, arguments: args = {} } = body.params;
+ if (name === REFUSED_SAMPLE) continue;
+ const tool = STUDIO.get(name);
+ expect(tool, name).toBeTruthy();
+ const props = Object.keys(tool.inputSchema?.properties || {});
+ expect(Object.keys(args).filter((k) => !props.includes(k)), name).toEqual([]);
+ expect((tool.inputSchema?.required || []).filter((k) => !(k in args)), name).toEqual([]);
+ }
+ });
+
+ it('the refused-tool sample really is refused on this surface', () => {
+ expect(sentBodies.some((b) => b.params?.name === REFUSED_SAMPLE)).toBe(true);
+ expect(SERVED.has(REFUSED_SAMPLE)).toBe(false);
+ });
+
+ it('every generation sample carries an idempotency_key', () => {
+ for (const body of sentBodies.filter((b) => b.params?.name === 'forge_free')) {
+ expect(body.params.arguments.idempotency_key).toBeTruthy();
+ }
+ });
+});
+
+describe('docs/grok-bot.md matches the code it describes', () => {
+ it('lists exactly the account tools a signed-in connector can get', () => {
+ const section = doc.slice(doc.indexOf('**On `/api/mcp-grok`, value-moving tools do not exist.**'), doc.indexOf('**On every other hosted server**'));
+ const named = new Set([...section.matchAll(/`([a-z_]+)`/g)].map((m) => m[1]).filter((n) => n !== REFUSED_SAMPLE));
+ expect([...named].sort()).toEqual([...GROK_ACCOUNT_TOOLS].sort());
+ });
+
+ it('the prompts table is every agent prompt', () => {
+ const table = doc.slice(doc.indexOf('| Prompt | Arguments | Listed |'));
+ const rows = [...table.matchAll(/^\| `([a-z0-9-]+)` \|/gm)].map((m) => m[1]);
+ expect(rows.sort()).toEqual(PROMPTS.filter((p) => p.agent).map((p) => p.name).sort());
+ });
+
+ it('the limits table states the enforced numbers', () => {
+ const row = (label) => doc.match(new RegExp(`^\\| ${label} \\| ([0-9]+) `, 'm'))?.[1];
+ expect(Number(row('Generation burst'))).toBe(STUDIO_LIMITS.genBurst.limit);
+ expect(Number(row('Generation hourly'))).toBe(STUDIO_LIMITS.genHourly.limit);
+ expect(Number(row('Per-IP pool'))).toBe(STUDIO_LIMITS.genPoolHourly.limit);
+ expect(Number(row('Transport'))).toBe(STUDIO_LIMITS.transport.limit);
+ expect(Number(row('Platform breaker'))).toBe(STUDIO_LIMITS.genGlobal.limit);
+ expect(Number(row('Install token minting'))).toBe(STUDIO_LIMITS.installMint.limit);
+ });
+
+ it('uses the connector name the CLI and /connect use', () => {
+ const slug = slugForEndpoint(GROK_ENDPOINT);
+ expect(doc).toContain(`called ${slug} at ${GROK_ENDPOINT}`);
+ expect(doc).toContain(`| Name | \`${slug}\` |`);
+ });
+});
+
+describe('troubleshooting covers every failure the connector probe reports', () => {
+ // The static start of each message scripts/mcp-client-probe.mjs can print.
+ const probe = fs.readFileSync(path.join(ROOT, 'scripts/mcp-client-probe.mjs'), 'utf8');
+ const messages = [
+ ...probe.matchAll(/failures\.push\(\s*[`'](.*?)[`']\s*\)/g),
+ ...probe.matchAll(/return '([A-Z][^']+)';/g),
+ ...probe.matchAll(/: '(GET [^']+)'/g),
+ ...probe.matchAll(/return `(GET [^`]+)`/g),
+ ].map((m) => m[1].split('${')[0].replace(/\.trim\(\)$/, '').trim());
+
+ it('finds the probe messages', () => {
+ expect(messages.length).toBeGreaterThanOrEqual(22);
+ });
+
+ it('has a row for each one', () => {
+ const table = doc.slice(doc.indexOf('| Probe says |'), doc.indexOf('### Errors a connected Grok Bot can see'));
+ expect(messages.filter((m) => m && !table.includes(m))).toEqual([]);
+ });
+});