finn-mcp/DEPLOYMENT.md

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

# 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):

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

3. Test the Connection

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

Should return:

{"status": "ok", "service": "finn-mcp-http"}

Docker Compose Deployment

# 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

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:

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

Caddy Configuration

your-domain.com {
    reverse_proxy localhost:8010
}

Configuration Options

Environment Variables

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

# 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:

environment:
  FINN_RATE_LIMIT_DELAY: 0.5
  HTTP_TIMEOUT: 30

Monitoring

Check Container Status

# 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

# 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

   # 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

   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

   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"

# 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"

# 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:

   docker update --memory 2g --cpus 2 finn-mcp-server
   

2. Add caching layer (already built-in):

   # View cache stats
   docker exec finn-mcp-server finn-eiendom cache stats
   

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

Updating

# 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
• README
• Implementation Details