321 lines
6.3 KiB
Markdown
321 lines
6.3 KiB
Markdown
# 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)
|