Connect a client to three.ws MCP

three.ws publishes a machine-readable directory of its hosted MCP servers. Fetch it rather than trusting a list in any document, including this one:

curl -s https://three.ws/.well-known/mcp.json

Each entry carries name, endpoint, transport, auth, and its documentation link. As of this writing the directory lists 7 hosted servers over Streamable HTTP, and dozens more install-and-run servers are published on npm under the @three-ws scope and registered in the MCP registry (https://registry.modelcontextprotocol.io/?q=io.github.nirholas).

Which server to add

Start with the free one. https://three.ws/api/mcp-studio needs no account, no key, and no payment, and it already covers the whole generate-and-rig path. Add the authenticated server only when the user wants their own library, agents, or money.

Claude Code

Project scope, in .mcp.json at the repo root (Claude Code auto-discovers it):

{
  "mcpServers": {
    "three-ws-studio": {
      "type": "http",
      "url": "https://three.ws/api/mcp-studio"
    }
  }
}

With an API key, reference an environment variable rather than pasting the secret into a file that gets committed:

{
  "mcpServers": {
    "three-ws": {
      "type": "http",
      "url": "https://three.ws/api/mcp",
      "headers": { "Authorization": "Bearer ${THREE_WS_MCP_TOKEN}" }
    }
  }
}

Then export THREE_WS_MCP_TOKEN='sk_live_...' in the shell that starts Claude Code, and restart the session so the client re-reads the file. The same block works in ~/.claude/settings.json under mcpServers when the user wants it on every project.

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "three-ws": {
      "command": "npx",
      "args": ["-y", "@three-ws/mcp-server", "--url", "https://three.ws/"]
    }
  }
}

That npm package handles the OAuth dance locally, which is what a desktop client wants. --url also lets the user point at a local dev server (http://localhost:3000/).

Any other client

POST JSON-RPC 2.0 to the endpoint. The server is stateless beyond the initialize handshake, so nothing else needs to be set up:

curl -s -X POST https://three.ws/api/mcp-studio \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

For the Agent SDK, register the same URL as an HTTP MCP server in the SDK's mcpServers option and pass the Authorization header if the server needs one.

Get a key when one is needed

1. Sign in at https://three.ws/login.
2. Open three.ws/dashboard/api, create a key, and copy the secret. It is shown once: the server stores only a SHA-256 hash and the 12-character prefix.
3. Scopes are fixed at creation. Pick from avatars:read, avatars:write, avatars:delete, profile, memory:read, memory:write, agents:read, agents:write. A read-only client should get read scopes only.
4. Secrets look like sk_live_... (or sk_test_...). Minting is limited to 30 keys per hour, per account.

Never write a key into a file inside the user's repo. Environment variable, or the client's own secret store.

Verify it worked

Ask the client to list tools, or run the curl above. A healthy free server answers with its tool set, which currently includes forge_free, text_to_avatar, mesh_forge, rig_mesh, forge_avatar, refine_model, check_job, look_at_model, create_agent_persona, get_agent_persona, and persona_say. Call tools/list for the live set rather than assuming this list is current.

Then prove the round trip with real work, not a ping:

curl -s -X POST https://three.ws/api/mcp-studio \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"forge_free","arguments":{"prompt":"a small brass desk lamp"}}}'

When it does not connect

Related

• The tools themselves: generate-3d-model, create-3d-avatar, rig-a-model, find-3d-assets all describe the MCP tool and the plain HTTP call side by side.
• Paying for tools: pay-for-service and x402 handle a 402 challenge.
• Full reference: three.ws/docs/mcp.