Option 1 — Native connector (recommended)

Clients with built-in remote MCP support (Claude, and others adding it) let you add a custom connector URL directly in their settings. Add this URL and sign in with Google or GitHub — no API key to paste, no package to install:

https://mcp.niua.ohao.tech/mcp

Add as a connector — sign in with Google or GitHub.

Option 2 — stdio bridge (any other client)

Clients without native remote MCP support (Cursor, Cline, etc.) can use the community mcp-remote bridge. It opens a browser tab to sign in, then proxies the hosted server over stdio. Paste this block into your client's MCP config:

{
  "mcpServers": {
    "niua": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.niua.ohao.tech/mcp"]
    }
  }
}

• Cursor — one-click: Add to Cursor (opens Cursor and installs the remote server), or paste the block above into the MCP block in settings.json.
• Cline — the MCP panel inside VS Code's extension settings.

Option 3 — API key (CI / power users)

To skip the browser sign-in — for CI pipelines or scripted workflows — get a key from Settings → Developer. Keys start with niua_live_. Pass it as a header to the native connector, or add it to the bridge config:

{
  "mcpServers": {
    "niua": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.niua.ohao.tech/mcp",
        "--header", "Authorization: Bearer niua_live_your_key_here"
      ]
    }
  }
}

Verify it worked

After connecting, ask your agent: "use niua to generate an image of a samurai mecha" — the agent will call generate_image and return a CDN URL.

Twenty-two tools are live on the remote server.

Generation

• generate_image — text prompt to PNG.
• generate_music — text prompt (with optional lyrics) to WAV.
• generate_text2motion — text prompt to BVH animation.
• generate_mesh — image to textured GLB. tier: game (default, faster cascade) / light / hero (full cascade, max detail).
• reexport_mesh — LOD budgets from a saved mesh recipe (ceiling = source tier).
• decompose_mesh — mesh to complete, watertight named parts (frame, limbs, lids — ready to animate). Not available in the EU, UK, or South Korea (model licensing).
• generate_mesh_texture — mesh + reference image to PBR-textured GLB.
• generate_rig — GLB to auto-rigged GLB.
• generate_motion — video to BVH motion capture.
• generate_speech — text to spoken WAV (named voice library).
• generate_sfx — text prompt to sound-effect WAV.
• generate_dialogue — multi-speaker script to dialogue WAV.
• generate_voicegen — voice description to a designed voice.

Discovery and account

• list_voices — list the voices in your voice library.
• check_balance — your current wallet balance.
• get_job — look up an async job by id.
• list_jobs — your recent jobs, newest first, with lineage.
• wait_for_job — the way to await any async job: polls server-side until it finishes or times out, and returns the full job body (including the failure reason on error if it failed). Replaces a hand-rolled sleep-poll loop around get_job.
• wait_for_jobs — batch form of wait_for_job: await up to 20 job ids together on one shared timeout.

Every modality is also available via the REST API.

Every tool that takes an image, video, or mesh input accepts it three ways:

• image_key / video_key / mesh_key — the output of a prior NIUA job.
• image_url — a public https:// URL. The MCP server fetches it and stages it for you.
• A local file — upload it with create_upload and finalize_upload, then pass the returned asset_key as the matching *_key field.

Local-file flow

Four calls: presign, PUT the bytes, finalize, then generate.

create_upload({ filename: "hero.jpg", content_type: "image/jpeg", size_bytes: 812345 })
  → { asset_id, upload_url }

curl -X PUT --data-binary @hero.jpg -H "Content-Type: image/jpeg" "<upload_url>"

finalize_upload({ asset_id })
  → { asset_key }

generate_mesh({ image_key: asset_key })

create_upload returns an upload_url that expires in about an hour — PUT the file's raw bytes to it directly (not JSON, not multipart). finalize_upload then validates the upload and returns an asset_key — the gateway's storage key (r2_key), usable anywhere a *_key field is accepted. Uploads are free; you're only charged when a generation tool consumes the asset.

Accepted content_type values: image/png, image/jpeg, image/webp, audio/wav, audio/mpeg, model/gltf-binary, model/obj, video/mp4, text/plain (BVH motion).

Every generation tool except generate_image returns a job_id immediately and runs in the background. Call wait_for_job with that job_id — it polls server-side until the job reports completed or failed, then hands back the full job body (asset URL on success, an error string on failure). This is the recommended way to await a job; use get_job only for a one-off status check.

Mesh is the slow one — typically 5 to 9 minutes of background processing, well past wait_for_job's default 480s timeout. If it times out (wait_status: "timeout"), the job is still running — call wait_for_job again with the same job_id; nothing is lost. Firing off several generations in parallel? Use wait_for_jobs to await up to 20 job ids on one shared timeout.

The bridge writes grep-able key=value lines to stderr:

[niua-mcp] event=ready version="0.7.1" server_url="https://mcp.niua.ohao.tech/mcp"
[niua-mcp] event=tool_call tool="generate_image" width=1024 height=1024
[niua-mcp] event=tool_ok tool="generate_image" ms=8421

Host clients (Claude, Cursor) show these in their MCP server logs panel. To inspect the server interactively, use the official MCP Inspector pointed at the remote endpoint:

npx @modelcontextprotocol/inspector npx mcp-remote https://mcp.niua.ohao.tech/mcp

The Inspector UI lets you call tools directly without needing a host client.

Tool returns "not authenticated." Re-run the connector setup or clear your auth cache with rm -rf ~/.mcp-auth — the next connection will open a browser to sign in again.

Tool returns "[insufficient_funds] ..." Top up your wallet at /pricing.

Bridge hangs or fails to sign in. Make sure mcp-remote can open a browser window. In headless environments, use the API key flow (Option 3) instead.

Client shows the server as disconnected. Check your network can reach mcp.niua.ohao.tech. You can verify with curl https://mcp.niua.ohao.tech/healthz.

Anything else — drop into the Discord and post your config + the error. Faster than email, and other people have probably hit the same thing.

MCP, short for Model Context Protocol, is an open standard for connecting AI agents to outside tools. An MCP server exposes capabilities (tools); an MCP client (Claude, Cursor, Cline) connects to one or more servers and gives its agent access to what they expose.

The NIUA MCP server is hosted at mcp.niua.ohao.tech. Clients with native remote MCP support connect to it directly by URL. For clients that only support stdio, the open-source mcp-remote bridge runs locally and proxies the connection. For the broader protocol, see modelcontextprotocol.io.