msg

docs/mcp-gateway.md

@@ -0,0 +1,62 @@
+# MCP Gateway Home Manager Module
+
+`homeManagerModules.mcp-gateway` exposes `services.mcp-gateway` and renders
+`~/.config/mcp-gateway/gateway.yaml` from Nix options.
+
+## Import
+
+```nix
+home-manager.sharedModules = [
+  mcp-servers.homeManagerModules.mcp-gateway
+];
+```
+
+## Minimal example
+
+```nix
+services.mcp-gateway = {
+  enable = true;
+  server = {
+    host = "100.64.0.19";
+    port = 39401;
+  };
+
+  environmentFile = "/run/secrets/rendered/mcp_gateway_env";
+
+  auth.apiKeys.dev = {
+    key = "env:DEV_GATEWAY_KEY";
+    backends = [ "nixos" "fetch" ];
+  };
+
+  backends = {
+    nixos.command = "${pkgs.mcp-nixos}/bin/mcp-nixos";
+    fetch.command = "${pkgs.mcp-server-fetch}/bin/mcp-server-fetch";
+  };
+};
+```
+
+`services.mcp-gateway.url` is read-only and resolves to
+`http://<server.host>:<server.port>/mcp`, for use by MCP clients.
+
+## Backends
+
+Backends are keyed by name and support:
+
+- `command` for stdio backends, or `httpUrl` for HTTP backends
+- `cwd`, `timeout`, `env`, `headers`
+- `passthrough`, `allowCleartextCredentials`
+- `resolveEnv = true` to wrap commands that read literal `${env.VAR}`
+  placeholders
+- `extraConfig` for fields not modelled by the module
+
+## API keys
+
+API keys are keyed by client name. The key may use the gateway's `env:VAR`,
+`keychain:NAME`, or `oauth:PROVIDER` indirection. Avoid literal secrets in the
+Nix store.
+
+## Routing profiles
+
+`routingProfiles.<name>` supports `allowBackends`, `denyBackends`,
+`allowTools`, and `denyTools`. Set `defaultRoutingProfile` to the profile used
+when a session has not selected one.