unreal-engine-mcp-system-plugin/agent-gateway

In-engine agent gateway

A local HTTP/SSE server that runs a Claude agent (via the Claude Agent SDK) wired to this project's ue-blueprint MCP server, and serves a chat UI for the Unreal WebBrowser widget. Talk to the agent from inside the editor while it edits Blueprints, spawns nodes, builds C++, screenshots UMG, etc.

WBP_AgentChat (WebBrowser)  ──HTTP/SSE──▶  server.mjs (this)
   public/ chat UI                           ├─ @anthropic-ai/claude-agent-sdk  (the agent)
   stream text + tool cards                  ├─ spawns ../src/server.js          (ue-blueprint MCP)
   clickable /Game asset chips               └─ /api/focus → UE Remote Control   (sync Content Browser)

One-time setup

1. Install deps (already done once):

   cd Plugins/UEBlueprintMCP/agent-gateway
   npm install
   

2. Give the agent credentials. The gateway spawns its own agent process, so it needs auth that does not depend on your interactive Claude Code session. Pick one:

   • Subscription (recommended) — generate a long-lived token:

     claude setup-token
     

     Copy the printed token into agent-gateway/auth.env (gitignored):

     CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
     

   • API key (pay-as-you-go) — in auth.env:

     ANTHROPIC_API_KEY=sk-ant-api03-...
     

   GET /api/health returns "hasAuth": false until one is present, and the chat header shows a "no token" state.

3. Enable UE plugins: Web Browser (for the widget) and Remote Control API (for live tool access — WebControl.StartServer, default port 30010).

Run

npm start         # → http://127.0.0.1:8765

or double-click start-gateway.bat.

Open http://127.0.0.1:8765 in any browser to test the UI without UE.

Inside Unreal

Open /Game/UI/Agent/WBP_AgentChat, add it to the viewport (or dock it in an Editor Utility Widget). It hosts a full-bleed WebBrowser pointed at the gateway URL. See ../UI_WORKFLOW.md note: this screen is a deliberate exception to the UMG-token rule — all visuals live in public/styles.css (the :root block), not in DA_UITheme, because the surface is HTML inside a browser.

Config (env vars)

var	default	meaning
MCP_AGENT_PORT	8765	gateway port
MCP_AGENT_HOST	127.0.0.1	bind host
MCP_AGENT_MODEL	claude-opus-4-8	agent model
UE_PROJECT_DIR	repo root (auto)	project cwd handed to the agent
UE_REMOTE_CONTROL_URL	http://127.0.0.1:30010	UE Remote Control (asset focus)

Endpoints

• GET / — chat UI (static from public/)
• GET /api/health — { ok, model, projectDir, mcp, hasAuth }
• POST /api/chat — { message, sessionId? } → SSE stream of: init · text · thinking · tool_start · tool_end · error · done. done.sessionId is replayed by the client to continue the conversation.
• POST /api/focus — { path: "/Game/..." } → focuses the asset in UE's Content Browser (used by clickable asset chips).

Notes

• The agent runs with permissionMode: bypassPermissions (no interactive terminal exists behind a web UI) and inherits the project CLAUDE.md via settingSources: ["project"], so it follows the same conventions Claude Code does — including the MCP-first and UI vision-loop rules.
• Conversation state is per sessionId (SDK resume); the browser keeps it in memory for the page session.