+320
@@ -0,0 +1,320 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user