Docker
Mcp Protocol
Mcp Server

Building a Remote MCP Architecture for Claude Code

Erwan.B

5 min readDec 30, 2025

How to connect Claude Code to a remote Kubernetes cluster using Docker MCP Gateway, SSH tunneling, and intelligent agents ?

The Challenge

Claude Code and Claude Desktop are powerful AI coding assistants, but their Model Context Protocol (MCP) servers typically run locally. What if you want to:

Access a remote Kubernetes cluster from Claude Code
Query vulnerability databases hosted on a VPS
Manage notes in Obsidian while auditing infrastructure
Keep everything secure and production-ready

This guide shows you how to build a hybrid MCP architecture that combines:

Direct SSH access for Kubernetes
Docker MCP Gateway for containerized tools
Persistent systemd services
Intelligent security auditing agents

Architecture Overview

Claude Code (Desktop Client)
    │
    ├─► k8s-vps (SSH direct)
    │       ↓
    │   /usr/local/bin/k8s-mcp → KIND Cluster (23 pods)
    │
    └─► vps-gateway (supergateway proxy)
            ↓
        VPS Debian
            │
            └─ Docker MCP Gateway :9876 (systemd)
                ├─ playwright (browser automation)
                ├─ context7 (code documentation)
                ├─ vuln-nist (CVE scanner)
                ├─ obsidian (knowledge management)
                └─ [+2 more servers]

Key insight: We use two different connection methods:

SSH stdio for the Kubernetes binary (low latency, secure)
HTTP with supergateway for Docker-containerized MCP servers (scalable, isolated)

Part 1: Setting Up Docker MCP Gateway on VPS

Prerequisites

VPS running Debian/Ubuntu
Docker Engine installed (not Docker Desktop)
Docker CLI with MCP plugin

Install Docker MCP Plugin


curl -fsSL https://get.docker.com | sh

The MCP plugin is typically included with modern Docker installations. Verify:

docker mcp --help

Configure MCP Servers

List available servers in the Docker catalog:

docker mcp catalog show docker-mcp

Add the servers you need:

docker mcp server add playwright context7 vuln-nist-mcp-server obsidian

Verify they're enabled:

docker mcp server ls

The biggest gotcha: Every time you restart the gateway, it generates a new Bearer token. This breaks client connections.

Get Erwan.B’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

When you run:

docker mcp gateway run --port 9876 --transport streaming

You'll see:

> Use Bearer token: Authorization: Bearer YOUR TOKEN

This token changes on every restart. You have to change it in the claude.json file at each restart of the gateway.

Solution: Persistent systemd Service

Create a systemd service that keeps the gateway running:

sudo nano /etc/systemd/system/docker-mcp-gateway.service

Content:

[Unit]
Description=Docker MCP Gateway
After=docker.service
Requires=docker.service

[Service]
Type=simple
User=debian
WorkingDirectory=/home/debian
ExecStart=/usr/bin/docker mcp gateway run --port 9876 --transport streaming --servers=playwright,context7,vuln-nist-mcp-server,obsidian,desktop-commander,openbnb-airbnb
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable docker-mcp-gateway
sudo systemctl start docker-mcp-gateway

Check status:

sudo systemctl status docker-mcp-gateway

Part 2: Kubernetes MCP via SSH (Independent Binary)

The Kubernetes MCP server runs as a standalone Go binary, not inside Docker Gateway. This provides:

Lower latency (direct SSH connection)
No HTTP overhead
Native Kubernetes authentication

Install k8s-mcp Binary on VPS

wget https://github.com/strowk/mcp-k8s-go/releases/download/v0.x.x/k8s-mcp
chmod +x k8s-mcp
sudo mv k8s-mcp /usr/local/bin/

Verify it works:

/usr/local/bin/k8s-mcp --read-only --kubeconfig ~/.kube/config

You should see it listing Kubernetes tools available.

Part 3: Claude Code Client Configuration (Desktop)

Install supergateway

supergateway is the magic bridge that converts HTTP-based MCP servers to stdio (which Claude Code understands).

npm install -g supergateway

Configure ~/.claude.json

Edit your Claude Code configuration:

nano ~/.claude.json

Add both MCP servers:

{
  "mcpServers": {
    "k8s-vps": {
      "type": "stdio",
      "command": "ssh",
      "args": [
        "debian@37.59.106.116",
        "/usr/local/bin/k8s-mcp",
        "--read-only",
        "--kubeconfig",
        "/home/debian/.kube/config"
      ],
      "env": {}
    },
    "vps-gateway": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "supergateway",
        "--streamableHttp",
        "http://37.59.106.116:9876/mcp",
        "--outputTransport",
        "stdio",
        "--header",
        "Authorization: Bearer your token"
      ],
      "env": {}
    }
  }
}

Important: Replace the Bearer token with the one from your systemd logs

Test the Connection

claude "List all pods in my Kubernetes cluster"

Test the gateway:

claude "Search for recent CVEs related to Kubernetes"

Part 4: Creating an Intelligent Security Agent

Now for the powerful part: an autonomous agent that combines multiple MCP servers to perform complex tasks.

Agent Architecture

Our cluster-security-auditor agent will:

Inspect the Kubernetes cluster (k8s-vps)
Query the NIST CVE database (vuln-nist)
Document findings in Obsidian (obsidian)

Create the Agent

mkdir -p ~/.claude/agents/cluster-security-auditor
nano ~/.claude/agents/cluster-security-auditor.md

Agent definition (condensed):

# Cluster Security Auditor

You are a Kubernetes security expert that audits clusters for vulnerabilities.

## Available Tools

**k8s-vps**: Kubernetes cluster inspection
- Get K8s version, list pods, inspect components

**vps-gateway → vuln-nist**: CVE database queries  
- search_cves(keyword, last_days)
- get_cve_by_id(cve_id)

**vps-gateway → obsidian**: Documentation
- obsidian_append_content(path, content)

## Workflow

1. **Cluster Reconnaissance** (k8s-vps)
   - Get Kubernetes version
   - List namespaces and pods
   - Identify components (Harbor, ingress-nginx, etc.)

2. **Vulnerability Research** (vuln-nist)
   - Search CVEs for "Kubernetes" (90 days)
   - Search CVEs for each component
   - Retrieve detailed CVE info for critical issues

3. **Impact Analysis**
   - Match CVE versions with cluster versions
   - Categorize by severity (🔴 Critical, ⚠️ High, 🟡 Medium, ✅ Safe)

4. **Report Generation** (obsidian)
   - Create markdown report with:
     - Executive summary
     - Cluster inventory
     - Vulnerability findings
     - Actionable recommendations

## Report Template

```markdown
# Kubernetes Security Audit - [DATE]

## Executive Summary
- Cluster Version: v[X.X.X]
- Risk Level: [CRITICAL/HIGH/MEDIUM/LOW]

## Cluster Inventory
| Component | Version | Status |

## Vulnerability Findings

### 🔴 Critical
[CVE details with recommendations]

### ⚠️ High Severity
[CVE details with recommendations]

## Recommendations
1. Immediate actions
2. Short-term remediation
3. Long-term improvements