Content
# Tool List
**Language**: **English** · [简体中文](README.md)
JetBrains Rider MCP **Agent** plugin: Run an independent MCP HTTP server locally (default `:6800`), automatically discover UE instances, and forward AI tool calls to the **NexusLink** UE plugin via WebSocket. Specific capabilities such as blueprints, assets, and PIE are provided by the UE-side NexusLink, and this plugin does not implement game logic.
## What is this?
| Access Method | Endpoint | Applicable |
|----------|------|------|
| **Rider Agent** (this plugin) | `http://127.0.0.1:6800/stream` | JetBrains Rider users; automatic discovery/switching of multiple UE instances |
| Direct UE Connection | `http://127.0.0.1:45000/stream` | No IDE plugin required; must specify UE port manually |
The value of the proxy mode: The AI client only connects to a fixed port, and Rider is responsible for scanning the `45000`–`45100` range, maintaining WebSocket long connections, and switching between multiple Editor/PIE instances.
## Dependencies and Version Compatibility
| Component | Requirements |
|------|------|
| **nexus-rider** | Align with UE `proxy_config.minProxyVersion`; recommend using the latest version |
| **NexusLink** (UE plugin) | `nexus-mcp-unreal-*.zip` released with [NexusLink Releases](https://github.com/bytepine/NexusLink/releases); UE **4.26+** |
| **JetBrains Rider** | 2025.3+ (build `253`, compatible up to `263.*`) |
| **JDK** (for local build only) | 21 |
NexusLink installation: Unzip the zip file to the UE project's `Plugins/Developer/NexusLink` directory, and enable the plugin in the editor. See [UE Prerequisites](#1-ue-prerequisites) below.
## Getting Releases
| Artifact | Source |
|------|------|
| `nexus-mcp-rider-<version>.zip` | [NexusRider Releases](https://github.com/bytepine/NexusRider/releases) |
| `nexus-mcp-unreal-<version>.zip` (NexusLink UE plugin) | [NexusLink Releases](https://github.com/bytepine/NexusLink/releases) |
You can also build locally and install via **Settings → Plugins → Install Plugin from Disk**.
## Architecture Overview
```mermaid
flowchart TB
AI["AI Client<br/>Cursor / CodeBuddy / Windsurf …"]
subgraph Rider["nexus-rider (Rider Plugin)"]
direction TB
HTTP["MCP HTTP Server<br/>Netty · default :6800"]
Mgr["Instance Discovery + Tool Proxy<br/>UnrealInstanceManager"]
HTTP --- Mgr
end
subgraph UE["UE Process · NexusLink"]
Link["HTTP + WebSocket<br/>default :45000 / :55000"]
end
AI -->|"POST /stream<br/>Streamable HTTP"| HTTP
AI -->|"GET /sse · GET /stream<br/>SSE Notification Stream"| HTTP
Mgr -->|"Concurrent Port Scan<br/>GET /status"| Link
Mgr <-->|"WebSocket JSON-RPC<br/>Bidirectional Long Connection"| Link
```
**Data Path**: AI client connects to Rider agent via MCP HTTP; agent connects to UE via WebSocket JSON-RPC, eliminating UE-side MCP handshake overhead. UE must enable MCP server in Editor Preferences to be scanned.
### Internal Components
```mermaid
flowchart LR
Startup["NexusLinkStartupActivity<br/>Start/stop service after project opens"]
Server["NexusMcpServer<br/>Netty HTTP · per-session"]
Dispatcher["NexusMcpDispatcher<br/>MCP Handshake · tool routing"]
Manager["UnrealInstanceManager<br/>Discovery · WS long connection · pass-through"]
Settings["NexusLinkSettings<br/>Persistent configuration"]
UI["NexusLinkConfigurable<br/>NexusLinkStatusBarWidget"]
Startup --> Server
Startup --> Manager
Server --> Dispatcher
Dispatcher --> Manager
Settings --> Startup
UI --> Settings
```
| Component | Responsibility |
|------|------|
| `NexusLinkStartupActivity` | Start/stop MCP service after project opens; periodically call `maintainConnection` |
| `NexusMcpServer` | Netty HTTP server; `POST /stream` + `GET /sse`/`/stream`; `Mcp-Session-Id` session isolation |
| `NexusMcpDispatcher` | JSON-RPC 2.0 parsing; `initialize` → `initialized` → `tools/list` / `tools/call` |
| `UnrealInstanceManager` | Port scan discovery; WebSocket long connection; `list_unreal_instances` / `connect_unreal_instance`; remote tool pass-through |
| `ProxyConfig` | Cache UE-pushed `nexus/proxy_config`; drive connection tool text and `initialize.instructions` |
### Tool Call Process
```mermaid
sequenceDiagram
participant AI as AI Client
participant HTTP as NexusMcpServer
participant Disp as NexusMcpDispatcher
participant Mgr as UnrealInstanceManager
participant UE as NexusLink (UE)
AI->>HTTP: POST /stream tools/call
HTTP->>Disp: dispatch (per-session)
alt arguments.targetPort specified
Disp->>Mgr: forwardToolCallsToPort (one-time WS)
else default
Disp->>Mgr: ensureLongConnection + forward
end
Mgr->>UE: WebSocket JSON-RPC
UE-->>Mgr: execution result
Mgr-->>Disp: outcome
Disp-->>HTTP: JSON-RPC result
HTTP-->>AI: HTTP response
```
## Installation and Usage
> **Must Open Project**: MCP service starts in `ProjectActivity` — Rider must **open any project** (File → Open) to listen to the port. Only after opening a project (even if it's just the Rider welcome page) will the service start.
### 1. UE Prerequisites
NexusLink's MCP HTTP/WebSocket **does not start by default**; you must enable it in UE:
1. Download `nexus-mcp-unreal-*.zip` from [NexusLink Releases](https://github.com/bytepine/NexusLink/releases) and unzip to `Plugins/Developer/NexusLink`
2. **Edit → Plugins → Developer → NexusLink** — enable the plugin and restart the editor
3. **Edit → Editor Preferences → Plugins → NexusLink** — check **Enable MCP Server**
4. Save to apply changes; the toolbar/settings panel will display the actual HTTP port (default `45000`) and WebSocket port (default `55000`)
If not checked, Rider scan results will be empty, and the status bar will display **⬡ Nexus**.
### 2. Install Plugin
1. Download `nexus-mcp-rider-<version>.zip` from [NexusRider Releases](https://github.com/bytepine/NexusRider/releases) or build locally
2. Rider → **Settings → Plugins → ⚙ → Install Plugin from Disk** → select zip
3. Restart Rider, **open a project**
4. **Settings → Tools → Nexus MCP** → check **Enable Nexus MCP Server** (default disabled; checked to start, unchecked to stop, no restart required)
### 3. Configuration
Entry: **Settings → Tools → Nexus MCP**
| Option | Default Value | Description |
|--------|--------|------|
| Enable Nexus MCP Server | `false` | Master switch; checked to start, unchecked to stop, no restart required |
| MCP Port | `6800` | AI client connection port; **change requires Rider restart** |
| Scan Port Range | `45000`–`45100` | UE instance discovery range; change requires MCP service restart (toggle master switch) |
| Scan Interval | `5` seconds | Periodic discovery interval; change has same effect as above |
The settings panel also provides **Streamable HTTP Configuration** and **SSE Configuration** buttons, which generate AI client JSON snippets for copying in the preview box.
### 4. Status Bar
Rider's bottom status bar displays UE connection status:
| Display | Meaning |
|------|------|
| **⬢ Project Name** | Connected to UE instance |
| **⬡ Nexus** | Not connected |
Clicking the status bar pops up the instance list, allowing one-click switching of connection targets. There is no command panel refresh command; it relies on periodic scanning and immediate re-scanning after disconnection.
### 5. UE Instance Discovery
- **Strategy**: 20-thread concurrent scan of configured port range, per-port `GET /status` verification of liveness and project name, `netRole`, etc.
- **Auto-connect**: Only one instance is automatically connected; for multiple instances, prioritize `netRole=Editor`, and allow manual switching on the status bar
- **Preferred Port**: User-manual selection records `preferredPort`; upon disconnection, re-scan prioritizes recovery
- **Steady-state Optimization**: During long connection liveness, most rounds only probe current port with heartbeats; every 6 rounds perform a full scan
- **Disconnection Handling**: Immediate async re-scan; does not broadcast `tools/list_changed`, but retains tool list cache; upon reconnection or MCP session `initialized`, refreshes the list
## Proxy Tool Reference
In addition to UE remote tools, the proxy layer has 2 built-in local tools (name and schema can be overridden by UE `proxy_config`; if not connected, use the following fallback).
### `list_unreal_instances`
Discover all active UE instances within the current scan range.
**Parameters**: None (`inputSchema`: empty object)
**Return** (`content[0].text` is JSON array):
| Field | Type | Description |
|------|------|------|
| `port` | int | UE HTTP port (used when `connect`) |
| `projectName` | string | Project name |
| `engineVersion` | string | Engine version |
| `netRole` | string | `Editor` / `DedicatedServer` / `ListenServer` / `Client` / `Standalone` |
| `connected` | bool | Whether it's the current long connection target and WS is still OPEN |
### `connect_unreal_instance`
Connect to the specified port UE instance and set it as `preferredPort`.
**Parameters**:
```json
{ "port": 45000 }
```
### Remote Tools and `targetPort`
`tools/list` merges UE tool lists when connected. `tools/call` defaults to forwarding to the currently bound instance (timeout **120s**).
For concurrent queries on multiple instances, add `targetPort` in `arguments`, using a one-time WebSocket without changing the long connection binding:
```json
{
"name": "call_capability",
"arguments": {
"targetPort": 45001,
"capability": "get_editor_context",
"arguments": {}
}
}
```
## Feature List
### Independent MCP Server (for AI Clients)
- [x] Netty-based HTTP/1.1 MCP server (not dependent on Rider's built-in MCP)
- [x] Dual endpoints: `POST /stream` (Streamable HTTP) + `GET /sse` / `GET /stream` (SSE notification stream, sharing the same handler)
- [x] Compatible with MCP old SSE transport (2024-11-05) and new Streamable HTTP (2025-03-26) dual protocols; negotiate version `2025-06-18`
- [x] JSON-RPC 2.0 protocol + MCP session state machine (initialize/initialized/ping/tools)
- [x] per-session session isolation (`Mcp-Session-Id` header); multiple AI clients can connect concurrently without interference
- [x] Configurable listening port (default 6800); automatic port increment (up to 100 ports) on conflict
### UE Instance Discovery and Management
- [x] Port scan + `GET /status` real connectivity verification (no stale process residue)
- [x] Periodic automatic re-discovery (default every 5 seconds)
- [x] WebSocket long connection communication (JSON-RPC, no MCP handshake overhead)
- [x] Multi-instance support: list all discovered UE instances and their project information
- [x] `preferredPort` retains user-manual selection
- [x] During disconnection, retain tool list cache to prevent AI clients from downgrading `tools/call` to Tool not found
### IDE Integration
- [x] Settings panel (**Tools → Nexus MCP**): master switch, port and scan configurations, one-click copy AI client configuration
- [x] Status bar component: real-time display of UE connection status, click to switch instances
- [x] UE connection/disconnection automatically pushes `notifications/tools/list_changed`
### MCP Tool Proxy
- [x] `list_unreal_instances` / `connect_unreal_instance` — see [Proxy Tool Reference](#proxy-tool-reference)
- [x] `initialize.instructions` — async pull UE `nexus/instructions`, stitch `InitializeInstructions.*.md` into handshake response
- [x] Connection tool text is delivered by UE `nexus/proxy_config` (`ProxyConfig.json`); fallback to generic text if not connected
- [x] Remote tool pass-through: `tools/list` merges UE tool lists; `tools/call` defaults to forwarding via long connection; `arguments.targetPort` uses one-time WS
## AI Client Configuration
Default endpoint `http://127.0.0.1:6800/stream`. If MCP port is occupied, it auto-increments; refer to Rider startup notifications or settings panel for the actual port.
**Cursor** (`~/.cursor/mcp.json`, Streamable HTTP):
```json
{
"mcpServers": {
"nexus-unreal": {
"url": "http://127.0.0.1:6800/stream"
}
}
}
```
**CodeBuddy / Windsurf** (Streamable HTTP):
```json
"Nexus": {
"url": "http://127.0.0.1:6800/stream",
"transportType": "streamable-http",
"description": "NexusLink MCP Server for Unreal Engine",
"disabled": false
}
```
**SSE Transport** (legacy MCP client):
```json
"nexus-unreal": {
"url": "http://127.0.0.1:6800/sse"
}
```
## Local Build and Development
### Build Installation Package
```bash
./gradlew buildPlugin # Windows: gradlew.bat buildPlugin
# or
build.bat # equivalent to gradlew clean buildPlugin
```
Artifact: `build/distributions/*.zip`.
### Release (Maintainer)
GitHub Release **sole source of truth** is the `[X.Y.Z]` section of `CHANGELOG.md` (verified by CI via `scripts/extract_release_notes.py --verify`). No handwritten Release notes on the web or `gh release create`.
1. Archive `[Unreleased]` → `[X.Y.Z] - YYYY-MM-DD`, update `VERSION`
2. `py scripts/extract_release_notes.py --version X.Y.Z --verify` (preview stdout, confirm correctness)
3. `git commit` → `git tag -a nexus-rider-vX.Y.Z` → `git push origin HEAD` + `git push origin nexus-rider-vX.Y.Z`
After pushing the tag, `.github/workflows/release.yml` packages `nexus-mcp-rider-<ver>.zip` and publishes the Release.
### Debug Plugin
```bash
./gradlew runIde
```
Requirements:
- Local installation of **Rider 2025.3** (matching `platformVersion=2025.3` in `gradle.properties`)
- **JDK 21**
- `build.gradle.kts` uses `useInstaller = false`, relying on local IDE SDK instead of auto-downloading
Source directory: `src/main/kotlin/com/nexusmcp/mcp/`
For feature changes, update the `[Unreleased]` section of [CHANGELOG.md](CHANGELOG.md).
---
## Tech Stack
| Category | Selection |
|------|------|
| Language / Platform | Kotlin + IntelliJ Platform Plugin (Rider module) |
| MCP HTTP | Netty (`compileOnly`, reusing Rider's built-in to avoid ClassLoader conflicts) |
| UE Communication | Java-WebSocket client + `org.json` |
| Build | Gradle 9 + IntelliJ Platform Gradle Plugin 2.x |
---
## Frequently Asked Questions
### AI client shows "MCP initialization timeout"
- Confirm Rider has **opened a project** and the setting to **enable Nexus MCP server** is checked
- Confirm UE has **enabled MCP server** and the NexusLink plugin is loaded
- Check the AI client configuration port matches Rider's actual listening port (default `6800`)
- Confirm Rider's status bar shows **⬢ Project name** (connected to UE)
### Multiple Rider project windows
MCP server is mounted per **project**. When multiple projects are open, windows may compete for port `6800`; subsequent windows will automatically use the next available port (`6801`...). Configure the AI client with the actual port from each window's startup notification.
### Multiple AI clients used simultaneously
Supports per-session isolation (`Mcp-Session-Id` header). Multiple AI clients can connect to the same Rider MCP server without interference.
### Multiple UE instances running concurrently
Each UE instance automatically allocates a different port. Rider automatically discovers all instances; select the target in the status bar. For concurrent queries with multiple instances, see [targetPort example](#remote-tool-with-targetport).
### Tool list not refreshing
When UE connects/disconnects, the proxy pushes `notifications/tools/list_changed`. If the AI client doesn't update, try reconnecting MCP or restarting the AI session; the proxy will preheat `tools/list` and resend notifications upon `initialized` completion.
### Viewing logs
Rider logs: `%LOCALAPPDATA%\JetBrains\Rider<version>\log\idea.log` (macOS/Linux: `~/Library/Logs/JetBrains/Rider<version>/idea.log`). Search for the keyword `Nexus MCP`.
### UE asset modifications not reflected on disk
This behavior is specific to NexusLink/UE (e.g., `save_asset` landing) and unrelated to this proxy.
---
## Change Log
See [CHANGELOG.md](CHANGELOG.md).
---
## License
[MIT](LICENSE) © byteyang
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available