Skip to content

Install Canvus MCP on your own server

Install Canvus MCP 26.11.0, paired with the pinned Canvus Server 26.11.4 combined container. Use the server's existing customer installation process; this installer does not change its other images or database.

Requirements

Use a Linux amd64 host with a rootful Docker Engine and Docker Compose v2, Python 3 for one-time setup, 4 GiB available memory, persistent local storage, and an existing HTTPS reverse proxy. The bundled Caddy configuration targets a host Caddy service. Docker/user-namespace remapping needs equivalent host UID mappings; the bootstrap below specifically uses host UID/GID 65532.

You supply your own Canvus server, DNS name, and Canvus/AI client accounts. There is no MT gateway and no GitLab/GitHub developer login. Use the Canvus version and capabilities recorded in the qualified release manifest, not an older arbitrary server version. The MCP installer never modifies your Canvus database.

Verify and import

Obtain the manifest and SHA256SUMS through the official HTTPS download page. SHA256 checks transfer integrity, not a detached publisher signature. This release does not claim cryptographic signing. Check all files before extraction:

sha256sum -c SHA256SUMS

From the download directory, create a new staging folder and extract the verified customer bundle:

mkdir canvus-mcp-26.11.0
 tar -xzf canvus-mcp-26.11.0-customer.tar.gz -C canvus-mcp-26.11.0
cd canvus-mcp-26.11.0

Run the supplied importer using the matching versioned filenames:

sudo python3 import-image.py --manifest ../release-manifest.json --archive ../canvus-mcp-26.11.0-linux-amd64.image.tar

The importer rechecks the archive hash/size, loads Docker's image-save format, verifies the imported identity/user/platform, and writes a new .env. Classic Docker stores use the configuration ID; containerd stores may use the recorded OCI manifest digest. Compose pins that verified identity with pull_policy: never, not a floating tag. The importer refuses to overwrite an existing .env; for an upgrade use --env-output release.image.env, then follow operations.md.

Fresh installation

From the extracted bundle, replace both example domains before running:

sudo python3 bootstrap.py --directory /opt/canvus-mcp --public-origin https://mcp.customer.example --canvus-base-url https://canvus.customer.example/api/v1/

The target must not exist. Bootstrap creates a fresh 32-byte encryption key (mode0400, owner65532), state and uploads (mode0700, owner65532), and a nonsecret configuration. It refuses reinitialization. It starts no service and imports no accounts, tokens or demo data. Securely back up the key; never print it.

Copy only release inputs into the newly initialized directory:

sudo cp compose.yaml .env ca-certificates.crt /opt/canvus-mcp/
sudo cp -a manual-index dependency-notices /opt/canvus-mcp/
sudo chmod 0755 /opt/canvus-mcp/manual-index
sudo chmod 0644 /opt/canvus-mcp/manual-index/* /opt/canvus-mcp/ca-certificates.crt

For an internal Canvus CA, append your public CA certificate(s) to /opt/canvus-mcp/ca-certificates.crt, retaining the supplied public roots. Keep it mode0644 and mounted read-only. Never disable certificate verification or put private keys in this file.

Have DNS resolve the MCP domain to this host; configure your existing Caddy service with /opt/canvus-mcp/Caddyfile and validate/reload it using your normal proxy procedure. This routes the entire origin on HTTPS443, without a path prefix, authentication wall, automatic mutation retry, wildcard CORS or proxy buffering. Only explicitly configured browser origins are accepted. If adding a browser origin, set the exact HTTPS origin in config.json's allowed_origins array.

cd /opt/canvus-mcp
sudo docker compose up -d
sudo docker compose exec canvus-mcp /usr/local/bin/canvus-mcp healthcheck --config /etc/canvus-mcp/config.json

A successful probe verifies local state and the installed manual, not all upstream APIs. Follow the qualified release's client and Canvus compatibility checks before handing access to facilitators. manual_unavailable is a failed installation, not normal operation.

Networking and accounts

Desktop/CLI clients that originate connections locally can use LAN/VPN access. Cloud connectors, including claude.ai and cloud-originating Claude Desktop connections, need publicly reachable HTTPS443 and a publicly trusted certificate. A local-only endpoint is not an air-gapped cloud connector. Content returned to an AI client may be sent to that client's model provider under your own account.

See Connecting AI clients for OAuth and Upgrading and recovery for durable-state handling. The bundle also includes these instructions as clients.md and operations.md.

The proxy must preserve the canonical Host and Authorization/MCP session headers and route discovery, /authorize, /token, /register, /revoke, /mcp, /uploads and /downloads at the same origin. S256 PKCE supports CIMD and dynamic client registration; callbacks must exactly match registration. Do not use demo certificates or credentials. The generated configuration requires your explicit Canvus API URL; there is no development upstream default.