# Centralized MCP Servers for Homelab

## Current State of MCP Remote Access

**The Problem**: Most MCP servers use `stdio` transport (local process communication).
Claude Code clients expect to spawn local processes.

**The Solution**: Use `mcp-remote` to bridge local clients to remote servers.

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    docker-host (10.10.10.206)                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ airtable-mcp│  │   exa-mcp   │  │ ticktick-mcp│   ...       │
│  │  :3001/sse  │  │  :3002/sse  │  │  :3003/sse  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘
              ▲               ▲               ▲
              │               │               │
       ┌──────┴───────────────┴───────────────┴──────┐
       │              Tailscale / LAN                │
       └──────┬───────────────┬───────────────┬──────┘
              │               │               │
    ┌─────────▼─────┐ ┌───────▼───────┐ ┌─────▼─────────┐
    │   MacBook     │ │   Mac Mini    │ │  Windows PC   │
    │ Claude Code   │ │ Claude Code   │ │ Claude Code   │
    │  mcp-remote   │ │  mcp-remote   │ │  mcp-remote   │
    └───────────────┘ └───────────────┘ └───────────────┘
```

## Setup

### Step 1: Deploy MCP Servers on docker-host

```bash
ssh hutson@10.10.10.206
cd /opt/mcp-central
docker-compose up -d
```

### Step 2: Configure Claude Code Clients

Each device needs `mcp-remote` installed and configured.

**Install mcp-remote:**
```bash
npm install -g mcp-remote
```

**Update ~/.claude/settings.json:**
```json
{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["mcp-remote", "http://10.10.10.206:3001/sse"]
    },
    "exa": {
      "command": "npx",
      "args": ["mcp-remote", "http://10.10.10.206:3002/sse"]
    },
    "ticktick": {
      "command": "npx",
      "args": ["mcp-remote", "http://10.10.10.206:3003/sse"]
    }
  }
}
```

**For remote access via Tailscale, use Tailscale IP:**
```json
{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["mcp-remote", "http://100.x.x.x:3001/sse"]
    }
  }
}
```

## Which Servers Can Be Centralized?

| Server | Centralizable | Notes |
|--------|--------------|-------|
| Airtable | Yes | Just needs API key |
| Exa | Yes | Just needs API key |
| TickTick | Yes | OAuth token stored server-side |
| Slack | Yes | Bot token stored server-side |
| Ref | Yes | API key only |
| Beeper | No | Needs local Beeper Desktop |
| Google Sheets | Partial | OAuth flow needs user interaction |
| Monarch Money | Partial | Credentials stored server-side |

## Alternative: Shared Config File

If full centralization is too complex, you can at least share the config:

1. Store `settings.json` in a synced folder (e.g., Syncthing `configs/`)
2. Symlink from each device:
   ```bash
   ln -s ~/Sync/configs/claude-settings.json ~/.claude/settings.json
   ```

This doesn't centralize the servers, but ensures all devices have the same config.

## Traefik Integration (Optional)

Add to Traefik for HTTPS access:

```yaml
# /etc/traefik/conf.d/mcp.yaml
http:
  routers:
    mcp-airtable:
      rule: "Host(`mcp-airtable.htsn.io`)"
      service: mcp-airtable
      tls:
        certResolver: cloudflare
  services:
    mcp-airtable:
      loadBalancer:
        servers:
          - url: "http://10.10.10.206:3001"
```

Then use: `http://mcp-airtable.htsn.io/sse` in your config.