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

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. 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 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—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 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, which exposes two key boolean flags that determine the operational mode.

Configuration Settings

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

{
  "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:

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:

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:

{
  "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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}