# How MCP-Only Mode Works in openclaw-windows-node Without a Gateway Connection

> Discover how MCP-only mode in openclaw-windows-node operates without a gateway. Learn how it uses a local HTTP server and shared registry for direct system tool invocation.

- Repository: [openclaw/openclaw-windows-node](https://github.com/openclaw/openclaw-windows-node)
- Tags: internals
- Published: 2026-06-05

---

**OpenClaw Windows Node executes in MCP-only mode by hosting a local HTTP server on `127.0.0.1:8765` that reads from a shared capability registry, allowing JSON-RPC requests to invoke system tools directly without establishing a gateway WebSocket connection.**

The `openclaw-windows-node` repository implements a flexible execution model that supports both cloud-connected gateway operation and fully local **MCP-only mode**. When running without a gateway, the tray application exposes all Windows-native capabilities—such as `system.run`, `screen.snapshot`, and `camera.snap`—through a local Model Context Protocol (MCP) endpoint, enabling developers to interact with the node using any MCP-aware client without authentication servers or network tunnels.

## Architecture of the Shared Capability Registry

At the heart of the system lies a **single capability registry** maintained by the `NodeService` class in [`src/OpenClaw.Tray.WinUI/Services/NodeService.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Tray.WinUI/Services/NodeService.cs). This registry, stored in the private field `NodeService._capabilities`, holds all registered tools that implement the `INodeCapability` interface.

During startup, the tray application invokes `NodeService.RegisterCapabilities()` to populate this list once. Because capabilities are registered in a centralized location, the same functional code serves multiple transports without modification. Whether a tool is invoked via the cloud gateway or a local curl request, it executes through the identical implementation in the shared registry.

## Dual Transport: Gateway WebSocket vs. MCP Bridge

The architecture supports two distinct transport mechanisms that read from the same capability list:

- **Gateway WebSocket** – Traditional cloud-connected mode active when `EnableNodeMode` is set to `true`. This maintains a persistent connection to OpenClaw servers.
- **MCP Bridge** – A JSON-RPC dispatcher implemented in [`src/OpenClaw.Shared/Mcp/McpToolBridge.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Shared/Mcp/McpToolBridge.cs) that maps MCP method calls to capability invocations.

When **MCP-only mode** is active (`EnableMcpServer = true` and `EnableNodeMode = false`), the application skips gateway client initialization entirely. Instead, `McpHttpServer`—defined in [`src/OpenClaw.Shared/Mcp/McpHttpServer.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Shared/Mcp/McpHttpServer.cs)—starts a local `HttpListener` bound to port `8765`. Incoming JSON-RPC requests route through the bridge directly to the capability registry, executing tools locally without external network dependencies.

## Security Model and Local Isolation

The MCP HTTP server enforces strict **local-only access** and authentication to prevent unauthorized cross-origin or remote exploitation.

### Network Binding and Token Authentication

The server binds exclusively to `127.0.0.1` (IPv4 loopback), refusing external connections. Every request must include a bearer token in the `Authorization` header. The system generates this token lazily on first startup and persists it to `%APPDATA%\OpenClawTray\mcp-token.txt`, surviving application restarts.

### Defensive Request Validation

Beyond token checking, the implementation in [`McpHttpServer.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/McpHttpServer.cs) applies multiple protective layers:

- **Origin and Host header validation** to block cross-origin scripting attacks
- **Strict Content-Type enforcement** ensuring only `application/json` is accepted
- **Request size limits** preventing memory exhaustion from oversized payloads
- **Concurrency semaphore** limiting in-flight requests to protect system resources

## Enabling and Using MCP-Only Mode

Configuration is controlled through [`src/OpenClaw.Shared/SettingsData.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/src/OpenClaw.Shared/SettingsData.cs), which exposes two key boolean flags that determine the operational mode.

### Configuration Settings

To activate MCP-only mode, set the following in your settings:

```json
{
  "EnableNodeMode": false,
  "EnableMcpServer": true
}

```

When `EnableNodeMode` is `false`, the gateway client is never instantiated. When `EnableMcpServer` is `true`, the tray starts the HTTP listener automatically.

### Listing Available Tools

Retrieve the catalog of registered capabilities using a standard JSON-RPC `tools/list` call:

```powershell
curl -s -X POST http://127.0.0.1:8765/ `
  -H "Authorization: Bearer <token>" `
  -H "Content-Type: application/json" `
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

```

Replace `<token>` with the value stored in `%APPDATA%\OpenClawTray\mcp-token.txt`.

### Invoking Capabilities

Execute any registered tool by calling `tools/call` with the appropriate parameters. For example, capturing a screenshot:

```powershell
curl -s -X POST http://127.0.0.1:8765/ `
  -H "Authorization: Bearer <token>" `
  -H "Content-Type: application/json" `
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"screen.snapshot"}}'

```

### Claude Code Integration

MCP-only mode integrates seamlessly with Claude Code and similar MCP clients. Add the following server configuration to your Claude settings:

```json
{
  "mcpServers": {
    "openclaw-tray": {
      "type": "http",
      "url": "http://127.0.0.1:8765/",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

```

## Summary

- **MCP-only mode** eliminates gateway dependencies by hosting capabilities locally via `McpHttpServer` on `127.0.0.1:8765`.
- The **`NodeService._capabilities`** registry shares tool implementations between WebSocket and MCP transports via the `INodeCapability` interface.
- Security relies on **loopback binding**, **bearer token authentication** stored in `%APPDATA%\OpenClawTray\mcp-token.txt`, and layered request validation.
- Activation requires setting `EnableMcpServer: true` and `EnableNodeMode: false` in `SettingsData`.
- All capabilities remain accessible to MCP clients like Claude Code without code changes, supporting workflows like `system.run`, `screen.snapshot`, and `camera.snap`.

## Frequently Asked Questions

### What is the difference between MCP-only mode and gateway mode in openclaw-windows-node?

Gateway mode maintains a persistent WebSocket connection to OpenClaw servers, routing capability calls through the cloud, while **MCP-only mode** operates entirely offline. In MCP-only mode, the application never initializes the gateway client; instead, `McpHttpServer` handles JSON-RPC requests locally using the same `NodeService._capabilities` registry shared by both modes.

### Where is the authentication token stored for MCP-only mode?

The bearer token is generated automatically on first launch and persisted to `%APPDATA%\OpenClawTray\mcp-token.txt`. This file survives application restarts, and the token must be included in the `Authorization` header for all requests to `http://127.0.0.1:8765/`.

### Can I run both gateway mode and MCP-only mode simultaneously?

Yes, both transports can operate concurrently. When `EnableNodeMode` and `EnableMcpServer` are both set to `true`, the tray registers capabilities once and exposes them simultaneously through the gateway WebSocket and the local MCP HTTP server at port `8765`.

### How does the McpToolBridge handle incoming requests?

[`McpToolBridge.cs`](https://github.com/openclaw/openclaw-windows-node/blob/main/McpToolBridge.cs) implements a JSON-RPC dispatcher that translates MCP method calls—such as `tools/list` and `tools/call`—into invocations of `INodeCapability` implementations. The bridge reads from the shared `NodeService._capabilities` list, ensuring that tools registered via `NodeService.RegisterCapabilities()` are immediately available to MCP clients without transport-specific modifications.