Hosts the stdio MCP servers declared per tenant and per project in the Manager (navin-mcp-host): each server is started on demand, isolated in its own process (isolation process) or in its own rootless Podman container on the network of its tenant project (isolation container) with its memory and concurrency limits, and served over streamable HTTP at /t/{tenant}/p/{project}/s/{name}/mcp with its own bearer token. The list of hosted servers is written by the Manager (servers.json) and reloaded without restart.
Generated from catalog/services/mcp-host.yaml: do not edit by hand.
Summary
| |
|---|
| Version | 1.0.0 |
| Use | install and configure |
| Layer | functional (AI catalog) |
| Category | Gateways and load balancing |
| Installation methods | python |
| External connection | no |
| Sandbox only | no |
Licence
| |
|---|
| SPDX identifier | Apache-2.0 |
| Licence policy | core licence (MIT or Apache-2.0) |
| Licence exception | - |
| Platform component | navin-mcp-host |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
| Kind | Package | Version | Licence | Details |
|---|
| container image | docker.io/library/node | 22.23.4-bookworm-slim | Apache-2.0 | image key node, digest sha256:4b150b48b4116e2a22f2c39cc27025fbf4f153e2078fd3b14d159fdb5c7279da |
| container image | docker.io/astral/uv | 0.9.30-python3.12-bookworm-slim | Apache-2.0 | image key python, digest sha256:e5b65587bce7de595f299855d7385fe7fca39b8a74baa261ba1b7147afa78e58 |
| Python package | navin-mcp-host | 1.0.0 | Apache-2.0 | interpreters, in order of preference python3.12, python3.11, python3.10 |
Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|
python | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64, aarch64 (not restricted by the descriptor) |
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
- at least 1024 MB of memory (blocking,
memory).
- the program
npx installed on the host, only when isolation is process (warning, npx_present).
- the program
uvx installed on the host, only when isolation is process (warning, uvx_present).
- the program
podman installed on the host, only when isolation is container (blocking, podman_present).
- subordinate uid and gid ranges of the user navin-mcp-host in /etc/subuid and /etc/subgid (created by user.ensure on a root agent with usermod), only when
isolation is container (blocking, subordinate_ids).
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|
mcp-host | mcp | 8790/tcp | yes |
Services and connections needed
This service has no dependency.
Installation methods and modes
| Method | Default | What the method uses |
|---|
python | yes | a Python virtual environment holding the Python packages of the descriptor |
Components
| Component | Kind | Installation methods | Ports |
|---|
MCP host (mcp-host) | master | python | 8790/tcp |
Single instance (single) (default)
One instance hosts every MCP server of the cluster.
What the mode deploys:
| Component | Placement |
|---|
mcp-host | min 1, max 1 |
Distributed (replicated)
Two instances or more; each MCP server is placed on one instance, chosen by int(sha256(id)[:8], 16) modulo the number of instances sorted by id.
What the mode deploys:
| Component | Placement |
|---|
mcp-host | min 2, recommended 2 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select MCP hosting. The card shows the licence Apache-2.0.
-
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode: single (default), replicated. Each mode deploys the components listed in Installation methods and modes.
-
Bindings. This service has no dependency: the Bindings step has nothing to bind.
-
Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.
-
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.
High availability
| |
|---|
| Cluster | none (none) |
| High availability | redundancy (redundancy) |
| Failover | none (none) |
| Replication | none (none) |
| Quorum | none (none) |
| Discovery | static (static) |
| Entry point | any node (any-node) |
| Official documentation | https://modelcontextprotocol.io/specification/2025-03-26/basic/transports |
| Peer TLS parameter | tls_enabled |
| Peer authentication | No traffic between the instances: each one reads its own servers.json written by the Manager. |
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|
single | standalone (standalone) | single (single) | - | - | One instance hosts every server; it is a single point of failure. |
replicated | standalone (standalone) | active-active (active-active) | - | 2 | The servers are spread over the instances, each server on exactly one instance; the load is shared, a failed instance stops its own servers only. |
Notes
- Distribution, not high availability: a server is not moved when its instance fails; the Manager places it again on the next application of the hosting.
Configuration parameters
Network
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
MCP port (port) | port | 8790 | - | no | no | yes | Port of the streamable HTTP endpoint of the hosted servers, of /healthz and of /metrics. |
TLS (tls_enabled) | bool | false | - | no | no | yes | Serve the endpoint over TLS with a certificate issued by the manager CA. |
Maximum request size (max_body_kb) | int | 1024 | min 16, max 65536 | no | no | no | Kilobytes accepted in one MCP request; larger bodies are refused with 413. |
Limits of the hosted servers
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
Memory per server (default_memory_mb) | int | 512 | min 64, max 65536 | no | no | no | Default memory limit (MB) of one hosted server process; a server may set its own limit. |
Concurrent requests per server (default_max_concurrency) | int | 8 | min 1, max 256 | no | no | no | Default number of requests a hosted server handles at the same time; the others wait. |
Request timeout (request_timeout_s) | int | 60 | min 1, max 3600 | no | no | no | Seconds before a call to a hosted server is abandoned. |
Idle timeout (idle_timeout_s) | int | 600 | min 10, max 86400 | no | no | no | Seconds without a request after which the process of a hosted server is stopped (started again on the next request). |
Maximum servers per instance (max_servers) | int | 200 | min 1, max 10000 | no | no | no | Hosted servers accepted by one instance; the extra entries of servers.json are ignored and reported. |
Runtime
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
PATH of the servers (runtime_path) | string | /usr/local/bin:/usr/bin:/bin | - | no | no | no | PATH given to the hosted server processes (where npx, uvx or the server commands are found); with the isolation container, PATH of the podman commands (the servers keep the PATH of their image). |
Allowed origins (allowed_origins) | json | [] | - | no | no | no | Origin headers accepted from browsers (JSON list); empty refuses every browser origin. |
Log level (log_level) | enum | info | debug, info, warning, error | no | no | no | Verbosity of the runtime log. |
Isolation of the servers
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
Isolation (isolation) | enum | process | process, container | no | no | yes | process: each server is a child process of the host (separation by configuration, validated servers of the company catalogue only). container: each server runs in a rootless Podman container, one network per tenant project, read-only root file system, no capability, memory and pids quotas; needed for untrusted servers. |
Processes per container (container_pids_limit) | int | 256 | min 16, max 65536 | no | no | no | Maximum number of processes and threads of one server container (podman --pids-limit). |
Temporary space per container (container_tmpfs_mb) | int | 64 | min 1, max 4096 | no | no | no | Size (MB) of the in-memory /tmp of one server container, the only writable folder with /work. |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|
mcp | http | mcp-host | 8790 (port) | - | tls_enabled | - | - | - |
Commands
| Command | Component | Target | Description |
|---|
Status (status) | mcp-host | every host | Asks every instance whether it answers on /healthz. |
Recent logs (logs) | mcp-host | chosen host | Last lines of the runtime journal. |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|
mcp-host | HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.ip or '127.0.0.1' }}:{{ config.port }}/healthz | Expected 200; 30 retries; interval 2 s; timeout 5 s |
Readiness (service check)
| Check | Details |
|---|
HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.ip or '127.0.0.1' }}:{{ config.port }}/healthz | Expected 200; 10 retries; interval 2 s; timeout 5 s |
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|
memory | memory_mb {"min": 1024} | at least 1024 MB of memory | blocking | every component |
mcp_port_free | port_free {"param": "port"} | port 8790 free on the host | blocking | every component |
npx_present | binary {"name": "npx"} | the program npx installed on the host, only when isolation is process | warning | every component |
uvx_present | binary {"name": "uvx"} | the program uvx installed on the host, only when isolation is process | warning | every component |
podman_present | binary {"name": "podman"} | the program podman installed on the host, only when isolation is container | blocking | every component |
subordinate_ids | subordinate_ids {"user": "navin-mcp-host"} | subordinate uid and gid ranges of the user navin-mcp-host in /etc/subuid and /etc/subgid (created by user.ensure on a root agent with usermod), only when isolation is container | blocking | every component |
Uninstall
Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.
Quick links
- Metrics:
{{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/metrics
Upstream documentation