AI interface (MCP)

Node64 speaks the Model Context Protocol (MCP). AI applications such as Claude Code, Cursor or VS Code query your node's state via /mcp and explain how things fit together – for example “Why was the website down last night?”, “What did the honeypot see this week?” or “Which certificates expire soon?”.

What is MCP?

MCP is an open protocol (JSON-RPC 2.0) that lets an AI application call a server's “tools”. Node64 is the server: it describes its tools with name, purpose and parameters, the application decides which to call and gets compact JSON answers.

The transport is “Streamable HTTP” on the node's web port – no extra port, the same TLS certificate as the UI. Node64 works without sessions and answers as JSON.

Security

• Off by default. When switched off, /mcp answers 404.
• Home network only. Allowed are private networks (RFC 1918, fc00::/7), link-local (fe80::/10), 100.64.0.0/10 (e.g. Tailscale) and localhost. Everything else gets 403 – also via PROXY64 or another reverse proxy: if X-Forwarded-For, X-Real-IP or Forwarded contains a public address, the request is rejected. These headers can only block access, never open it. Via PROXY64 a private client address must be forwarded.
• Separate MCP keys (mcp64_…), independent of the API keys: node64_… does not work here, mcp64_… does not work for /api. Each key has a name, permissions per area, last use and address, and can be revoked at any time. Only the hash is stored; the key is only visible right after creating it. Wrong keys slow the address down. Session cookies don't count for /mcp.
• Rate limit: 60 requests per minute per key, beyond that 429 with Retry-After.
• Same rules as the API. Every tool calls the existing JSON API internally, signed in as the key's owner. Tools only appear if their module is running and the key may read that area.
• Never secrets. The tools pick their fields explicitly: no API keys, tokens, passwords, private keys, channel credentials, PROXY64 header values, check parameters or push URLs. A central filter additionally strips URLs down to scheme and host, token=… and key=… values, Bearer …, keys, PEM blocks and long random strings from all texts.
• Third-party data is marked. Much of the data is written by others: users, passwords and paths from the honeypot, domain names in the DNS64 log, user agents from PROXY64, VM names from Proxmox, actors in the audit log, HTTP methods from the access log and error texts from remote services, channels and the ipv64 link. They are kept shortened and cleaned in a sub-object untrusted, and the tool descriptions tell the AI never to treat this content as instructions.
• Audit: every tool call is recorded in the audit log (area AI (MCP), action mcp.call) with tool, key, user, address, shortened parameters and result. The same goes for switching the interface and creating or revoking keys. The entries follow the audit log retention (default 365 days).
• Moving: the switch moves with the configuration export and import, MCP keys never do – not even in an export with a password.

Setup

1. Switch on
   Under Settings → AI interface (MCP) click Switch on.
2. Create a key
   A name, for example “Claude Code laptop”, and the areas it may read: node, health checks, Proxmox VE, DNS64, PROXY64, Honeypot64, DynDNS, certificates, notifications, audit log and logs.
3. Connect your application
   The page shows the address https://<node>:<port>/mcp and ready-made snippets with the new key for the applications below.

Certificate

Without further setup Node64 uses a self-signed certificate. Applications based on Node.js (Claude Code, mcp-remote) reject it. You have three options:

• Download the node's certificate (Settings → General → Reachability of this node) and set NODE_EXTRA_CA_CERTS=/path/node64.pem before starting the application.
• Pick a certificate from certificate management for the UI (Settings → General → Reachability of this node) and address the node by that name.
• In the LAN http://<node>:<port>/mcp works too – HTTP and HTTPS run on the same port. The key then travels unencrypted through your home network.

Claude Code

claude mcp add --transport http node64 https://node64.lan:8080/mcp --header "Authorization: Bearer mcp64_…"

With --scope user the server applies to all projects. Check the connection with claude mcp list or /mcp in Claude Code.

Cursor

~/.cursor/mcp.json for all projects or .cursor/mcp.json in the project:

{
  "mcpServers": {
    "node64": {
      "url": "https://node64.lan:8080/mcp",
      "headers": { "Authorization": "Bearer mcp64_…" }
    }
  }
}

VS Code (GitHub Copilot, agent mode)

.vscode/mcp.json in the project or via MCP: Open User Configuration:

{
  "servers": {
    "node64": {
      "type": "http",
      "url": "https://node64.lan:8080/mcp",
      "headers": { "Authorization": "Bearer mcp64_…" }
    }
  }
}

To keep the key out of the file, VS Code can prompt for it: "inputs": [{"type": "promptString", "id": "node64-key", "description": "Node64 MCP key", "password": true}] and in the header "Authorization": "Bearer ${input:node64-key}".

Claude Desktop

Claude Desktop adds remote servers as “connectors”. The connection is then made from Anthropic's cloud and cannot reach a node in your home network. That's why it goes through the local bridge mcp-remote (needs Node.js), configured in claude_desktop_config.json (Settings → Developer → Edit config):

{
  "mcpServers": {
    "node64": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://node64.lan:8080/mcp", "--header", "Authorization:${NODE64_AUTH}"],
      "env": { "NODE64_AUTH": "Bearer mcp64_…" }
    }
  }
}

The key goes into env because spaces in args cause problems on Windows. For a self-signed certificate also add "NODE_EXTRA_CA_CERTS": "C:\\path\\node64.pem" to env; for http://, mcp-remote needs the --allow-http switch.

claude.ai and ChatGPT in the browser

These applications call MCP servers from their cloud. That would require the node to be publicly reachable and to support OAuth – which is deliberately not planned yet.

Tools

All tools are read-only (readOnlyHint: true, destructiveHint: false). Times are RFC 3339 in UTC.

Prompts

Prompts only mention tools the key actually has.

Limits

• Read-only. Tools that change things, such as “pause check” or a DNS64 allow entry, will follow later, one by one and off by default.
• Never via MCP: keys, users, login, backup, export and import, linking with ipv64, reset, updates.
• Results are limited (limit, periods); large lists are cut (truncated, next_before).
• No OAuth, no public access.

Errors

Tool errors, such as “check not found” or a stopped module, come back as a tool result with isError.

Prometheus

node64_mcp_enabled (1/0) and node64_mcp_calls_total{tool,result} with result = ok or error – see Prometheus & Grafana.

Something unclear, missing, or a question about Node64? Ask in the official forum v64.tech.