Perplexica MCP v0.3.6 Self-Hosted Deployment: A Production-Grade 2026 Guide

Executive Summary & Architecture Overview

Perplexica MCP (v0.3.6) is a Model Context Protocol (MCP) server that exposes a search and research API to AI assistants like Claude, ChatGPT, or any MCP-compatible client. Instead of relying on commercial SaaS search aggregators, self-hosting Perplexica MCP gives you complete control over your search queries, provider credentials, and data flow. By running it inside your own network, you eliminate third-party data mining, reduce latency, and ensure that your search history never leaves your infrastructure.

This guide walks you through a production-grade deployment on a Linux homelab server. You will prepare the host, write a modern Docker Compose file (no obsolete version key), deploy with docker compose up -d, secure it with Caddy as a reverse proxy, enable zero-trust remote access via Tailscale, and implement an automated backup strategy. We also provide a deep troubleshooting matrix for common pitfalls and answer veteran-level FAQs.

Architecture Flow:

1. MCP Client (e.g., Claude Desktop, Continue, or custom app) sends a JSON-RPC request over HTTP.
2. Caddy (or your reverse proxy) terminates TLS, forwards headers, and proxies to the Perplexica MCP container on port 3001.
3. Perplexica MCP receives the request, resolves the provider (e.g., SearXNG, Tavily, or custom) via its internal API, and returns structured results.
4. Backup cron runs nightly, stopping the container, dumping any local state, and compressing to an offsite disk.
5. Tailscale provides encrypted overlay network access for remote management without exposing public ports.

All components are isolated on a custom Docker bridge network, with healthchecks to ensure rapid failure detection.

Hardware, OS & Network Requirements

Ports:

• Inbound (public): 443 (HTTPS) if you expose via reverse proxy; none if you rely solely on Tailscale.
• Internal: 3001 (Perplexica MCP), 8080 (optional for Caddy HTTP), 22 (SSH for management).

Step 1: Host Preparation & Directory Layout

We'll use a standard homelab layout under /opt/perplexica-mcp. This keeps the application isolated and easy to back up.

# Create the base directory and subdirectories
sudo mkdir -p /opt/perplexica-mcp/{data,backups}

# Set ownership to your user (replace 'youruser' with your actual username)
sudo chown -R youruser:youruser /opt/perplexica-mcp

# Navigate to the project directory
cd /opt/perplexica-mcp

Now create the .env file that will hold all secrets and configuration. Use openssl to generate strong random values:

# Generate a random API key for internal use (if needed)
openssl rand -hex 32

# Generate a random secret for session or JWT (if applicable)
openssl rand -hex 32

Create the file with your editor:

nano /opt/perplexica-mcp/.env

Paste the following (replace placeholders with your generated values):

# Perplexica MCP Configuration
# Provider name (e.g., 'searxng' or 'tavily') - must match a configured provider
PERPLEXICA_PROVIDER=searxng

# Optional: Provider API key if your provider requires one (e.g., Tavily)
PERPLEXICA_API_KEY=your_generated_hex_key_here

# Host binding for the FastMCP server
HOST=0.0.0.0
PORT=3001

# Logging level (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

Note: The container image thetom42/perplexica-mcp:latest (as of 2026-09-05) reads these environment variables. For a complete list, refer to the official repository documentation, but the above covers the essentials.

Step 2: Production-Grade docker compose.yaml

We'll write a docker-compose.yml using the modern Compose Spec (no top-level version key). The service uses a custom bridge network, a named volume for persistent data, and a healthcheck that sends an MCP initialize request.

Create the file:

nano /opt/perplexica-mcp/docker-compose.yml

Paste the following:

services:
  perplexica-mcp:
    image: thetom42/perplexica-mcp:latest
    container_name: perplexica-mcp
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "127.0.0.1:3001:3001"   # Bind to loopback only; reverse proxy will access it
    volumes:
      - perplexica-data:/app/data   # Persistent storage for any local state
    command: python src/perplexica_mcp/server.py http
    networks:
      - perplexica-network
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request, json; req = urllib.request.Request('http://localhost:3001/mcp', data=json.dumps({'jsonrpc': '2.0', 'method': 'initialize', 'params': {'protocolVersion': '2024-11-05', 'capabilities': {}, 'clientInfo': {'name': 'healthcheck', 'version': '1.0.0'}}, 'id': 1}).encode(), headers={'Content-Type': 'application/json'}); resp = urllib.request.urlopen(req, timeout=5); json.load(resp)"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s
    security_opt:
      - no-new-privileges:true
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

networks:
  perplexica-network:
    driver: bridge
    name: perplexica-network

volumes:
  perplexica-data:
    name: perplexica-data

Explanation of key choices:

• image: thetom42/perplexica-mcp:latest: Uses the verified container from the official repository. In production, consider pinning to a specific digest for reproducibility.
• ports: "127.0.0.1:3001:3001": Binds only to the loopback interface. This prevents direct external access and forces traffic through your reverse proxy, which is a security best practice.
• command: Explicitly starts the Streamable HTTP transport, matching the official snippet.
• healthcheck: Sends a real MCP initialize request to the endpoint, ensuring the server is truly functional, not just the process alive.
• security_opt: no-new-privileges:true: Hardens the container against privilege escalation.
• logging: Limits log size to prevent disk exhaustion.

Step 3: Deployment & Health Verification

With the configuration in place, deploy the stack:

cd /opt/perplexica-mcp

# Pull the image and start the container in the background
docker compose up -d

# Check the status
docker compose ps

You should see perplexica-mcp with status Up and health healthy after the start period. To monitor logs in real time:

docker compose logs -f

Look for lines like Uvicorn running on http://0.0.0.0:3001 to confirm the server started correctly.

Initial Onboarding: Since Perplexica MCP is an API server, there is no web setup wizard. Instead, you configure providers via environment variables or by editing a configuration file inside the container. For v0.3.6, the provider ID resolution fix means you can use provider names (e.g., searxng) directly in your MCP client configuration. To test the endpoint manually, run:

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}},"id":1}'

If you receive a JSON-RPC response with serverInfo, the server is operational.

Step 4: Reverse Proxy, Domain & SSL Hardening

To expose Perplexica MCP securely to the internet (or your LAN), use Caddy as a reverse proxy. Caddy automatically obtains and renews Let's Encrypt certificates. We'll bind the container to loopback only, as shown above, and configure Caddy to forward requests.

Install Caddy (if not already installed) and create a Caddyfile:

# Install Caddy (Debian/Ubuntu)
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Create the Caddyfile:

sudo nano /etc/caddy/Caddyfile

Add the following (replace perplexica.example.com with your actual domain):

perplexica.example.com {
    reverse_proxy 127.0.0.1:3001 {
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
        header_up Host {host}
    }
    encode zstd gzip
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
    }
}

WebSocket Support: Although MCP over HTTP is not WebSocket-based, the Streamable HTTP transport may use SSE (Server-Sent Events). Caddy handles SSE transparently with the above configuration. No special Upgrade header is needed for SSE, but if you later switch to WebSocket transport, add:

# Inside the reverse_proxy block, add:
header_up Connection {http.request.header.Connection}
header_up Upgrade {http.request.header.Upgrade}

Reload Caddy:

sudo systemctl reload caddy

Now your Perplexica MCP is accessible at https://perplexica.example.com with automatic HTTPS.

Step 5: Zero-Trust Remote Access with Tailscale

For remote administration without exposing any public ports, use Tailscale. This is a zero-trust overlay network that encrypts traffic between your devices.

Setup on your host:

# Install Tailscale (Debian/Ubuntu)
curl -fsSL https://tailscale.com/install.sh | sh

# Start Tailscale and authenticate
sudo tailscale up

Follow the URL printed to authenticate your device. Once connected, note the Tailscale IP address (e.g., 100.x.y.z).

Access from your laptop or phone: Install the Tailscale client on your device, sign in to the same account, and you can reach the server via http://100.x.y.z:3001 (or better, via the internal reverse proxy if you set up a Tailscale serve). To avoid exposing the port on the public internet, ensure your Caddy bind is on 127.0.0.1 only, which we already did.

Alternative: Tailscale Serve

You can also use tailscale serve to proxy to your Caddy instance:

sudo tailscale serve --bg https / https://127.0.0.1

This creates a https://your-machine.tailnet.ts.net endpoint that routes to your local Caddy, giving you a valid TLS certificate without opening any firewall ports.

Step 6: Automated Backup & Disaster Recovery

Backups are critical. We'll create a script that stops the container, snapshots the named volume, and compresses it to an offsite disk using tar. For a more robust solution, you could use Restic, but here we use tar for simplicity and universality.

Create the backup script:

nano /opt/perplexica-mcp/backup.sh

Paste the following:

#!/bin/bash

# Backup script for Perplexica MCP
# Run as root or with sudo

set -euo pipefail

# Configuration
BACKUP_DIR="/opt/perplexica-mcp/backups"
CONTAINER_NAME="perplexica-mcp"
VOLUME_NAME="perplexica-data"
RETENTION_DAYS=7

# Timestamp
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
BACKUP_FILE="${BACKUP_DIR}/perplexica_${TIMESTAMP}.tar.gz"

# Create backup directory if it doesn't exist
mkdir -p "${BACKUP_DIR}"

# Stop the container to ensure consistent state
echo "Stopping container ${CONTAINER_NAME}..."
docker stop "${CONTAINER_NAME}"

# Backup the volume using a temporary container
echo "Backing up volume ${VOLUME_NAME}..."
docker run --rm \
  -v "${VOLUME_NAME}:/data:ro" \
  -v "${BACKUP_DIR}:/backup" \
  alpine tar czf "/backup/perplexica_${TIMESTAMP}.tar.gz" -C /data .

# Restart the container
echo "Starting container ${CONTAINER_NAME}..."
docker start "${CONTAINER_NAME}"

# Remove backups older than RETENTION_DAYS
find "${BACKUP_DIR}" -name "perplexica_*.tar.gz" -type f -mtime "+${RETENTION_DAYS}" -delete

echo "Backup completed: ${BACKUP_FILE}"

Make it executable and test it:

chmod +x /opt/perplexica-mcp/backup.sh
sudo /opt/perplexica-mcp/backup.sh

Automate with cron:

sudo crontab -e

Add the following line to run nightly at 2 AM:

0 2 * * * /opt/perplexica-mcp/backup.sh >> /var/log/perplexica-backup.log 2>&1

Disaster Recovery: To restore from a backup, stop the container, restore the volume contents, and restart:

# Stop the container
docker stop perplexica-mcp

# Restore from a specific backup file (replace with actual file)
docker run --rm \
  -v perplexica-data:/data \
  -v /opt/perplexica-mcp/backups:/backup \
  alpine sh -c "tar xzf /backup/perplexica_YYYYMMDD_HHMMSS.tar.gz -C /data"

# Start the container
docker start perplexica-mcp

Step 7: Deep Troubleshooting Matrix

Step 8: Frequently Asked Questions (FAQ)

Q1: Should I pin the image to a specific version instead of using latest?

Absolutely. In production, you should pin to a specific digest or tag like thetom42/perplexica-mcp:v0.3.6 to ensure reproducibility. Using latest can break your deployment when a new version is pushed. However, for a homelab, you might prefer latest to receive fixes automatically. If you do, consider using Watchtower to automate updates, but always test in a staging environment first.

Q2: How do I configure multiple search providers (e.g., SearXNG and Tavily)?

The server supports multiple providers via its internal configuration. You can set up a config.json inside the container or use environment variables for each provider. In v0.3.6, the provider ID resolution fix allows you to refer to providers by name, making configuration easier. Refer to the official repository's documentation for the full schema.

Q3: Can I run this behind Nginx Proxy Manager instead of Caddy?

Yes. Create a proxy host and set the forward host to 127.0.0.1:3001. Enable WebSocket support (even though it's not required, it doesn't hurt). Add the following custom headers: X-Forwarded-For, X-Forwarded-Proto, and Host. Nginx Proxy Manager will handle SSL certificates.

Q4: What is the best way to monitor resource usage?

Use docker stats for real-time metrics. For historical data, deploy Prometheus with the cAdvisor exporter and Grafana dashboards. Since Perplexica MCP is lightweight, you can also set up a simple cron job that logs docker stats --no-stream to a file.

Q5: How do I migrate to a new host?

1. On the old host, run docker compose down to stop the container.
2. Back up the entire /opt/perplexica-mcp directory (including .env and backups).
3. Transfer the directory to the new host using rsync or scp.
4. On the new host, run docker compose up -d.
5. If the volume data was included in the backup, restore it as described in the backup section.

Q6: Does Perplexica MCP support GPU acceleration?

No, Perplexica MCP is a lightweight API server that aggregates search results from external providers. It does not run local AI models, so GPU acceleration is unnecessary. If you later integrate a local LLM, you would need to run a separate service with GPU support.

Q7: How do I update to a new version?

cd /opt/perplexica-mcp
docker compose pull
docker compose up -d

Always review the release notes for breaking changes. For v0.3.6, the main fix was provider ID resolution, which is backward-compatible.

Conclusion

You now have a production-grade Perplexica MCP deployment that is secure, remotely accessible, and backed up. By following this guide, you've eliminated dependency on commercial search APIs, maintained data ownership, and implemented best practices for containerized applications. For further enhancements, consider adding a monitoring stack or centralizing logs with Loki. Stay tuned to Play5afe.com for more advanced homelab guides.

Last updated: 2026-09-05