MCPO — Model Context Protocol Orchestrator
Purpose
Orchestrates Model Context Protocol (MCP) servers, providing a centralized way to manage and expose multiple MCP servers.
Entry Point
- Main file: mcpo.nix
- Upstream: MCPO GitHub Repository
Options
services.mcpo.apiTokenFile
| Type | null or absolute path |
| Default | null |
Path to a file containing the API token for the mcpo service. This file will be exposed to the service through a systemd credential named “apiToken”.
services.mcpo.configuration
| Type | attribute set of (submodule) |
| Default | { } |
This option has no description.
services.mcpo.configuration.<name>.args
| Type | list of string |
| Default | [ ] |
Arguments to pass to the command.
services.mcpo.configuration.<name>.command
| Type | null or string |
| Default | null |
Command to render the config file.
services.mcpo.configuration.<name>.headers
| Type | attribute set of string |
| Default | { } |
Headers to pass to the command.
services.mcpo.configuration.<name>.type
| Type | null or one of "sse", "streamable-http" |
| Default | null |
This option has no description.
services.mcpo.configuration.<name>.url
| Type | null or string |
| Default | null |
This option has no description.
services.mcpo.enable
| Type | boolean |
| Default | false |
| Example | true |
Whether to enable mcpo (Model Context Protocol Orchestrator) service.
services.mcpo.environment
| Type | attribute set of string |
| Default | { } |
Additional environment variables for the service.
services.mcpo.extraPackages
| Type | list of package |
| Default | [ ] |
Additional packages to include in the service’s PATH.
services.mcpo.helpers
| Type | attribute set |
| Default | { npxServer = <function>; npxServerWithArgs = <function>; uvxServer = <function>; uvxServerWithArgs = <function>; } |
Helper functions for constructing mcpo server command blocks.
services.mcpo.package
| Type | package |
| Default | <derivation mcpo-0.0.18> |
Package providing the mcpo executable.
Architecture / Services / Scope
MCPO runs as a DynamicUser with a state directory at /var/lib/mcpo. The configuration is rendered via sops.templates and loaded into the service via systemd credentials. The service’s PATH includes bash, nodejs, and uv by default to support various MCP server types; additional packages can be added with services.mcpo.extraPackages.
Secrets
apiTokenFile(optional) — API token exposed to the service as the systemd credentialapiToken.- Server configuration and environment are rendered through sops templates (
mcpoConfiguration,mcpoEnvironment) and consumed viaLoadCredential/EnvironmentFile.
Operational Notes / Assumptions
Usage Example
{ config, ... }: {
services.mcpo = {
enable = true;
configuration = {
everything = config.services.mcpo.helpers.npxServer "@modelcontextprotocol/server-everything";
};
};
}
Package Patches
- mcpo-union-repr-compat.patch — Applied via overlay in
overlays/patches/. Upstream testsrc/mcpo/tests/test_main.pyassertsUnionrepr starts with"typing.Union[", but Python 3.12+ may stringify unions asstr | float. Patch usesget_origin(result_type) is Unioninstead. Build/test compatibility only; no runtime impact.