Skip to content
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,7 @@ Releases follow [Semantic Versioning](https://semver.org/).

### Bug Fixes

- **`serve --data-dir` (and `MCPPROXY_DATA_DIR`) now reads `<data-dir>/mcp_config.json`.** Until now `serve` looked for its config only in the working directory and `$HOME/.mcpproxy` and applied the data dir afterwards, so a config on a mounted volume was ignored and a fresh one (new listen address, new API key) was written under `$HOME`, while every management command already read the config from the data dir. `serve` now resolves it the same way: an explicit `--config` wins, then `<data-dir>/mcp_config.json` if it exists, and on a first run with no config anywhere the default is seeded inside the data dir. `MCPPROXY_DATA_DIR`, documented but never implemented, now works as an alias of `--data-dir` (the legacy `MCPPROXY_DATA` keeps relocating only the data directory, and loses when both are set). If you already export `MCPPROXY_DATA_DIR`, it takes effect for the first time on this upgrade: the data directory, and so the database, search index and socket, move to it. **Migration:** an instance started with `--data-dir X` that relied on the config under `$HOME/.mcpproxy` while a stale `X/mcp_config.json` also exists will now read the one in `X`.
- **audit: a profile tool-policy refusal now names its rule (#1703).** The `authz` audit line for a call refused by a profile's tier cap, deny rule or unannotated-tool policy used to read `reason: other`; it now reads `profile_tier`, `profile_rule` or `profile_unannotated` (`disclosed: true`), matching the `block_reason` of the same call in the activity log. A refusal inside a `code_execution` script used to be written as `token_scope` with `disclosed: false` and now uses the same three reasons. `profile_scope` is unchanged, and `profile_code_execution` / `profile_management` are not audit reasons because those built-in tools are not audited per call. The `reason` enum in `docs/schemas/audit-line-v1.schema.json` gains the three members, so a consumer that validates audit lines against the enum must accept them. (refs #1703)

- **Upgrade no longer admits a server an older release held in quarantine (RC-UPG-001).** A v0.69 restart (including the baseline security scan shortly after startup) wrote a keyless server's un-gated config over its recorded quarantine, while v0.69 kept holding it in memory. On upgrade the config-load admission gate read that record as already admitted and auto-baseline approved all of its tools. The gate now also requires an approval baseline: a server recorded as unquarantined whose tools were never approved is quarantined again for review. Servers with approved tools are unaffected; vetted servers with no tool records (zero-tool servers, servers that never connected while live, servers last vetted before v0.21) are also held once — approve them, or set `"quarantined": false` before upgrading.
Expand Down
38 changes: 34 additions & 4 deletions cmd/mcpproxy/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -793,23 +793,53 @@ func readConfigFile(path string) (*config.Config, error) {
return config.DecodeConfigFile(path)
}

// implicitDataDirConfigPath is the config file `serve` uses when no --config was
// given but a data directory was: <data-dir>/mcp_config.json when it exists, and
// on a first run (no config in the data dir or in the legacy discovery
// locations) the same path so the default config is seeded inside the named
// directory instead of under $HOME. "" keeps the legacy discovery (cwd, then
// $HOME/.mcpproxy).
func implicitDataDirConfigPath() string {
if dataDir == "" {
return ""
}
p := config.GetConfigPath(dataDir)
if _, err := os.Stat(p); err == nil {
return p
}
if !legacyConfigExists() {
return p
}
return ""
}

func loadConfig(cmd *cobra.Command) (*config.Config, *serveConfigSaver, error) {
var cfg *config.Config
var err error
loadedPath := configFile

// A --data-dir (or MCPPROXY_DATA_DIR) names where this instance keeps its
// state, config included: every management command already reads
// <data-dir>/mcp_config.json (GH #854/#897/#908), so `serve` must too or
// the two disagree about the listen address and API key. An explicit
// --config still wins.
configPath := configFile
if configPath == "" {
configPath = implicitDataDirConfigPath()
}
loadedPath := configPath

// Load configuration - use LoadFromFile if config file specified, otherwise use Load
if configFile != "" {
if configPath != "" {
// A named config that has never been written is a FIRST RUN, not an
// error: the relocated tray instance of GH #936 spawns its core with
// --data-dir <root> --config <root>/mcp_config.json against a root
// nothing has used before. The implicit path has always created its
// default here; the explicit one used to exit with "no such file or
// directory" instead, which made that whole flow unusable.
if _, ensureErr := config.EnsureConfigFile(configFile, dataDir); ensureErr != nil {
if _, ensureErr := config.EnsureConfigFile(configPath, dataDir); ensureErr != nil {
return nil, nil, ensureErr
}
cfg, err = config.LoadFromFile(configFile)
cfg, err = config.LoadFromFile(configPath)
} else {
cfg, loadedPath, err = config.LoadWithPath()
}
Expand Down
12 changes: 12 additions & 0 deletions cmd/mcpproxy/path_flag.go
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ import (

"github.com/spf13/cobra"
"github.com/spf13/pflag"

"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
)

// nonEmptyPathValue is the pflag.Value behind every --config / --data-dir flag.
Expand Down Expand Up @@ -49,5 +51,15 @@ func addConfigFlag(fs *pflag.FlagSet, p *string, usage string) {
// -d/--data-dir flags.
func registerRootPathFlags(root *cobra.Command) {
root.PersistentFlags().VarP(newPathFlag(&configFile), "config", "c", "Configuration file path")
// MCPPROXY_DATA_DIR seeds --data-dir so every command (serve and the
// management commands that find the daemon through the data dir) agrees on
// the directory; an explicit flag still wins because it is parsed later.
if dataDir == "" {
dataDir = config.DataDirFromEnv()
}
root.PersistentFlags().VarP(newPathFlag(&dataDir), "data-dir", "d", "Data directory path (default: ~/.mcpproxy)")
// Keep --help identical whether or not the variable is set.
if f := root.PersistentFlags().Lookup("data-dir"); f != nil {
f.DefValue = ""
}
}
158 changes: 158 additions & 0 deletions cmd/mcpproxy/serve_data_dir_config_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,158 @@
package main

import (
"os"
"path/filepath"
"testing"

"github.com/spf13/cobra"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"

"github.com/smart-mcp-proxy/mcpproxy-go/internal/config"
)

// serveDataDirEnv isolates $HOME and cwd and clears every variable that could
// relocate the data dir, so a test only sees what it sets itself.
func serveDataDirEnv(t *testing.T) (home string) {
t.Helper()
saveServeGlobals(t)
home = t.TempDir()
t.Setenv("HOME", home)
t.Setenv("USERPROFILE", home)
t.Setenv(config.EnvDataDir, "")
t.Setenv(config.EnvDataDirLegacy, "")
t.Setenv("MCPPROXY_API_KEY", "")
// Seeding a first-run config probes Docker with a `docker info` subprocess
// (2 s timeout). On Windows a probe killed at the deadline can still hold
// the test's working directory for a moment and make t.TempDir cleanup
// fail; with no docker on PATH the probe returns without spawning anything.
t.Setenv("PATH", t.TempDir())
t.Chdir(t.TempDir())
configFile, dataDir = "", ""
return home
}

// `serve --data-dir X` reads X/mcp_config.json (the file the management
// commands already read), instead of $HOME/.mcpproxy.
func TestServeReadsConfigFromDataDir(t *testing.T) {
home := serveDataDirEnv(t)
d := filepath.Join(t.TempDir(), "state")
writeListenConfig(t, filepath.Join(d, "mcp_config.json"), "127.0.0.1:18997")
dataDir = d

cfg, saver, err := loadConfig(newServeFlagTestCmd())
require.NoError(t, err)
assert.Equal(t, "127.0.0.1:18997", cfg.Listen, "config in the data dir was ignored")
assert.Equal(t, d, cfg.DataDir)
assert.Equal(t, filepath.Join(d, "mcp_config.json"), saver.path, "later saves must go to the file that was read")
_, statErr := os.Stat(filepath.Join(home, ".mcpproxy", "mcp_config.json"))
assert.True(t, os.IsNotExist(statErr), "a default config was created under $HOME")
}

// The same through MCPPROXY_DATA_DIR, which registerRootPathFlags turns into
// the --data-dir default.
func TestServeReadsConfigFromDataDirEnv(t *testing.T) {
serveDataDirEnv(t)
d := filepath.Join(t.TempDir(), "state")
writeListenConfig(t, filepath.Join(d, "mcp_config.json"), "127.0.0.1:18996")
t.Setenv(config.EnvDataDir, d)

root := &cobra.Command{Use: "mcpproxy"}
registerRootPathFlags(root)
require.NoError(t, root.ParseFlags(nil))
require.Equal(t, d, dataDir)
assert.Equal(t, "", root.PersistentFlags().Lookup("data-dir").DefValue, "--help must not change when the variable is set")

cfg, _, err := loadConfig(newServeFlagTestCmd())
require.NoError(t, err)
assert.Equal(t, "127.0.0.1:18996", cfg.Listen)
assert.Equal(t, d, cfg.DataDir)
}

// An explicit --data-dir beats MCPPROXY_DATA_DIR.
func TestServeDataDirFlagBeatsEnv(t *testing.T) {
serveDataDirEnv(t)
envDir := filepath.Join(t.TempDir(), "env")
flagDir := filepath.Join(t.TempDir(), "flag")
writeListenConfig(t, filepath.Join(envDir, "mcp_config.json"), "127.0.0.1:18001")
writeListenConfig(t, filepath.Join(flagDir, "mcp_config.json"), "127.0.0.1:18002")
t.Setenv(config.EnvDataDir, envDir)

root := &cobra.Command{Use: "mcpproxy"}
registerRootPathFlags(root)
require.NoError(t, root.ParseFlags([]string{"--data-dir", flagDir}))

cfg, _, err := loadConfig(newServeFlagTestCmd())
require.NoError(t, err)
assert.Equal(t, "127.0.0.1:18002", cfg.Listen)
assert.Equal(t, flagDir, cfg.DataDir)
}

// An explicit --config still wins over a config in the data dir.
func TestServeConfigFlagBeatsDataDirConfig(t *testing.T) {
serveDataDirEnv(t)
d := filepath.Join(t.TempDir(), "state")
writeListenConfig(t, filepath.Join(d, "mcp_config.json"), "127.0.0.1:18001")
explicit := filepath.Join(t.TempDir(), "explicit.json")
writeListenConfig(t, explicit, "127.0.0.1:18003")
dataDir, configFile = d, explicit

cfg, _, err := loadConfig(newServeFlagTestCmd())
require.NoError(t, err)
assert.Equal(t, "127.0.0.1:18003", cfg.Listen)
}

// First run: nothing anywhere, so the default config (and its generated API
// key) is seeded inside the named data dir, not under $HOME.
func TestServeFirstRunSeedsConfigInDataDir(t *testing.T) {
home := serveDataDirEnv(t)
d := filepath.Join(t.TempDir(), "fresh")
dataDir = d

cfg, _, err := loadConfig(newServeFlagTestCmd())
require.NoError(t, err)
assert.Equal(t, d, cfg.DataDir)
_, statErr := os.Stat(filepath.Join(d, "mcp_config.json"))
assert.NoError(t, statErr, "default config was not seeded in the data dir")
_, statErr = os.Stat(filepath.Join(home, ".mcpproxy", "mcp_config.json"))
assert.True(t, os.IsNotExist(statErr), "a default config was created under $HOME")
}

// Compatibility: with no config in the data dir but one in the legacy location,
// serve keeps using the legacy file and only relocates the data dir.
func TestServeKeepsLegacyConfigWhenDataDirHasNone(t *testing.T) {
home := serveDataDirEnv(t)
writeListenConfig(t, filepath.Join(home, ".mcpproxy", "mcp_config.json"), "127.0.0.1:18004")
d := filepath.Join(t.TempDir(), "state")
require.NoError(t, os.MkdirAll(d, 0o700))
dataDir = d

cfg, _, err := loadConfig(newServeFlagTestCmd())
require.NoError(t, err)
assert.Equal(t, "127.0.0.1:18004", cfg.Listen)
assert.Equal(t, d, cfg.DataDir)
_, statErr := os.Stat(filepath.Join(d, "mcp_config.json"))
assert.True(t, os.IsNotExist(statErr), "no config should be seeded when a legacy one exists")
}

// MCPPROXY_DATA_DIR is the documented name and beats the legacy MCPPROXY_DATA
// when the loader applies env overrides; the legacy name keeps working alone.
func TestDataDirEnvNames(t *testing.T) {
cases := []struct {
name, newVar, legacy, want string
}{
{"new only", "/n", "", "/n"},
{"legacy only", "", "/l", "/l"},
{"both: new wins", "/n", "/l", "/n"},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
t.Setenv(config.EnvDataDir, tc.newVar)
t.Setenv(config.EnvDataDirLegacy, tc.legacy)
cfg := config.DefaultConfig()
config.ApplyEnvOverrides(cfg)
assert.Equal(t, tc.want, cfg.DataDir)
})
}
}
2 changes: 1 addition & 1 deletion docs/cli/command-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ These flags are available for all commands:
|------|-------------|
| `--config` | Path to configuration file |
| `--log-level` | Log level (debug, info, warn, error) |
| `--data-dir, -d` | Data directory path (default: ~/.mcpproxy) |
| `--data-dir, -d` | Data directory path (default: ~/.mcpproxy). Also the place `serve` reads `mcp_config.json` from when `--config` is not given. Env: `MCPPROXY_DATA_DIR` |
| `--log-to-file` | Enable logging to file in standard OS location |
| `--log-dir` | Custom log directory path (overrides standard OS location) |
| `--help` | Show help for command |
Expand Down
3 changes: 2 additions & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -1867,7 +1867,8 @@ Many configuration options can be overridden via environment variables:
| `MCPPROXY_TLS_ENABLED` | `tls.enabled` | Enable HTTPS/TLS |
| `MCPPROXY_TLS_REQUIRE_CLIENT_CERT` | `tls.require_client_cert` | Enable mTLS |
| `MCPPROXY_CERTS_DIR` | `tls.certs_dir` | Custom certificates directory |
| `MCPPROXY_DATA` | `data_dir` | Override data directory |
| `MCPPROXY_DATA_DIR` | `data_dir` | Override data directory; also where `serve` looks for `mcp_config.json` (same as `--data-dir`) |
| `MCPPROXY_DATA` | `data_dir` | Override data directory only (legacy name; `MCPPROXY_DATA_DIR` wins) |
| `MCPPROXY_TOOL_RESPONSE_MODE` | `tool_response_mode` | `retrieve_tools` serialization: `full` (default) or `compact` |
| `MCPPROXY_DIRECT_TOOL_RESPONSE_MODE` | `direct_tool_response_mode` | Direct enumeration surface serialization: `full` (default) or `deferred` |
| `MCPPROXY_MAX_CONCURRENT_REQUESTS` | `max_concurrent_requests` | Global aggregate cap on concurrent upstream tool calls (`0` disables it). See [Concurrency Limits](#concurrency-limits--request-queueing) |
Expand Down
4 changes: 2 additions & 2 deletions docs/configuration/environment-variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ Environment variables are useful for CI/CD environments or temporary overrides d
| `MCPPROXY_LISTEN` | Override listen address | `127.0.0.1:8080` or `:8080` |
| `MCPPROXY_API_KEY` | Set API key for authentication | `my-secret-key` |
| `MCPPROXY_API_KEY_FILE` | Read the API key from a file (absolute path). Set it or `MCPPROXY_API_KEY`, not both; see [API key from a file](#api-key-from-a-file) | `/run/secrets/mcpproxy_api_key` |
| `MCPPROXY_DATA_DIR` | Override data directory | `/var/lib/mcpproxy` |
| `MCPPROXY_DATA` | Override data directory (backward compatibility, prefer `MCPPROXY_DATA_DIR`) | `/var/lib/mcpproxy` |
| `MCPPROXY_DATA_DIR` | Override data directory. Like `--data-dir` (which wins when both are set), it also makes `serve` read `<data-dir>/mcp_config.json` | `/var/lib/mcpproxy` |
| `MCPPROXY_DATA` | Override data directory only (backward compatibility; `MCPPROXY_DATA_DIR` wins when both are set, and the config file is still looked up in the working directory and `~/.mcpproxy`) | `/var/lib/mcpproxy` |

### API key from a file

Expand Down
14 changes: 9 additions & 5 deletions docs/getting-started/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -383,11 +383,15 @@ docker run -d --name mcpproxy \
- **State survives restarts, not replacement**: `docker restart` keeps everything. Removing and
re-running the container, upgrading the tag, or rescheduling the pod destroys whatever is not
on the volume — so mount one before you configure anything.
- **Don't use `MCPPROXY_DATA` or a bare `--data-dir` to relocate state.** The data-dir override is
applied after the config file is resolved, so the config in that directory is never read and is
overwritten with a fresh default (rotating the API key) on every boot. Mount the volume at the
default `/root/.mcpproxy` path instead. (`MCPPROXY_DATA_DIR`, referenced elsewhere in the docs,
is not implemented at all.)
- **Relocating state**: `--data-dir` and `MCPPROXY_DATA_DIR` move the data directory and also
decide where `serve` looks for `mcp_config.json` — `<data-dir>/mcp_config.json` is read when it
exists, and seeded there on a first run with no config anywhere — so the config and its API key
live on the same volume as the database. If the data dir has no config but a legacy one exists in
the working directory or `$HOME/.mcpproxy`, `serve` keeps using that legacy file and moves only the
data. An explicit `--config` still wins. The legacy `MCPPROXY_DATA` only relocates the data
directory: with it the config is still looked up in the working directory and `$HOME/.mcpproxy`
(`/root/.mcpproxy` in this image). Releases before this change ignored `<data-dir>/mcp_config.json`
under `serve`, so on those, mount the volume at the default `/root/.mcpproxy` path instead.
- **Port**: the entrypoint is `mcpproxy serve --listen 0.0.0.0:8080`, so the container listens on
`8080` inside the network namespace. The `-p 127.0.0.1:8080:8080` above keeps it reachable only
from the host; drop the `127.0.0.1:` prefix only if you deliberately want it on the network, and
Expand Down
26 changes: 24 additions & 2 deletions internal/config/loader.go
Original file line number Diff line number Diff line change
Expand Up @@ -604,6 +604,21 @@ func SaveConfigToDataDir(cfg *Config) error {
return SaveConfig(cfg, configPath)
}

// Environment variables that name the data directory. EnvDataDir is the
// documented spelling and, like --data-dir, also decides where `serve` looks
// for mcp_config.json (see cmd/mcpproxy loadConfig). EnvDataDirLegacy keeps its
// historical meaning: it relocates the data directory only.
const (
EnvDataDir = "MCPPROXY_DATA_DIR"
EnvDataDirLegacy = "MCPPROXY_DATA"
)

// DataDirFromEnv returns the directory named by MCPPROXY_DATA_DIR, or "" when
// it is unset or blank. It does not consult the legacy MCPPROXY_DATA.
func DataDirFromEnv() string {
return strings.TrimSpace(os.Getenv(EnvDataDir))
}

// GetConfigPath returns the path to the configuration file in the data directory
func GetConfigPath(dataDir string) string {
if dataDir == "" {
Expand Down Expand Up @@ -844,8 +859,15 @@ func applyTLSEnvOverrides(cfg *Config) {
value = os.Getenv("MCPPROXY_CERTS_DIR")
envOverride(b, cfg, FieldTLSCertsDir, value != "", value)

// Override data directory from environment (for backward compatibility)
value = os.Getenv("MCPPROXY_DATA")
// Override data directory from environment. MCPPROXY_DATA_DIR is the
// documented name; MCPPROXY_DATA is kept for backward compatibility and
// loses when both are set.
// DataDirFromEnv trims the value, so a whitespace-only MCPPROXY_DATA_DIR
// neither relocates the data dir to " " nor shadows the legacy variable.
value = DataDirFromEnv()
if value == "" {
value = strings.TrimSpace(os.Getenv(EnvDataDirLegacy))
}
envOverride(b, cfg, FieldDataDir, value != "", value)

// Spec 112 FR-003: MCPPROXY_FORWARD_CLIENT_HEADERS=false|0|off disables
Expand Down
Loading