Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions bin/mcp-fnox-inject
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
#!/usr/bin/env bash
# mcp-fnox-inject
# Path: claude-code-config/bin/mcp-fnox-inject
#
# Starts an MCP server with only its own API key, read from fnox.
#
# Usage (in ~/.claude.json mcpServers):
# "command": "mcp-fnox-inject",
# "args": ["BRAVE_API_KEY", "npx", "-y", "@brave/brave-search-mcp-server@2.1.4"]
#
# `fnox exec` would hand the server every secret fnox holds; this passes one.
# fnox runs from HOME, so a fnox.toml in the repository a session opened is
# never read. A key fnox cannot decrypt stops the server with a message rather
# than starting it without one. exec keeps one process, so Claude's signals
# reach the server and nothing is left behind.
set -euo pipefail

readonly var="${1:?usage: mcp-fnox-inject VAR command [args...]}"
shift
if [[ ! "${var}" =~ ^[A-Z_][A-Z0-9_]*$ ]]; then
echo "mcp-fnox-inject: '${var}' is not a variable name" >&2
exit 2
fi
if (($# == 0)); then
echo "mcp-fnox-inject: no server command after ${var}" >&2
exit 2
fi

# A shim path survives fnox upgrades, for launchers whose PATH lacks mise's shims.
fnox_bin="${MCP_FNOX_BIN:-$(command -v fnox || echo "${HOME}/.local/share/mise/shims/fnox")}"
# fnox's own reason (a missing age key, say) is shown only when it fails.
err="$(mktemp)"
if ! value="$(cd "${HOME}" && "${fnox_bin}" get "${var}" 2>"${err}")" || [[ -z "${value}" ]]; then
sed 's/^/mcp-fnox-inject: fnox: /' "${err}" >&2
rm -f "${err}"
echo "mcp-fnox-inject: fnox could not decrypt ${var}; not starting the server" >&2
exit 1
fi
rm -f "${err}"
export "${var}=${value}"
exec "$@"
2 changes: 2 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,8 @@ The system auto-detects the secrets backend:
1. **Doppler** (enterprise): if the Doppler CLI is installed and configured for the project, uses Doppler secrets management.
2. **Envfile** (default): reads/writes API keys from `~/.claude/mcp-keys.env`. After rotation, syncs the active key to the envfile.

Launching the servers is separate from rotating keys: setup registers each MCP server through `mcp-fnox-inject`, which gives it only its own key from fnox (read from HOME), when fnox can decrypt that key, and through `mcp-env-inject` with the envfile otherwise. Doppler no longer launches any server.

Key rotation is atomic: find the current key's index in the pool, advance to the next, and write the new active key. Quota checking calls the provider's API (Brave: response headers, Tavily: `/usage` endpoint) with a 5-minute cache to avoid redundant API calls.

## The setup system
Expand Down
2 changes: 1 addition & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,7 @@ files another tool owns, the second for that profile alone. `claude-as` shares

| Server | Package | Environment Variable |
|--------|---------|---------------------|
| `brave-search` | `@brave/brave-search-mcp-server` | `BRAVE_API_KEY` |
| `brave-search` | `@brave/brave-search-mcp-server@2.1.4` | `BRAVE_API_KEY` |
| `tavily` | `tavily-mcp@0.2.17` | `TAVILY_API_KEY` |

Both use `${VAR}` syntax for runtime environment variable expansion.
Expand Down
14 changes: 10 additions & 4 deletions docs/how-to-add-mcp-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,15 +33,21 @@ Add the key to `~/.claude/mcp-keys.env`:
echo 'MY_API_KEY=your-key-here' >> ~/.claude/mcp-keys.env
```

### Doppler backend (enterprise)
### fnox backend (preferred)

If using Doppler for secrets management:
If [fnox](https://github.com/jdx/fnox) can decrypt a server's key, setup registers that server as
`mcp-fnox-inject <VAR> npx -y <package>`. The helper reads only that key, from HOME (so a
repository's `fnox.toml` is never read), exports it alone and `exec`s the server. `fnox exec`
would hand the server every secret fnox holds. A key fnox cannot decrypt stops the server with
fnox's reason. The helper only controls what it adds: keys exported in the shell that starts
Claude Code (a mise integration of fnox, say) still reach every server. Add the key from the directory that holds your fnox config:

```bash
doppler secrets set MY_API_KEY --project claude-code-config --config dev
printf %s "$MY_API_KEY" | fnox set MY_API_KEY --provider age
```

The setup script auto-detects which backend to use.
Setup decides per server: fnox when it can decrypt that server's key, the env file otherwise.
The choice is made at setup time; if fnox later cannot decrypt the key, re-run setup.

## 3. Verify the server

Expand Down
2 changes: 1 addition & 1 deletion lib/setup-ps/mcp.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ $script:McpServers = @{
label = "brave-search"
desc = "Web, image, video, news, local search (1,000/mo free)"
env_var = "BRAVE_API_KEY"
package = "@brave/brave-search-mcp-server"
package = "@brave/brave-search-mcp-server@2.1.4"
signup_url = "https://api-dashboard.search.brave.com/"
free_limit = "1,000 searches/month (`$5 free credits)"
}
Expand Down
97 changes: 38 additions & 59 deletions lib/setup/mcp.sh
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ mcp_get() {
brave-search:label) echo "brave-search" ;;
brave-search:desc) echo "Web, image, video, news, local search (1,000/mo free)" ;;
brave-search:env_var) echo "BRAVE_API_KEY" ;;
brave-search:package) echo "@brave/brave-search-mcp-server" ;;
brave-search:package) echo "@brave/brave-search-mcp-server@2.1.4" ;;
brave-search:signup_url) echo "https://api-dashboard.search.brave.com/" ;;
brave-search:free_limit) echo "1,000 searches/month (\$5 free credits)" ;;
tavily:label) echo "tavily" ;;
Expand All @@ -34,27 +34,20 @@ mcp_get() {
}

# --- MCP Backend Detection ---
# Determines whether to use Doppler wrapper or mcp-env-inject wrapper.
# Returns: "doppler" or "envfile"
# Per server: fnox when it can decrypt that server's key, else the env file.
# Usage: detect_mcp_backend [key] (key defaults to brave-search)
# Returns: "fnox" or "envfile"

readonly DOPPLER_PROJECT="${MCP_DOPPLER_PROJECT:-claude-code-config}"
readonly DOPPLER_CONFIG="${MCP_DOPPLER_CONFIG:-dev}"
readonly MCP_KEYS_ENV_FILE="${MCP_KEYS_ENV_FILE:-${CLAUDE_CONFIG_DIR:-${HOME}/.claude}/mcp-keys.env}"

detect_mcp_backend() {
# Tier 1: Doppler CLI available and project accessible
if command -v doppler &>/dev/null; then
# Test that at least one MCP key is accessible via Doppler
local test_var
test_var="$(mcp_get "brave-search" env_var)"
if doppler secrets get "${test_var}" --plain \
-p "${DOPPLER_PROJECT}" -c "${DOPPLER_CONFIG}" &>/dev/null; then
echo "doppler"
return
fi
local key="${1:-brave-search}" env_var
env_var="$(mcp_get "${key}" env_var)"
# From HOME, so a repository's fnox.toml is never read.
if command -v fnox &>/dev/null && (cd "${HOME}" && fnox get "${env_var}") &>/dev/null; then
echo "fnox"
return
fi

# Tier 2: Fall back to env file wrapper
echo "envfile"
}

Expand All @@ -70,18 +63,15 @@ configure_mcp_servers() {
return
fi

local backend
backend="$(detect_mcp_backend)"
echo " MCP backend: ${backend}"
echo ""

local key
local key backend any_envfile=0
for key in "${INSTALL_MCP_SERVERS[@]}"; do
backend="$(detect_mcp_backend "${key}")"
[[ "${backend}" == "envfile" ]] && any_envfile=1
_configure_single_mcp "${key}" "${backend}"
done

# For envfile backend: create the keys env file
if [[ "${backend}" == "envfile" ]]; then
# For servers on the envfile backend: create the keys env file
if ((any_envfile)); then
_create_mcp_keys_env
fi
}
Expand All @@ -96,13 +86,14 @@ _build_mcp_json() {
local package
package="$(mcp_get "${key}" package)"

if [[ "${backend}" == "doppler" ]]; then
# Doppler wrapper: doppler run -p PROJECT -c CONFIG -- npx -y <package>
if [[ "${backend}" == "fnox" ]]; then
# mcp-fnox-inject passes the server only its own key, read from fnox in HOME.
local env_var
env_var="$(mcp_get "${key}" env_var)"
jq -n -c \
--arg project "${DOPPLER_PROJECT}" \
--arg config "${DOPPLER_CONFIG}" \
--arg env_var "${env_var}" \
--arg package "${package}" \
'{type:"stdio",command:"doppler",args:["run","-p",$project,"-c",$config,"--","npx","-y",$package]}'
'{type:"stdio",command:"mcp-fnox-inject",args:[$env_var,"npx","-y",$package]}'
else
# Env file wrapper: mcp-env-inject npx -y <package>
jq -n -c \
Expand Down Expand Up @@ -200,33 +191,21 @@ _create_mcp_keys_env() {
}

check_mcp_env_vars() {
local backend
backend="$(detect_mcp_backend)"

if [[ "${backend}" == "doppler" ]]; then
echo " ✓ Doppler backend active — keys injected at MCP server launch"
return
fi

# For envfile backend: check the env file exists and has keys
if [[ -f "${MCP_KEYS_ENV_FILE}" ]]; then
local key
for key in "${INSTALL_MCP_SERVERS[@]}"; do
local env_var
env_var="$(mcp_get "${key}" env_var)"
if grep -q "^${env_var}=" "${MCP_KEYS_ENV_FILE}" 2>/dev/null; then
echo " ✓ ${env_var} found in ${MCP_KEYS_ENV_FILE}"
else
local signup_url free_limit
signup_url="$(mcp_get "${key}" signup_url)"
free_limit="$(mcp_get "${key}" free_limit)"
echo " ⚠ ${env_var} missing from ${MCP_KEYS_ENV_FILE}"
echo " echo '${env_var}=YOUR_KEY' >> ${MCP_KEYS_ENV_FILE}"
echo " Get a free API key (${free_limit}): ${signup_url}"
fi
done
else
echo " ⚠ ${MCP_KEYS_ENV_FILE} not found."
echo " Re-run setup.sh or create it manually with your MCP API keys."
fi
local key env_var backend
for key in "${INSTALL_MCP_SERVERS[@]}"; do
env_var="$(mcp_get "${key}" env_var)"
backend="$(detect_mcp_backend "${key}")"
if [[ "${backend}" == "fnox" ]]; then
echo " ✓ ${env_var} in fnox — injected alone at ${key} launch"
elif [[ -f "${MCP_KEYS_ENV_FILE}" ]] && grep -q "^${env_var}=" "${MCP_KEYS_ENV_FILE}" 2>/dev/null; then
echo " ✓ ${env_var} found in ${MCP_KEYS_ENV_FILE}"
else
local signup_url free_limit
signup_url="$(mcp_get "${key}" signup_url)"
free_limit="$(mcp_get "${key}" free_limit)"
echo " ⚠ ${env_var} missing from fnox and ${MCP_KEYS_ENV_FILE}"
echo " echo '${env_var}=YOUR_KEY' >> ${MCP_KEYS_ENV_FILE}"
echo " Get a free API key (${free_limit}): ${signup_url}"
fi
done
}
30 changes: 13 additions & 17 deletions lib/setup/opencode.sh
Original file line number Diff line number Diff line change
Expand Up @@ -238,21 +238,17 @@ with open(dest_path, "w", encoding="utf-8") as fh:
PYTHON_TRANSLATE
}

# backend = "doppler" → `doppler run -p PROJ -c CONF -- npx -y PKG`
# backend = "fnox" → `mcp-fnox-inject VAR npx -y PKG` (only that server's key)
# backend = "envfile" → `mcp-env-inject npx -y PKG`
# Wrong wrapper = MCP -32000 "Connection closed" (no keys reach server).
_opencode_build_mcp_entry() {
local pkg="$1" backend="$2"
if [[ "${backend}" == "doppler" ]]; then
jq -n -c \
--arg project "${DOPPLER_PROJECT}" \
--arg config "${DOPPLER_CONFIG}" \
--arg pkg "${pkg}" \
'{
type: "local",
command: ["doppler", "run", "-p", $project, "-c", $config, "--", "npx", "-y", $pkg],
enabled: true
}'
local pkg="$1" backend="$2" env_var="${3:-}"
if [[ "${backend}" == "fnox" ]]; then
jq -n -c --arg pkg "${pkg}" --arg env_var "${env_var}" '{
type: "local",
command: ["mcp-fnox-inject", $env_var, "npx", "-y", $pkg],
enabled: true
}'
else
jq -n -c --arg pkg "${pkg}" '{
type: "local",
Expand Down Expand Up @@ -346,9 +342,7 @@ _opencode_generate_json() {

OPENCODE_JSON="$(_opencode_resolve_config_path)"

local backend
backend="$(detect_mcp_backend)"

local backend backends=""
local mcp_section="{}"
local key
for key in "${INSTALL_MCP_SERVERS[@]}"; do
Expand All @@ -357,8 +351,10 @@ _opencode_generate_json() {
if [[ -z "${pkg}" ]]; then
continue
fi
backend="$(detect_mcp_backend "${key}")"
backends="${backends:+${backends}, }${key}: ${backend}"
local entry
entry="$(_opencode_build_mcp_entry "${pkg}" "${backend}")"
entry="$(_opencode_build_mcp_entry "${pkg}" "${backend}" "$(mcp_get "${key}" env_var)")"
mcp_section="$(printf '%s' "${mcp_section}" | jq -c \
--arg name "${key}" \
--argjson entry "${entry}" \
Expand Down Expand Up @@ -387,7 +383,7 @@ _opencode_generate_json() {
'. + {"$schema": "https://opencode.ai/config.json"} + {mcp: ((.mcp // {}) + $mcp)}')"

printf '%s\n' "${merged}" | jq '.' >"${OPENCODE_JSON}"
echo " ✓ ${OPENCODE_JSON} (${backend} backend)"
echo " ✓ ${OPENCODE_JSON} (${backends:-no servers})"
}

_opencode_link_agents_md() {
Expand Down
8 changes: 8 additions & 0 deletions setup.sh
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,14 @@ main() {
echo " Run: chmod +x ${REPO_DIR}/bin/mcp-env-inject"
fi

if [[ -x "${REPO_DIR}/bin/mcp-fnox-inject" ]]; then
ln -sf "${REPO_DIR}/bin/mcp-fnox-inject" "${bin_dir}/mcp-fnox-inject"
echo " ✓ ~/.local/bin/mcp-fnox-inject -> ${REPO_DIR}/bin/mcp-fnox-inject"
else
echo " ⚠ bin/mcp-fnox-inject not found or not executable (skipping)"
echo " Run: chmod +x ${REPO_DIR}/bin/mcp-fnox-inject"
fi

if [[ -x "${REPO_DIR}/bin/claude-permissions-audit" ]]; then
ln -sf "${REPO_DIR}/bin/claude-permissions-audit" "${bin_dir}/claude-permissions-audit"
echo " ✓ ~/.local/bin/claude-permissions-audit -> ${REPO_DIR}/bin/claude-permissions-audit"
Expand Down
34 changes: 17 additions & 17 deletions tests/mcp-env-inject-sync.bats
Original file line number Diff line number Diff line change
Expand Up @@ -273,34 +273,34 @@ EOF
# UNIT TESTS: detect_mcp_backend (from lib/setup/mcp.sh)
# ==========================================================================

@test "detect_mcp_backend: returns doppler when doppler is available" {
# Mock doppler is already in PATH and BRAVE_API_KEY is seeded
doppler_seed "BRAVE_API_KEY" "${KEY_A}"

run bash -c '
@test "detect_mcp_backend: returns fnox when fnox can decrypt the key" {
local bin="${BATS_TEST_TMPDIR}/fnox-bin"
mkdir -p "${bin}"
printf '#!/bin/sh\n[ "$1" = get ] && [ "$2" = BRAVE_API_KEY ] && echo k\n' > "${bin}/fnox"
chmod +x "${bin}/fnox"
run env PATH="${bin}:/usr/bin:/bin" bash -c '
source "'"${MCP_SH}"'"
detect_mcp_backend
'
[ "$status" -eq 0 ]
[ "$output" = "doppler" ]
[ "$output" = "fnox" ]
}

@test "detect_mcp_backend: returns envfile when doppler is not available" {
# Build a minimal PATH with only system dirs, excluding mock doppler AND real doppler
# We need basic commands (bash, grep, etc.) but no doppler anywhere
local minimal_path="/usr/bin:/bin:/usr/sbin:/sbin"

run env PATH="${minimal_path}" bash -c '
@test "detect_mcp_backend: returns envfile when fnox is not available" {
run env PATH="/usr/bin:/bin:/usr/sbin:/sbin" bash -c '
source "'"${MCP_SH}"'"
detect_mcp_backend
'
[ "$status" -eq 0 ]
[ "$output" = "envfile" ]
}

@test "detect_mcp_backend: returns envfile when doppler project is inaccessible" {
# Mock doppler is in PATH but no secrets are seeded (secrets get will fail)
run bash -c '
@test "detect_mcp_backend: returns envfile when fnox cannot decrypt the key" {
local bin="${BATS_TEST_TMPDIR}/fnox-bin"
mkdir -p "${bin}"
printf '#!/bin/sh\nexit 1\n' > "${bin}/fnox"
chmod +x "${bin}/fnox"
run env PATH="${bin}:/usr/bin:/bin" bash -c '
source "'"${MCP_SH}"'"
detect_mcp_backend
'
Expand Down Expand Up @@ -464,8 +464,8 @@ REPO_ROOT="$BATS_TEST_DIRNAME/.."
grep -q "detect_mcp_backend" "${REPO_ROOT}/lib/setup/mcp.sh"
}

@test "repo: lib/setup/mcp.sh references doppler run wrapper" {
grep -q "doppler run" "${REPO_ROOT}/lib/setup/mcp.sh"
@test "repo: lib/setup/mcp.sh references mcp-fnox-inject wrapper" {
grep -q "mcp-fnox-inject" "${REPO_ROOT}/lib/setup/mcp.sh"
}

@test "repo: lib/setup/mcp.sh references mcp-env-inject wrapper" {
Expand Down
Loading
Loading