Wire RakuAI into Claude Desktop

Supercharge your AI in the real world.

The six MCP tools (load_world_model, ingest_frame, get_scene_state, set_render_target, start_simulation, get_metrics) appear natively in Claude Desktop as soon as you add raku-mcp.fly.dev/mcp/ as an MCP server. Two paths below — PowerShell auto-config, or manual JSON edit. Same six-tool surface drives ChatGPT custom GPTs, Gemini, Copilot, and in-house agents — multi-vendor by design.

Prerequisites

  1. A raku_ API key — mint one at rakuai.com/developers/login.html. New developers: request access, accept the NDA, wait for an admin approval.
  2. Claude Desktop installed (claude.ai/download).
  3. Windows: PowerShell 5+ or 7+. macOS / Linux: same shape, swap the config path.

Path A — PowerShell auto-config (recommended)

The MCP server expects a developer JWT in the Authorization: Bearer ... header. JWTs expire in 24 hours, so the practical setup is a small script that exchanges your long-lived API key for a fresh JWT and patches Claude Desktop's config file. Run it whenever the tools stop appearing in Claude.

Refresh-RakuMcpJwt.ps1

Exchanges your API key for a JWT, patches claude_desktop_config.json.

Download

Run it

$env:RAKU_API_KEY = "raku_your_long_lived_key_here"
.\Refresh-RakuMcpJwt.ps1

That's it. Restart Claude Desktop, start a new conversation, ask Claude to call get_metrics on the Raku runtime.

Schedule it (optional)

If you'd rather not run it manually, register a Windows scheduled task to run daily:

schtasks /Create /SC DAILY /TN "Refresh Raku MCP JWT" `
  /TR "powershell -NoProfile -File C:\path\to\Refresh-RakuMcpJwt.ps1" `
  /ST 06:00
Long-term: we'll either bump the JWT TTL or accept the raw API key directly on raku-mcp.fly.dev so this refresh step goes away. Until then, the script is the path.

Path B — manual JSON edit

If you'd rather not run a script, edit Claude Desktop's config by hand. Location:

Merge in (or create) the mcpServers section:

{
  "mcpServers": {
    "raku": {
      "type": "http",
      "url": "https://raku-mcp.fly.dev/mcp/",
      "headers": {
        "Authorization": "Bearer <your-24h-developer-JWT>"
      }
    }
  }
}

Mint the JWT once with curl:

curl -sS -X POST https://api.rakuai.com/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"api_key":"raku_your_long_lived_key_here"}' \
  | jq -r .access_token

Paste the resulting token in place of <your-24h-developer-JWT> and restart Claude Desktop.

Verify it's working

Open a new conversation in Claude Desktop and prompt:

Call get_metrics on the Raku runtime.

You should see Claude invoke the get_metrics tool and return a JSON payload like:

{
  "fps": 0.0,
  "sim_running": false,
  "loaded_adapters": 0,
  "status": "ok"
}

If you don't see the tools, double-check (1) the JWT hasn't expired, (2) the path is exactly https://raku-mcp.fly.dev/mcp/ (trailing slash), (3) Claude Desktop was restarted after the config change.

The six tools

ToolModeWhat it does
get_metricsallFPS, frame time, adapter count, uptime — safe read.
get_scene_stateallSnapshot of nodes, physics bodies, loaded adapters, sim state.
load_world_modelsandbox/devRegister an adapter (Runway, Veo, Marble, Genie, content_pack).
ingest_framesandbox/devPush a frame from a generative model into the scene graph.
set_render_targetsandbox/devWebGL, VR headset, native window, or offscreen.
start_simulationsandbox/devBegin the simulation loop. Denied in production mode by design.

Read more about the MCP boundary →

Troubleshooting

The tools don't appear in Claude

The MCP server says “Authentication failed”

“start_simulation is blocked in production mode”

That's correct. raku-mcp.fly.dev runs in production mode and refuses mutating tools by design. Read-only tools (get_metrics, get_scene_state) work; mutations need a sandbox or dev deployment. We'll publish a local-dev path shortly.

Related