vaultproxy/mcp-servers.example.toml at main · aaronckj/vaultproxy · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
# vaultproxy MCP server launcher configuration
# Copy to your --config-dir as mcp-servers.toml.
#
# Use `vault-proxy --launch <name>` to start a server with credentials injected.
#
# RELOAD NOTE: Changes to this file require a PROCESS RESTART — they are NOT
# picked up by SIGHUP. SIGHUP only reloads services.toml (the /proxy registry).
# To apply mcp-servers.toml changes: docker compose restart vaultproxy
#
# SECURITY NOTES:
#
#   1. /proc/<pid>/environ exposure: --launch injects credentials into the
#      child process via fork/exec. On Linux, /proc/<pid>/environ is readable
#      by any same-user process. vault-proxy emits a warning on every --launch
#      invocation reminding operators of this risk. For stronger isolation, use
#      an MCP server that supports the native /proxy integration instead.
#
#   2. Shell-interpreter denylist: the `command` field must NOT use a shell
#      interpreter (bash, sh, zsh, python, node, etc.) as the executable.
#      vault-proxy refuses to launch these to prevent arbitrary command execution
#      with vault credentials in scope. Use a purpose-built binary or wrapper
#      instead of `command = "/bin/bash -c <script>"`.
#
#   3. Sensitive env vars: setting LD_PRELOAD, LD_LIBRARY_PATH, or similar
#      dynamic-linker control variables via the [[mcp_server.env]] block will
#      trigger a startup warning — these can cause shared-library injection.
#
#   4. Env var name rules: var names must match [A-Za-z_][A-Za-z0-9_]*. Names
#      containing '=', null bytes, or other special characters are rejected.

# ── UniFi Network MCP (sirkirby/unifi-mcp) ──────────────────────────────────
[[mcp_server]]
name = "unifi-network"
command = "uvx unifi-network-mcp@latest"

  [[mcp_server.env]]
  var = "UNIFI_HOST"
  value = "https://unifi.local"           # static — your controller URL

  [[mcp_server.env]]
  var = "UNIFI_API_KEY"
  vault_item = "vault-proxy - UniFi"      # resolved from Vaultwarden at launch
  field = "password"

# ── Home Assistant MCP ───────────────────────────────────────────────────────
[[mcp_server]]
name = "home-assistant"
command = "uvx homeassistant-mcp@latest"

  [[mcp_server.env]]
  var = "HA_BASE_URL"
  value = "http://homeassistant.local:8123"

  [[mcp_server.env]]
  var = "HA_TOKEN"
  vault_item = "vault-proxy - Home Assistant"
  field = "password"

# ── mcp-opnsense (smart /proxy integration — credentials never in env) ───────
# mcp-opnsense natively calls POST $VAULT_PROXY_URL/proxy for every OPNsense
# API request. vaultproxy injects Basic auth (API key + secret) internally.
# No vault_item entries needed here — credentials stay in vaultproxy.
# Requires a matching [[service]] block in services.toml:
#   name = "opnsense", auth = "basic", key_field = "key", secret_field = "secret"
# See mcp-opnsense repo: vaultproxy.example.toml
[[mcp_server]]
name = "mcp-opnsense"
command = "uvx mcp-opnsense@latest"
# VAULT_PROXY_URL is auto-injected — do NOT add it manually.

  [[mcp_server.env]]
  var = "OPNSENSE_HOST"
  value = "https://192.168.1.1"           # update to your OPNsense host

# ── mcp-duplicati (smart /proxy integration — credentials never in env) ──────
# mcp-duplicati natively calls POST $VAULT_PROXY_URL/proxy. vaultproxy manages
# the Duplicati session (login + token caching) internally.
# No vault_item entries needed here — credentials stay in vaultproxy.
# Requires a matching [[service]] block in services.toml:
#   name = "duplicati", auth = "session", login_path = "/api/v1/auth/login"
# See mcp-duplicati repo: vaultproxy.example.toml
[[mcp_server]]
name = "mcp-duplicati"
command = "uvx mcp-duplicati@latest"
# VAULT_PROXY_URL is auto-injected — do NOT add it manually.

  [[mcp_server.env]]
  var = "DUPLICATI_HOST"
  value = "http://localhost:8200"         # update to your Duplicati host

# ── mcp-caddy (no credentials — Caddy admin API is unauthenticated) ──────────
# Caddy's admin API (default: http://localhost:2019) requires no auth.
# Launcher mode is still useful for configuring CADDY_HOST when Caddy runs
# on a non-default address or a remote host.
[[mcp_server]]
name = "mcp-caddy"
command = "uvx mcp-caddy@latest"
# VAULT_PROXY_URL is auto-injected (unused by mcp-caddy, which has no auth).

  [[mcp_server.env]]
  var = "CADDY_HOST"
  value = "http://localhost:2019"         # update if Caddy admin binds elsewhere

# ── mcp-nettools (no credentials — uses system tools) ───────────────────────
# mcp-nettools runs ping, traceroute, DNS lookups, etc. — no remote service
# credentials. No [[mcp_server.env]] entries needed.
[[mcp_server]]
name = "mcp-nettools"
command = "uvx mcp-nettools@latest"

# ── Smart server example (native /proxy integration) ─────────────────────────
# A "smart" MCP server that natively supports vault-proxy does NOT need any
# [[mcp_server.env]] entries with vault_item — it discovers the proxy sidecar
# at runtime via the VAULT_PROXY_URL environment variable and calls
# POST $VAULT_PROXY_URL/proxy to make authenticated requests.
# Credentials never appear in its environment.
#
# AUTO-INJECTED VARIABLES: vaultproxy injects two env vars into every --launch
# child automatically.  Do NOT add manual [[mcp_server.env]] entries for them
# unless you want to override the auto-injected value:
#
#   VAULT_PROXY_URL        — URL of the vault-proxy sidecar.  Derived from
#                            --listen (or VAULT_PROXY_PUBLIC_URL if set).
#                            Smart servers call POST $VAULT_PROXY_URL/proxy.
#
#   VAULT_PROXY_CALLER_ID  — Server name from this file (e.g. "my-smart-mcp").
#                            Smart servers MUST forward this as the
#                            X-Caller-Id header on every /proxy request:
#                              X-Caller-Id: <value of VAULT_PROXY_CALLER_ID>
#                            This gives each launched server its own isolated
#                            per-caller rate-limit bucket automatically.
#
# This pattern provides stronger isolation than the "dumb" launcher examples
# above: vault-proxy injects auth headers into the outbound request internally,
# so the MCP server process only ever sees downstream service *responses*.
#
# To work correctly, the smart server's downstream service must be registered
# in services.toml with the correct auth type.
#
# Internal vault-proxy endpoints (/vault/*, /audit/*, /rotate) require the
# internal bearer token.  If your smart server needs to call these (not /proxy),
# it must read $CONFIG_DIR/internal-token and include it as:
#   Authorization: Bearer <token>
# This token is written by vault-proxy at startup (mode 0600) and is separate
# from any Vaultwarden credential.
#
# [[mcp_server]]
# name = "my-smart-mcp"
# command = "/usr/local/bin/my-smart-mcp"
# # VAULT_PROXY_URL is auto-injected — do NOT add it here manually.
# # Static (non-secret) env vars are still fine:
#
#   [[mcp_server.env]]
#   var = "MCP_SERVICE_NAME"
#   value = "ha_home"          # the service name registered in services.toml