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.
three.ws for Grok and Grok Bot
Give Grok a 3D studio and a body. One remote MCP server lets Grok Bot, Grok connectors and the xAI API turn text or an image into a textured 3D model, a rigged animation-ready avatar, or a named 3D persona that lip-syncs its replies. The studio is free: no account, no payment, no API key. Sign the same URL in to your three.ws account and it also manages your agents, their memory and skills, without ever being able to spend.
Live page and demo: three.ws/grok
Connector reference (exact fields per sign-in mode, the result and job contracts, limits, troubleshooting): Grok Bot connector reference
| URL | https://three.ws/api/mcp-grok |
| Transport | Streamable HTTP (JSON-RPC over POST) |
| Auth | None for the studio. Optional: a connector API key, or OAuth 2.1 at https://three.ws/api/mcp-grok?auth=oauth, adds your agent tools |
| Protocol | MCP 2025-06-18 |
| Tools | The full free studio: the same fifteen tools as /api/mcp-studio. Signed in, also your account's agent tools |
Grok Bot
Grok Bot adds a custom MCP server from chat. Send:
Add a custom MCP server called three-ws-grok at https://three.ws/api/mcp-grok
Say "custom server" (the sentence above does), or Grok Bot may look for a
marketplace plugin instead. It shows the name and URL and asks you to confirm.
No sign-in card appears, because there is nothing to sign in to. Then ask for 3D
in any task, or attach the server with @three-ws-grok:
- "Make a 3D model of a reusable rocket booster with grid fins, then send me the viewer link and the GLB."
- "Give yourself a body: forge a friendly white robot, save it as your persona, and say hello to me with it."
- "Turn this photo into a rigged, animation-ready 3D avatar and save the GLB to my files."
Grok Bot works on its own cloud computer, so it can save the GLB to its files, hand it to another tool in the same task, or run the request on a schedule.
Prefer the connector form to chat? three.ws/connect?client=grok
lists the exact fields (name, transport Streamable HTTP, URL, authentication)
for whichever hosted server you pick, with a copy button for each URL. The URL
must be public: Grok Bot connects from xAI's cloud, so a localhost server
never works.
Your account on the same URL
The free studio needs no account. To let Grok Bot also work with your agents, their memory and skills, and your avatars (on a schedule, say), keep the same URL and give it a credential. Two ways:
- Connector key (recommended for Grok Bot). At three.ws/dashboard/api choose New key, then For an AI agent (Grok Bot, schedules, CI), name it, and copy the key it shows once. Ask Grok Bot to add a custom MCP server at
https://three.ws/api/mcp-grokwith API key authentication, and store the key as a Bot secret. It is sent asAuthorization: Bearer sk_live_…. - OAuth 2.1. Use
https://three.ws/api/mcp-grok?auth=oauthas the server URL with OAuth authentication. The?auth=oauthform answers an anonymous client with401and aWWW-Authenticatechallenge, which is what makes an MCP client start sign-in; the plain URL serves anonymous clients and so never would. The connector registers itself, you approve the consent screen once, and every token it holds is refused the moment you revoke the app in Connected apps.
Signed in, tools/list adds these to the fifteen studio tools, each only when
the credential's scopes allow it and your MCP tool settings
leave it on:
| Tool | What it does |
|---|---|
create_agent, attach_avatar_to_agent |
Create an agent on your account and give it a body you generated with forge_avatar. |
identity_check, call_agent |
Screen an agent identity, or send another three.ws agent a message and get its reply. |
remember, recall |
Your agents' long-term memory. |
list_available_skills, import_community_skill, list_custom_skills, get_custom_skill, create_custom_skill, update_custom_skill |
Your agents' prompt-only skills. |
list_skill_candidates |
Skills your agents drafted for themselves from runs that worked (read-only; you approve them on the dashboard). |
list_my_avatars, get_avatar, get_embed_code, render_avatar_image |
Your avatars, their embed snippets and rendered images. |
read_resource |
Read-only views of your account and agents (three://me, three://agents, and each agent's usage, runs, earnings and wallet state), which the agent-report prompt reads. Reading a balance moves nothing. |
It never spends. No wallet, payment, card, trading, launch or delete tool is
ever listed on this URL, whatever scopes the credential holds, and calling one by
name answers unknown tool. Those actions happen in a browser at
three.ws/dashboard. The same tools run through the core server's
policy, scope checks and spend gate exactly as on /api/mcp, and the free tools
stay anonymous: signing in changes nothing about what they do, except that your
generation caps key on your account instead of the MCP session.
A credential that no longer verifies (expired, revoked, or minted for another
server) is answered with 401 and the challenge rather than served anonymously,
so a connector re-authenticates instead of quietly losing your tools. An account
tool called without signing in answers JSON-RPC -32002 with
data.reason: "sign_in_required" and the OAuth URL. Scopes and the exact spend
refusal: API key scopes.
Grok connectors
On paid Grok plans, custom connectors take a remote MCP URL (remote servers
only, which this is). Open Connectors, add a custom connector, paste
https://three.ws/api/mcp-grok, and leave authentication off. Business and
Enterprise workspaces may need an admin to allow custom connectors first.
xAI API
The Responses API connects to remote MCP servers on xAI's side. Pass the server as a tool (xAI's Remote MCP docs):
curl https://api.x.ai/v1/responses \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.7",
"input": [{"role": "user", "content": "Make a 3D model of a lunar lander and give me the viewer link."}],
"tools": [{
"type": "mcp",
"server_url": "https://three.ws/api/mcp-grok",
"server_label": "three-ws"
}]
}'
With the Python SDK (pip install xai-sdk):
import os
from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import mcp
client = Client(api_key=os.environ["XAI_API_KEY"])
chat = client.chat.create(
model="grok-4.7",
tools=[mcp(server_url="https://three.ws/api/mcp-grok", server_label="three-ws")],
)
chat.append(user("Make a 3D model of a lunar lander and give me the viewer link."))
print(chat.sample().content)
Add allowed_tools (allowed_tool_names in the Python SDK) to expose only the
tools a task needs, for example ["search_catalog", "forge_free", "get_job"].
A complete, zero-dependency Node script that also collects slow renders lives in
examples/grok-remote-mcp.
A skill file for Grok
three.ws/grok-skill.md teaches Grok all of this
in one Markdown file: what three.ws does, the connector sentence for Grok Bot,
the sign-in options, runnable curl JSON-RPC calls for when no connector is set
up (open a session, list tools, search the catalog, generate, collect with
check_job), the links contract, what needs an account, and the spend rule.
Upload it to Grok's Skills, or ask Grok Bot to fetch it to its files:
Download https://three.ws/grok-skill.md to your files and follow it whenever I ask for 3D.
When no connector is set up, the file's plain HTTPS section is enough on its
own: runnable curl JSON-RPC calls to the free server
(https://three.ws/api/mcp-grok, the same tools without a session) that open a
session, search the catalog, fetch embed code, generate a model and render it
from several angles. Every example is run against production before the file
changes.
It renders from data/grok-skill-md.template.md
with the same facts as the general skill.md
(server URLs, tool and prompt names, free limits), read from the code that owns
each one, so the two files cannot disagree. node scripts/build-skills-pack.mjs
renders it, npm run check:skills-pack fails when it is stale, and
tests/grok-skill-md.test.js checks that every
URL in it resolves to a route this server serves and that the limits match the
handler. A renamed tool fails the build rather than shipping a file that names it.
What Grok gets
| Tool | What it does |
|---|---|
forge_free |
Text to a textured 3D model (GLB). |
text_to_avatar, mesh_forge |
An avatar or an art-directed mesh from text or a reference image. |
forge_avatar |
Generate and rig a character in one step. |
rig_mesh |
Add a humanoid skeleton to any static GLB. |
refine_model |
Change a model in words ("make it metallic") with a version history. |
get_job |
Status of a render that outlived one call: status, progress, eta_seconds, then the model and its links. check_job does the same and stays for older clients. |
look_at_model |
Render a GLB from several angles so Grok can see what it made. |
search_catalog, get_catalog_item, get_item_source |
Thousands of ready-made CC0 props, rigged characters and motion clips, plus paste-ready embed code. |
create_agent_persona, get_agent_persona, persona_say |
Save a rigged model as a named body, bring it back later, and make it speak a reply with lip-sync and emotion. |
Every finished model comes back with a viewer_url (an interactive viewer that
opens in any browser), a glb_url, a poster_png_url and embed_html. Nothing
renders inline in Grok, so this URL lists no widget templates and no ui://
resources, and the server's instructions tell Grok to hand those links to the
user. Signed in, Grok also gets the account tools.
Scheduled tasks: guided prompts
Grok Bot runs tasks on a schedule with nobody watching, so this URL serves MCP
prompts (prompts/list, prompts/get) written for exactly that: each one names
the tools to call with their exact argument objects, keys every generation with
an idempotency_key built from the prompt, the schedule id and the date, never
stops to ask, and ends with the plain links Grok hands back.
| Prompt | Arguments | What a run does |
|---|---|---|
agent-get-started |
none | Every call this connector can make, the links contract, and the first scheduled task to set up. |
daily-3d-brief |
topic (default trending) |
Picks the day's top topic (or yours), generates a model, checks it with look_at_model, and returns the viewer, GLB, poster PNG and embed. |
asset-pack |
theme, count |
Takes ready-made catalog items first, generates only the gaps, and returns one row of links per asset. |
avatar-from-photo |
image_url |
A rigged, animation-ready avatar from a photo, its links, and a pose studio link. |
agent-report |
agentId (optional) |
Signed in only: a read-only status of your agents (activity, runs, cost, earnings, wallet state) and what needs attention. |
A schedule such as "every morning, run the daily-3d-brief prompt from
three-ws-grok and send me the links" is all it takes. three.ws/grok
has three of these as copy-ready recipes, each with the calls it makes in order. Anonymous, the connector lists
the first four; signed in, it adds agent-report. Each prompt is written out as
its calls in MCP use cases, and
api/_mcp/prompts.js renders them against the
caller's own tools/list, so a prompt never names a tool the connector cannot
call.
A skill file for Grok
https://three.ws/grok-skill.md teaches
Grok all of the above in one Markdown file: the connector URL and its settings,
the plain HTTPS fallback, the links contract, the free limits, what needs an
account, and the rule that a connector never spends. Upload it to Grok's Skills,
or have Grok Bot keep it in its files:
Download https://three.ws/grok-skill.md to your files and follow it whenever I ask for anything 3D.
It works without a connector too. Grok Bot has a terminal, so the file shows the
free server as curl JSON-RPC calls that run as written: list the tools, search
the ready-made library, get paste-ready code for a match, generate a model, and
collect a render that outlived the call:
curl -s -X POST https://three.ws/api/mcp-studio \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_catalog","arguments":{"q":"chair","limit":2}}}'
The file is the Grok edition of the general /skill.md.
Both render from one set of facts, so their URLs, mint and free limits cannot
disagree; see Agent Skills.
How it behaves under Grok
No call hangs. A model usually lands in under a minute, but a GPU that has
scaled to zero boots first, and a render can take a few minutes. Grok calls MCP
from xAI's cloud with no published timeout, so this surface answers every call
within 40 seconds: with the model, or with a pending job and the seconds to
wait. The server's instructions tell Grok to call get_job(job_id) until the
model is done and keep going without asking the user.
Retries never generate twice. Every generation tool takes an optional
idempotency_key. A scheduled task that passes its task id as the key and
retries after a timeout gets the first run's job back (idempotent_replay: true), not a second model, and the retry costs none of its quota. Keys belong to
the caller, so a task that reconnects keeps them only on a connector URL with an
install token (below). Details:
Retries and idempotency_key. In the Responses API,
where Grok cannot wait between calls in one response, continue the conversation
with previous_response_id, as the example does.
Your own quota. Every Grok user reaches three.ws from xAI's shared egress,
so per-IP limits would ration all of Grok as a single caller. MCP Streamable
HTTP has a per-connection identity: on initialize the server issues an
Mcp-Session-Id, and a conforming client sends it back on every later request.
/api/mcp-grok keys the per-caller generation caps on that session. Minting a
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.
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)
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.
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
/api/mcp-grok is one of three front doors on the same handler
(api/_mcp-studio/handler.js); SURFACES in
api/_mcp-studio/dispatch.js defines what each
advertises. The account tools come from the core server through
api/_mcp-studio/account-tools.js, whose
allowlist only admits a tool the shared policy says moves no value. They share one generation quota and one breaker, so the Grok door
never adds GPU spend of its own. See the free 3D Studio MCP
for the tools in depth and MCP integration for every hosted server.