ragifix-mcp

MCP server (Model Context Protocol, Streamable HTTP transport) that exposes a ragifix database to a compatible chat client (search, addition, deletion, and listing of documents).

Table of contents

• Installation via Docker

• Installation via .deb package

• Installation in a development environment

• Configuration to paste into the chat client

• Exposed tools

• Remote access

Related MCP server: mcp-rag-bridge

Installation via Docker

git clone <url-du-dépôt> ragifix-mcp && cd ragifix-mcp

cp config.example.yaml config.yaml              # puis l'adapter
cp deploy/ragifix-mcp.env.example ragifix-mcp.env # puis renseigner les secrets

docker build -f deploy/docker/Dockerfile -t ragifix-mcp .

docker run -d \
  --name ragifix-mcp \
  --network host \
  --env-file ragifix-mcp.env \
  -v "$(pwd)/config.yaml:/etc/ragifix/config.yaml:ro" \
  ragifix-mcp

--network host: by default (server.host: 127.0.0.1), the server must remain reachable locally on the machine that also hosts ragifix and the chat client.

Verify that the service is running (401 expected without a token — this is the sign that the server is responding):

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8422/mcp \
  -X POST -H "Content-Type: application/json" -d '{}'

Installation via .deb package

git clone <url-du-dépôt> ragifix-mcp && cd ragifix-mcp

sudo apt-get install -y devscripts debhelper python3-venv python3-pip
dpkg-buildpackage -us -uc -b

sudo apt install -y ../ragifix-mcp_0.1.0-1_all.deb

The installation (postinst) builds a Python virtual environment in /opt/ragifix-mcp/venv and installs the dependencies from PyPI (lightweight: mcp, httpx, starlette, uvicorn, pydantic — network access required at apt install time, the service then works offline).

The package creates a dedicated system user, /etc/ragifix-mcp/config.yaml and ragifix-mcp.env (from the examples), and a systemd unit ragifix-mcp.service.

sudo nano /etc/ragifix-mcp/config.yaml
sudo nano /etc/ragifix-mcp/ragifix-mcp.env
sudo systemctl enable --now ragifix-mcp
journalctl -u ragifix-mcp -f

sudo apt remove ragifix-mcp    # conserve la config
sudo apt purge ragifix-mcp     # supprime tout

Installation in a development environment

git clone <url-du-dépôt> ragifix-mcp && cd ragifix-mcp

python3 -m venv venv
source venv/bin/activate
pip install -e .

cp config.example.yaml config.yaml   # reste à côté du code, hors /etc

export RAGIFIX_MCP_TOKEN=dev-mcp-token
export RAGIFIX_API_TOKEN=dev-token    # le token de l'API ragifix visée

ragifix-mcp --config ./config.yaml

Configuration to paste into the chat client

Once the server is started, declare a remote MCP server (HTTP transport) in the client configuration, in the current standard format:

{
  "mcpServers": {
    "ragifix": {
      "url": "http://127.0.0.1:8422/mcp",
      "headers": {
        "Authorization": "Bearer <RAGIFIX_MCP_TOKEN>"
      }
    }
  }
}

Replace <RAGIFIX_MCP_TOKEN> with the value configured in ragifix-mcp.env (or RAGIFIX_MCP_TOKEN in development), and the URL with the actual server address if different from 127.0.0.1:8422.

Some older clients do not yet know how to connect directly to a remote HTTP server and only accept a local command (command/args); in that case, use a bridge such as mcp-remote:

{
  "mcpServers": {
    "ragifix": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "http://127.0.0.1:8422/mcp",
        "--header", "Authorization: Bearer <RAGIFIX_MCP_TOKEN>"
      ]
    }
  }
}

Refer to the documentation of the chat client used to know where to paste this configuration (MCP config file, or management interface for MCP connectors/servers).

Exposed tools

Remote access

By default (server.host: 127.0.0.1), the server is only reachable from the local machine — suitable for a chat client running on the same machine (e.g., Claude Desktop locally).

For a remote chat client, two changes are required:

1. server.host in config.yaml: set it to 0.0.0.0 (all interfaces) or to the IP of the relevant network interface. A warning is logged at startup as long as host is not local, to remind you of this point.

2. TLS: this server does not terminate TLS itself. Place a reverse proxy (nginx, Caddy, Traefik...) in front of it, which handles the certificate and relays to http://127.0.0.1:<port>/mcp internally. Minimal example with Caddy:

   mcp.exemple.fr {
       reverse_proxy 127.0.0.1:8422
   }

The url declared on the chat client side then becomes https://mcp.exemple.fr/mcp.

The dedicated token (RAGIFIX_MCP_TOKEN) remains the application-level protection in both cases — TLS protects the transport, the token protects access.