# Deployment Guide

This guide covers deploying the FINN-Eiendom MCP server on a remote server for use with any chat service (Claude Desktop, GitHub Copilot, etc.).

## Overview

The MCP server runs as an **HTTP service** on port 8010. This makes it agnostic to any client - any chat service can send JSON-RPC requests to the HTTP endpoint.

## Architecture

```
Local Client (Claude Desktop/Copilot/etc)
    ↓ HTTP JSON-RPC
Remote Server (HTTP API)
    ↓ 
Docker Container (HTTP Server)
    ↓ subprocess stdin/stdout
MCP stdio server
    ↓ 
Service Functions
    ↓
FINN / Eiendom.no APIs
```

## Prerequisites

- Remote server with Docker and Docker Compose installed
- Port 8010 open (or configure with reverse proxy)
- Domain/IP address accessible to your clients

## Quick Start: Docker Compose

### 1. Deploy on Remote Server

```bash
# SSH into remote server
ssh user@your-remote-server.com

# Clone the repository
git clone https://github.com/yourusername/finn-mcp.git
cd finn-mcp

# Start with docker-compose
docker-compose up -d
```

The MCP HTTP server will be available at `http://your-remote-server.com:8010`

### 2. Configure Claude Desktop

Edit `~/.config/claude-desktop/claude.json` (Mac/Linux) or `%APPDATA%\Claude\claude.json` (Windows):

```json
{
  "mcpServers": {
    "finn-eiendom": {
      "type": "http",
      "url": "http://your-remote-server.com:8010"
    }
  }
}
```

### 3. Test the Connection

```bash
# From your local machine
curl -X POST http://your-remote-server.com:8010/health
```

Should return:
```json
{"status": "ok", "service": "finn-mcp-http"}
```

## Docker Compose Deployment

```bash
# Build and start
docker-compose up -d

# View logs
docker-compose logs -f mcp-server

# Stop
docker-compose down
```

## Production Setup with Reverse Proxy

For security and domain management, use a reverse proxy (Nginx/Caddy):

### Nginx Configuration

```nginx
upstream mcp {
    server localhost:8010;
}

server {
    listen 80;
    server_name your-domain.com;

    # Redirect HTTP to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://mcp;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Enable larger uploads if needed
        client_max_body_size 10M;
    }
}
```

Then configure Claude Desktop with HTTPS:

```json
{
  "mcpServers": {
    "finn-eiendom": {
      "type": "http",
      "url": "https://your-domain.com"
    }
  }
}
```

### Caddy Configuration

```caddy
your-domain.com {
    reverse_proxy localhost:8010
}
```

## Configuration Options

### Environment Variables

Set these in your `docker run` command or `docker-compose.yml`:

```bash
# Performance tuning
FINN_RATE_LIMIT_DELAY=0.5      # Delay between FINN requests (seconds)
HTTP_TIMEOUT=30                 # HTTP request timeout
HTTP_MAX_RETRIES=3              # Max retry attempts
```

Example with docker-compose:

```yaml
environment:
  FINN_RATE_LIMIT_DELAY: 0.5
  HTTP_TIMEOUT: 30
```

## Monitoring

### Check Container Status

```bash
# On remote server
docker ps --filter "name=finn-mcp"

# View logs
docker logs -f finn-mcp-server

# Check health
curl http://localhost:8010/health
```

### Test API Endpoint

```bash
# Health check
curl http://your-remote-server.com:8010/health

# Query a tool (example)
curl -X POST http://your-remote-server.com:8010 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'
```

## Security Considerations

1. **Use HTTPS**: Always use a reverse proxy with SSL/TLS
   - Never expose HTTP directly on the internet
   - Use Let's Encrypt for free certificates

2. **Firewall**: Restrict port 8010 access
   ```bash
   # Only allow from localhost (reverse proxy will forward)
   # In docker-compose, map to localhost only:
   ports:
     - "127.0.0.1:8010:8010"
   ```

3. **Rate Limiting**: Set up rate limiting on reverse proxy
   ```nginx
   limit_req_zone $binary_remote_addr zone=mcp:10m rate=10r/s;
   
   location / {
       limit_req zone=mcp burst=20;
       proxy_pass http://mcp;
   }
   ```

4. **Authentication** (Optional): Add API key validation
   ```nginx
   location / {
       if ($http_x_api_key != "your-secret-key") {
           return 401;
       }
       proxy_pass http://mcp;
   }
   ```

5. **Container Security**:
   - Don't run container as root
   - Use read-only filesystems where possible
   - Set resource limits

## Troubleshooting

### "Connection refused"

```bash
# Check if container is running
docker ps | grep finn-mcp

# Start container
docker-compose up -d

# Check logs for startup errors
docker logs finn-mcp-server
```

### "Unable to connect to HTTP endpoint"

```bash
# Verify port is open on remote server
netstat -tlnp | grep 8010

# Verify reverse proxy configuration (if using)
curl -v http://localhost:8010/health

# Check firewall rules
ufw status
ufw allow 8010  # If needed
```

### "502 Bad Gateway" from reverse proxy

1. Check MCP container is running: `docker ps`
2. Verify health endpoint: `docker exec finn-mcp-server curl http://localhost:8010/health`
3. Check container logs: `docker logs finn-mcp-server`
4. Verify resource limits aren't exceeded: `docker stats finn-mcp-server`

### "Request timeout" from Claude Desktop

1. Verify connection: `curl -v http://your-domain:8010/health`
2. Check network latency: `ping your-domain`
3. Increase timeout in reverse proxy config
4. Check CPU/memory usage: `docker stats`

## Scaling

For multiple clients or high load:

1. **Increase container resources**:
   ```bash
   docker update --memory 2g --cpus 2 finn-mcp-server
   ```

2. **Add caching layer** (already built-in):
   ```bash
   # View cache stats
   docker exec finn-mcp-server finn-eiendom cache stats
   ```

3. **Load balancing**: Run multiple containers with different cache databases

## Updating

```bash
# Pull latest code
git pull

# Rebuild image
docker build -t finn-mcp:latest .

# Restart container
docker-compose down
docker-compose up -d
```

## Next Steps

- [Usage Guide](USAGE.md)
- [README](README.md)
- [Implementation Details](IMPLEMENTATION.md)