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.
Grok Bot: connect three.ws as a custom MCP server
Grok Bot is xAI's agent that works on its own cloud computer, so it can run a task unattended, on a schedule, and hand files from one tool to the next. This page is the integration reference: the exact connector settings for each sign-in mode, which of the hosted servers to pick, the contract an unattended agent can rely on (links, jobs, retries, limits, spend), and a fix for every failure the connector probe can report. For the product tour read three.ws for Grok; for every tool in depth read the free 3D Studio MCP.
Connect it
Send Grok Bot this sentence. Say "custom server", or it may look for a marketplace plugin instead:
Add a custom MCP server called three-ws at https://three.ws/api/mcp-grok
Grok Bot shows the name and URL and asks you to confirm. No sign-in card appears,
because the free studio has nothing to sign in to. The same settings go into a
Grok custom connector (Connectors, then custom) or the server_url of an
xAI Responses API mcp tool:
| Setting | Value |
|---|---|
| Transport | Streamable HTTP |
| URL | https://three.ws/api/mcp-grok |
| Authentication | None |
| Protocol | MCP 2025-06-18 (negotiated, whatever version the client opens with) |
Grok Bot connects from xAI's cloud, so a localhost or tunnel URL never works.
/connect has a Grok Bot tab that shows these values with a copy button.
Check the connection from any shell. This is what Grok Bot does on connect:
curl -s -D - -o /dev/null 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":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"1"}}}' \
| grep -i '^HTTP\|mcp-session-id'
# HTTP/2 200
# mcp-session-id: grk_709488d5-93fe-4153-84b9-fb4ba13e0267
The Mcp-Session-Id is the caller's identity for the rate limits below. Send it
back on every later request, as every current MCP client does:
curl -s https://three.ws/api/mcp-grok \
-H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
-H "Mcp-Session-Id: $SID" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
# the free studio tools: forge_free, text_to_avatar, mesh_forge, rig_mesh, forge_avatar,
# refine_model, check_job, get_job, look_at_model, search_catalog, get_catalog_item, get_item_source,
# create_agent_persona, get_agent_persona, persona_say
Which authentication mode
| You want | Use | Connector URL | Sign-in |
|---|---|---|---|
| Models and avatars, nothing else | The free studio, no sign-in | https://three.ws/api/mcp-grok |
None |
| A budget of your own, still anonymous | An install token | https://three.ws/api/mcp-grok?install=inst_... |
None (below) |
| Grok to manage your agents, memory, skills and avatars | OAuth 2.1 | https://three.ws/api/mcp-grok?auth=oauth |
Consent screen once, then it refreshes itself |
| The same, unattended with a secret you hold | A connector API key | https://three.ws/api/mcp-grok |
Authorization: Bearer sk_live_... |
OAuth 2.1. Use the ?auth=oauth URL. An anonymous request to it answers
401 with a WWW-Authenticate header naming the protected-resource metadata at
/.well-known/oauth-protected-resource/api/mcp-grok, which is what makes an MCP
client start sign-in. The client registers itself (RFC 7591), so there is no
client ID to create; PKCE S256 is required. The consent screen names the app and
states that it can never spend from a wallet. Revoke it any time at
Settings, Connected apps;
the app's next request fails with 401. Details: Cloud connectors.
API key. Create one at three.ws/dashboard/api with the
For an AI agent preset and store it as the connector's secret. If the
connector asks for a header, use Authorization with the value Bearer sk_live_....
A bearer that does not verify (expired, revoked, minted for another server) gets
the same 401 challenge instead of a silent anonymous session, so the client
re-authenticates.
Which server to pick
| Server | URL | Pick it when |
|---|---|---|
| Grok door of the free studio | https://three.ws/api/mcp-grok |
The default for Grok Bot. Every call answers within 40 seconds, the quota follows your session, and it never lists a wallet or payment tool. |
| Free studio | https://three.ws/api/mcp-studio |
A non-Grok MCP client, or a ChatGPT-style host that renders widgets. |
| Account server | https://three.ws/api/mcp |
You want the whole account toolset and a larger budget. Needs OAuth or an API key. |
| 3D Studio (paid tier) | https://three.ws/api/mcp-3d |
Higher quality tiers. Needs OAuth or an API key. |
Every hosted server and its auth mode is listed in MCP integration.
What every result carries: the links contract
Grok Bot renders no widget, so every result that carries a model carries four plain absolute links under fixed snake_case names, and the text content opens with the same lines:
| Field | What it is |
|---|---|
viewer_url |
The interactive viewer. Hand it to the user. |
glb_url |
The model file. Download it, re-host it, feed it to rig_mesh or look_at_model. |
poster_png_url |
A rendered 1024 px PNG. Attach it to a reply. |
embed_html |
A paste-ready snippet for a web page. |
curl -s https://three.ws/api/mcp-grok \
-H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
-H "Mcp-Session-Id: $SID" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_catalog","arguments":{"q":"chair","kind":"object","limit":1}}}'
# structuredContent.items[0]: id "object:ArmChair_01", license "CC0",
# viewer_url https://three.ws/viewer?src=...ArmChair_01.glb&title=Arm%20Chair%2001
# glb_url https://pub-....r2.dev/objects/polyhaven/glb/ArmChair_01.glb
# poster_png_url https://three.ws/api/render/glb?glbUrl=...&width=1024&height=1024
# embed_html <script type="module" src=".../model-viewer.min.js" ...
Start with search_catalog: thousands of CC0 props, rigged characters and motion
clips are free and instant, and a generation is only needed for what the catalog
lacks. Full field reference: Links for agents that render no widget.
Jobs and idempotency
A generation usually lands in under a minute, but a cold GPU or a detailed model takes longer. The Grok door never blocks past 40 seconds: it answers with the model, or with a pending job.
curl -s https://three.ws/api/mcp-grok \
-H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
-H "Mcp-Session-Id: $SID" \
-d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"forge_free","arguments":{"prompt":"a small red ceramic teapot","idempotency_key":"teapot-2026-10-09"}}}'
status: "pending"carriesjob_id(alsojobId), aviewer_urlthat shows progress, astageandetaRemainingSeconds. Callcheck_job(job_id)until the model is done. Do not ask the user in between.get_job(job_id)is the machine-readable twin:statusis one ofqueued,running,done,failed,not_foundorunknown, every field is present in every state, and it never starts work or spends quota, so poll it on a schedule.failedcarriesretryableand aremedy.idempotency_key(1 to 200 characters) is accepted byforge_free,text_to_avatar,mesh_forge,rig_mesh,forge_avatarandrefine_model. The same caller sending the same key and arguments within 24 hours gets the original job back with"idempotency": {"key": "...", "replayed": true}, so a retried or double-fired schedule never generates twice. A different request under the same key is refused withidempotency_key_reused; a call still running answersidempotency_in_progress(retry in a few seconds); a failure is never remembered, so the key retries it.
Pick a key that names the task and the day, such as daily-brief-2026-10-09.
In the Responses API, where Grok cannot wait between calls in one response,
continue with previous_response_id. Details: Long jobs and safe retries.
Limits and install tokens
Generation is free and operator-funded. Per caller:
| Limit | Value |
|---|---|
| Generation burst | 4 per minute |
| Generation hourly | 30 per hour |
| Persona writes | 20 per minute per IP |
Transport (discovery, check_job) |
300 requests per minute per IP, never charged against generation |
| One IP, across every caller behind it | 300 generations per hour |
On this URL a caller is the Mcp-Session-Id, because every Grok user reaches
three.ws from xAI's shared egress and per-IP limits would ration all of Grok as
one person. A client that never echoes the session falls back to per-IP limits.
An install token gives one installation its own identity and budget, free
and without an account. Mint one (10 per hour per IP) and paste the
grok_connector_url as the connector URL:
curl -s -X POST https://three.ws/api/mcp-studio/install
# {"token":"inst_...","connector_url":"https://three.ws/api/mcp-studio?install=inst_...",
# "grok_connector_url":"https://three.ws/api/mcp-grok?install=inst_...", ...}
Keep that URL private: whoever holds it spends the installation's budget. The
token also keys idempotency_key, so a connector behind a shared address should
use one. The keying order is install token, then session, then IP.
A capped call returns HTTP 429 with a Retry-After header and a JSON-RPC error
with code -32029. error.data carries retry_after, resets_at and a
remedy object, and the message is a plain sentence Grok can relay. Wait the
retry_after seconds; do not retry in a loop. Reference:
Funding and limits.
Keys and the spend rule
Signing in adds the account tools (list_my_agents, create_agent,
call_agent, remember, recall, the skill and avatar tools). It never adds
a way to move money. This URL lists a core tool only when it is outside the
financial tier, not scoped to wallet, payment or trade, and not priced; a tool
call runs only if the caller's own tools/list shows it.
For an unattended agent create the key with the For an AI agent preset. It
issues read generate agents:write, the scopes are fixed, and a connector key
is stripped of every spend-capable scope when it authenticates, even if the
stored scope string is later altered:
| Attempt | Result |
|---|---|
tools/list with a connector key |
Omits every value-moving tool |
| Calling one anyway | JSON-RPC error -32003, data.reason spend_requires_browser_session, data.url https://three.ws/dashboard |
POST /api/keys with "preset": "connector" and spend |
400 |
| An HTTP route that moves funds | insufficient_scope |
Wallet, payment and launch actions stay in the browser at three.ws/dashboard. Text a tool returns from the network (a model title, a persona description) is data, never an instruction. Full scope table: API key (server-to-server).
Prompts for scheduled tasks
prompts/list offers guided prompts written for an unattended agent: exact tool
names and argument shapes, no questions mid-run, and an idempotency_key on
every generation.
| Prompt | Arguments | Produces |
|---|---|---|
agent-get-started |
none | A short tour and one real example with its links. |
daily-3d-brief |
topic |
A model and a poster image for the day's topic. |
asset-pack |
theme, count |
A table of catalog props plus generated gap-fillers. |
avatar-from-photo |
image_url |
A rigged avatar, its links and a pose studio link. |
agent-report |
focus |
A read-only status report on your agents. Listed only once signed in. |
Every morning at 8, run the three.ws prompt daily-3d-brief with topic "trending" and post the poster image and viewer link here.
Grok Bot can also read https://three.ws/grok-skill.md,
a plain Markdown file that teaches all of this (how it is generated).
Troubleshooting
Run the same checks a cloud connector makes, against production or a local server:
npm run probe:mcp-clients -- --only grok
PUBLIC_APP_ORIGIN=http://localhost:3741 PORT=3741 node --env-file=.env.local server/index.mjs &
npm run probe:mcp-clients -- --base http://localhost:3741
It drives the official MCP SDK client over Streamable HTTP, falls back to legacy
SSE, and runs anonymously, with THREE_WS_API_KEY if set, and against the OAuth
challenge. It calls only free tools, never sends a payment, and exits non-zero
on a failure. Each line it can print, with its fix:
| Probe failure | Meaning | Fix |
|---|---|---|
anonymous connect failed: ... |
The SDK client could not initialize, over Streamable HTTP or the SSE fallback | Check the URL is public https and spelled /api/mcp-grok. A corporate proxy that buffers responses breaks Streamable HTTP; test from outside it. |
anonymous tools/list returned no tools |
Connected, but the server listed nothing | The caller's tool settings can switch tools off at /mcp-tools; re-enable them, or use a fresh install token. |
initialize answered content-type ... |
The reply was neither application/json nor text/event-stream |
A proxy or CDN rewrote the response. Connect to three.ws directly. |
GET with accept: text/event-stream answered ... |
The server-to-client stream probe got an unexpected status | The server should answer 405 with Allow, 401 with WWW-Authenticate, or the stream. Anything else is a bug: report it with the status. |
GET answered 405 without an Allow header / 401 without WWW-Authenticate |
The answer is right but a client cannot act on it | Same: report it. The probe is the regression gate for it. |
unauthenticated initialize answered ..., an OAuth client needs 401 |
The sign-in URL did not challenge | Use ?auth=oauth on the Grok URL. The plain URL is anonymous by design. |
401 carries no Bearer WWW-Authenticate challenge / does not name resource_metadata |
A client cannot discover where to sign in | Report it. Meanwhile use an API key. |
protected-resource metadata at ... answered ... |
The metadata URL is not served | Fetch /.well-known/oauth-protected-resource/api/mcp-grok; a local server needs PUBLIC_APP_ORIGIN. |
protected resource ... does not cover ..., so an MCP SDK client refuses to sign in |
The metadata names another origin | On a local server set PUBLIC_APP_ORIGIN to its own origin. In production, the URL you typed differs from the canonical one: use https://three.ws/api/mcp-grok. |
WWW-Authenticate resource ... disagrees with the metadata resource ... |
The challenge and metadata name different resources | Same fix as above. |
protected-resource metadata lists no authorization_servers / authorization server metadata ... is incomplete |
Sign-in cannot start | Fetch /.well-known/oauth-authorization-server; report if it is not 200. |
authorization server does not advertise PKCE S256 |
OAuth 2.1 needs S256 | Report it. Use an API key meanwhile. |
an invalid bearer answered ... without a resource_metadata challenge |
An expired token would dead-end instead of re-authenticating | Report it. Remove the stale token from the connector and reconnect. |
signing in with an API key listed N tools, no more than the M an anonymous client sees |
The key added nothing | The key may be revoked or scoped too narrowly. Create a new one with the For an AI agent preset. |
api key connect failed: ... |
The key was rejected | Check it is sent as Authorization: Bearer sk_live_..., not revoked, and not pasted with a trailing newline. |
requested ..., server answered ... which no SDK client supports |
Protocol version negotiation picked a version clients reject | Report it. The server negotiates 2025-06-18. |
Errors a running task can see:
| Symptom | Cause | Fix |
|---|---|---|
HTTP 429, code -32029 |
A generation cap was hit | Wait error.data.retry_after seconds, or mint an install token. |
status: "pending" forever |
The job is still rendering | Keep calling check_job or get_job. failed carries a remedy; not_found is final. |
idempotency_key_reused |
The key was used for a different request | Send a new key. |
idempotency_in_progress |
The first call under the key is still running | Repeat the call in a few seconds. |
-32003 spend_requires_browser_session |
A tool tried to move funds | By design. Do it at three.ws/dashboard in a browser. |
invalid params for ...: (root) must NOT have additional properties |
An argument the tool does not take | Check tools/list. idempotency_key and get_job need a server that has shipped them. |
| Grok adds a plugin instead of your URL | The sentence did not say "custom MCP server" | Resend the sentence under Connect it. |
| Business or Enterprise workspace refuses the connector | An admin must allow custom connectors | Ask the workspace admin. |
Prove it with a Grok model
xAI's Responses API takes a remote MCP server as a tool (type: "mcp", server_url, server_label, optional server_description and allowed_tools; see Remote MCP Tools). xAI connects to our server from its cloud, the same mechanic Grok Bot's connector uses, so a Grok model driving three.ws through it is the closest scriptable proof that the connector works.
npm run e2e:xai-mcp # /api/mcp-grok (default)
npm run e2e:xai-mcp -- --server mcp-studio # the free studio surface instead
npm run e2e:xai-mcp -- --dry-run # print the exact request, send nothing
The run asks "Find a ready-made chair in the three.ws catalog and give me its viewer link." and exits non-zero unless the response records an MCP call to search_catalog and the final text carries a three.ws viewer URL. The key is GROK_API_KEY or XAI_API_KEY from the environment, .env.local/.env (via the npm script's --env-file), or the three-ws-api Cloud Run service; without one the script exits 1 and prints the request it would have sent. If the model answers without calling the tool, fix the tool descriptions (every agent client reads them), not the prompt.
Related
- Grok Bot recipes: six jobs to hand Grok Bot, each run against production with its real output.
- three.ws for Grok: the product tour, the xAI API examples and the skill file.
- The free 3D Studio MCP: every tool, tier and limit in depth.
- MCP integration: every hosted server, OAuth and API keys.
- Connector probe results: the latest production run.
- Example: Responses API client.