@kvyverse/mcp

MCP bridge for Kvyverse — lets an AI agent (Claude Code or any MCP client) control a live Kvyverse editor session right in your browser: build scenes, write behaviour scripts and shaders, manage assets and settings, and teach you the editor as it works.

Setup

The server command is npx -y @kvyverse/mcp@latest — register it in your MCP agent. The bridge runs on Node.js 18+. The same steps are shown in the editor (burger menu → Agent MCP).

Claude Code

1. Install Claude Code if you don't have it (official installer, auto-updates; Homebrew/WinGet/npm also work):

   curl -fsSL https://claude.ai/install.sh | bash   # macOS/Linux/WSL
   irm https://claude.ai/install.ps1 | iex          # Windows PowerShell

2. Add the MCP server (one-time):

   claude mcp add -s user kvyverse -- npx -y @kvyverse/mcp@latest

3. Start a new agent session (run claude) — the bridge starts with it (/mcp should list kvyverse). To skip per-tool permission prompts, allow all Kvyverse tools once: /permissions → Allow → add the rule mcp__kvyverse (or put {"permissions": {"allow": ["mcp__kvyverse"]}} into ~/.claude/settings.json). Safe: the agent's edits are undoable and visible live in the editor. Not sure how? Just ask the agent — it will guide you.

Other MCP clients (Cursor, Claude Desktop, ...)

Add a stdio server to your client's MCP config; it usually looks like:

{
  "mcpServers": {
    "kvyverse": { "command": "npx", "args": ["-y", "@kvyverse/mcp@latest"] }
  }
}

Then start the client and approve the Kvyverse tools when prompted.

Clients that support the MCP Streamable HTTP transport can also skip the stdio process and connect straight to a running hub at http://127.0.0.1:7455/mcp (some bridge process must be alive to host the hub).

Connect

Open your world in the Kvyverse editor → burger menu → Agent MCP → Connect (the default http://127.0.0.1:7455 works for a local bridge).

How it works

Claude Code #1 ↔ stdio ↔ @kvyverse/mcp  ← LEADER: hub on 127.0.0.1:7455
Claude Code #2 ↔ stdio ↔ @kvyverse/mcp  ← follower
                              │ MCP Streamable HTTP → /mcp (leader's hub)
editor browser tab ───────────┘ SSE GET /editor/events + POST register/result

The bridge is a thin relay: the editor tab registers the tool set when it connects, tool calls are forwarded to the live editor and executed there (undoably — Cmd+Z works on the agent's changes), results stream back. While no editor tab is connected the tool list is empty and calls return "editor is not connected".

Multiple agent sessions share one port:

• Every bridge process is a stdio proxy (stdio MCP server ↔ Streamable HTTP MCP client to the hub). The first process to bind the port becomes the leader and additionally hosts the hub; the rest are followers and proxy through it — the leader itself goes through the same loopback code path.
• Leader died → followers detect it (heartbeat ping) and race with jitter to re-bind the port; the editor tab reconnects on its own (SSE auto-reconnect).
• The MCP client exited → stdin closes → the process exits and frees the port (no zombie processes).
• The hub reports the number of attached agents to the editor — the Agent MCP dialog shows "Connected · N agents". Agent sessions that die without a clean MCP DELETE are pruned by a hub-side ping within ~15s, so the counter stays honest.

Other notes:

• One editor tab at a time — a newer connection replaces the previous one.
• Tool calls time out after 60s; logs go to stderr only (stdout carries the MCP protocol).
• KVYVERSE_MCP_PORT overrides the port if 7455 is taken by unrelated software.

Development (in the kvyverse repo)

• Source: packages/kvyverse-mcp/src/ — index.ts (entry, leader election), stdio-proxy.ts, hub/Hub.ts (transport-agnostic core), hub/http-server.ts (node:http + SSE + CORS adapter), protocol.ts (editor↔hub contract; the app imports its types via the @kvyverse/mcp/protocol tsconfig alias).
• Dev run without building: bun packages/kvyverse-mcp/src/index.ts (point your MCP client at this command instead of npx).
• Build: bun run build (bundles deps and the agent instructions into dist/index.js, Node target, zero runtime dependencies).
• Publish: npm version patch && npm publish from this folder (prepublishOnly builds automatically).