MCP Feature

Introduction

The MCP feature on NanoKVM Cube lets MCP-compatible AI tools connect to NanoKVM Cube, so the AI tool can view and control the target device through NanoKVM Cube.

After the connection is configured, the AI tool can use the target device screen content to assist with clicking, typing, opening applications, changing settings, troubleshooting issues, and performing repetitive operations. This feature is useful for remote maintenance, system configuration, troubleshooting, and assisted automation.

The MCP feature gives the AI tool the ability to operate the target device. Use trusted AI tools only, and do not expose the MCP service on untrusted networks.

How It Works

After MCP is enabled on NanoKVM Cube, the AI tool on the control device connects to the MCP service using the Endpoint and API Key shown on the NanoKVM Cube page. The AI tool does not connect to the target device directly. Instead, it gets screen content and sends control operations through NanoKVM Cube.

The connection flow is:

AI tool on the control device
        |
        | MCP
        v
NanoKVM Cube
        |
        | KVM control
        v
Target device

In this flow:

• The target device sends video to NanoKVM Cube through HDMI and receives keyboard and mouse control through the PC USB (HID) interface;
• NanoKVM Cube captures the target device screen and sends keyboard and mouse operations to the target device;
• The AI tool on the control device connects to NanoKVM Cube through MCP;
• After the user sends an instruction in the AI tool, the AI tool controls the target device through NanoKVM Cube.

Preparation

Before using MCP, make sure that:

• NanoKVM Cube is connected to the target device;
• The NanoKVM Cube web control page can display the target device screen correctly;
• NanoKVM Cube is connected to the network and has obtained an IP address;
• The control device can access the MCP endpoint shown by NanoKVM Cube;
• The control device has an MCP-compatible AI tool installed, such as OpenCode or another MCP client;
• The NanoKVM Cube system and application versions support MCP.

If the MCP option is not shown, check whether the NanoKVM Cube system and application have been updated to a version that supports MCP.

Enable MCP

1. Connect NanoKVM Cube to the target device and confirm that the target device screen is displayed correctly.
2. Enter the NanoKVM Cube IP address in a browser to open the NanoKVM Cube web control page.
3. Log in to NanoKVM Cube.
4. Open the settings page.

5. Find the MCP option.

6. Turn on the MCP switch.
7. Record the Endpoint and API Key shown on the page.

Add MCP to an AI Tool

Different AI tools use different MCP configuration methods. This section uses OpenCode as an example.

Get the Endpoint and API Key

After MCP is enabled on NanoKVM Cube, the page shows an Endpoint and an API Key.

In this section:

• Endpoint is the full URL of the NanoKVM Cube MCP server, for example http://<NanoKVM-IP>/api/mcp or https://<NanoKVM-IP>/api/mcp;
• API Key is the credential used to access the NanoKVM Cube MCP server.

When configuring an AI tool, copy the endpoint shown on the page directly. Do not split the IP address and port or change the protocol.

Add MCP to OpenCode

OpenCode supports adding a remote MCP server through the global configuration file.

Create or edit the following configuration file:

~/.config/opencode/opencode.json

Configuration example:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "nanokvm": {
      "type": "remote",
      "url": "<Endpoint>",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer <API-Key>"
      }
    }
  }
}

Replace:

• <Endpoint> with the Endpoint shown on the NanoKVM Cube MCP page;
• <API-Key> with the API Key shown on the NanoKVM Cube MCP page.

The displayed endpoint may start with HTTP or HTTPS. Enter it exactly as shown. Use MCP only on a trusted LAN, and prefer HTTPS whenever possible.

If the endpoint starts with HTTPS and OpenCode cannot connect because of the local NanoKVM Cube certificate, set the following environment variable before starting OpenCode on Linux:

export NODE_TLS_REJECT_UNAUTHORIZED=0
opencode

You can also start OpenCode with a single command:

NODE_TLS_REJECT_UNAUTHORIZED=0 opencode

The NODE_TLS_REJECT_UNAUTHORIZED environment variable disables TLS certificate verification for the current OpenCode process. Use it only when connecting to NanoKVM Cube MCP on a trusted LAN. Do not use it long term on untrusted networks.

After saving the configuration, restart OpenCode. Then check whether the MCP server is connected:

opencode mcp list

If an HTTPS endpoint produces a local certificate verification error, use:

NODE_TLS_REJECT_UNAUTHORIZED=0 opencode mcp list

If nanokvm is shown as connected, OpenCode has successfully connected to NanoKVM Cube MCP.

After the connection succeeds, you can send an instruction to OpenCode and let OpenCode view and control the target device through NanoKVM Cube MCP.

To restore the default security behavior, close the current terminal and open a new one. You can also run:

unset NODE_TLS_REJECT_UNAUTHORIZED

Other AI Tools

Other MCP-compatible AI tools can also try connecting to NanoKVM Cube MCP. Support for remote MCP, HTTPS, and tool-call permissions varies between tools and versions.

If an AI tool cannot handle the certificate used by an HTTPS endpoint, a reverse proxy such as Nginx may be required to handle certificates. This setup is more complex and is not recommended as the first choice for general users.

Usage Examples

After the connection succeeds, you can describe the operation you want to perform in natural language. For example:

Use NanoKVM Cube to check the current screen and tell me which page the target device is on.

Use NanoKVM Cube to click the Settings button on the screen.

Use NanoKVM Cube to open a terminal and type ifconfig to check the network information.

Use NanoKVM Cube to continue the system installation process based on the current screen.

Start with simple and easy-to-confirm operations, such as reading the screen, clicking a clear button, or typing a short command. For high-risk operations such as deleting files, formatting disks, or changing system configuration, confirm the action before allowing the AI tool to proceed.

FAQ

The AI Tool Cannot Connect to NanoKVM Cube MCP

Check:

• Whether the NanoKVM Cube MCP switch is turned on;
• Whether the MCP endpoint is correct;
• Whether the API Key is correct;
• Whether the control device and NanoKVM Cube can reach each other over the network;
• When using an HTTPS endpoint, whether the AI tool can handle the local NanoKVM Cube certificate;
• Whether a firewall, router, VPN, or security software is blocking the connection;
• Whether NanoKVM Cube is connected to the network and shows an IP address.

The AI Tool Can Connect to MCP, but Cannot Control the Target Device

Check:

• Whether the NanoKVM Cube web control page can display the target device screen correctly;
• Whether the target device is connected to NanoKVM Cube correctly;
• Whether the current target device screen requires unlocking, login, or manual confirmation;
• Whether the AI tool allows MCP tool calls;
• Whether keyboard and mouse control works normally in NanoKVM Cube.

The MCP Switch Is Not Shown

Check:

• Whether the NanoKVM Cube system or application version is too old;
• Whether the current version supports MCP;
• Whether the KVM App needs to be updated from the web control page;
• Whether the settings page has been reopened after the update.

Security Notes

• MCP gives the AI tool the ability to operate the target device. Connect only trusted AI tools;
• Do not expose the MCP service directly to the public Internet;
• Do not expose the MCP endpoint on untrusted networks;
• Turn off MCP when it is not needed;
• Confirm the AI tool's action before operating important devices;
• Do not leak the NanoKVM Cube MCP API Key;
• When entering passwords, keys, tokens, or other sensitive information, make sure the AI tool and network environment are trusted.