sql-safe-mcp 1.5.2__tar.gz → 2.0.0__tar.gz

{sql_safe_mcp-1.5.2 → sql_safe_mcp-2.0.0}/CHANGELOG.md

@@ -7,6 +7,67 @@ categories `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`.
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-11-07
+
+### Added
+
+- `sql-safe-mcp --verify-pii-rules [--strict]` connects to each `all_pii_safe` alias, reports how
+  many tables and columns every PII rule matches, and warns about rules that match nothing
+  (exit 2 with `--strict`) and about unprotected columns whose names look personal.
+- `logging.audit: true` writes one `sql_safe_mcp.audit` line per `execute_sql` call with the server,
+  database, tables and columns read, protected column count, row count, truncation, and elapsed
+  time (or the error `code`). It never contains SQL, bind values, rows, or tokens. Off by default;
+  the tool response is unchanged.
+- `--verify-pii-rules` also checks `pii.exposed_columns` and `pii.deny` entries (unmatched ones
+  warn and fail `--strict`) and, in `deny-by-default`, advises only on exposed columns.
+- `pii.mode: deny-by-default` protects every column not listed in `pii.exposed_columns`, and
+  `pii.deny` rejects any reference to a column with `QUERY_REJECTED` ("a denied column cannot be
+  referenced"). Existing configurations are unchanged. See `docs/configuration.md`.
+- `runtime.token_ttl_seconds` (off by default) rejects tokens older than the limit with
+  `INVALID_PII_TOKEN`. Enabling it also rejects tokens issued before it was set. The token format
+  stays `pii:v1:`.
+- `runtime.min_count_cell` (off by default) makes `execute_sql` return a `COUNT(*)` value from 1
+  to the threshold minus one as `null`, with the new column encoding `suppressed`. `0` is not
+  suppressed.
+- `pii_key_file` reads an alias key from a file instead of `pii_key_env`; a relative path is
+  resolved against the configuration file's directory. On POSIX the file must be owned by the
+  server user or root, with no access for others and no group write.
+
+### Security
+
+- With `logging.level: DEBUG`, the MCP SDK no longer writes a malformed protocol message to
+  stderr; its logger is held at `INFO` or above, because that message could carry SQL, tokens,
+  or rows.
+- `all_pii_safe` aliases now require verified TLS in `connection_url`: SQL Server needs
+  `Encrypt=yes` and rejects `TrustServerCertificate=yes` and `odbc_connect`; MySQL and MariaDB
+  need `ssl_ca` or `ssl_capath` and reject options that turn certificate checks off. A
+  configuration without them fails at startup with `CONFIG_ERROR`. `require_tls: false` on the
+  alias turns the check off and logs a warning at every start.
+- After loading the configuration, the server removes `pii_key_env` variables from its environment,
+  so child processes such as ODBC drivers no longer inherit PII keys.
+- `pii.rules` entries accept an optional `domain`. A token returned for a column of one domain is
+  rejected with `INVALID_PII_TOKEN` when compared with a column of another domain, so protected
+  values cannot be replayed across unrelated columns. Without `domain` the domain is the server
+  alias. Rules of different domains matching one column reject queries touching it with
+  `QUERY_REJECTED`.
+- PII tokens now pad their payload to a multiple of 32 bytes, so token length reveals only a
+  32-byte bucket of the plaintext length.
+- Tokens issued before padding and domains are rejected with `INVALID_PII_TOKEN`; agents must
+  request new tokens.
+- `execute_sql` now allows each SQL construct only in the positions the supported subset uses.
+  A bare column or literal used as a condition (`WHERE a`, `ON 1`, `WHERE a AND b = 1`) and any
+  other node in an unlisted position is rejected with `QUERY_REJECTED` before the database runs
+  the query.
+- `execute_sql` now checks a PII token against the type of the protected column it is compared
+  with. A string token compared with an integer or decimal column, or any token compared with a
+  column of an unrecognised type, is rejected with `QUERY_REJECTED` before the database runs the
+  query. Before, SQL Server could echo the decrypted value in a conversion error (for example
+  error 245).
+- Driver error messages in logs no longer carry values. Quoted literals (`'…'`, `N'…'`, `"…"`)
+  become `'***'` and digit runs of six or more become `***`, since SQL Server and MySQL echo the
+  offending value in conversion and duplicate-key errors. A failed `execute_sql` logs only the
+  driver error class and its SQLSTATE or numeric code, with no message text.
+
 ## [1.5.2] - 2026-10-05
 
 ### Security

{sql_safe_mcp-1.5.2 → sql_safe_mcp-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sql-safe-mcp
-Version: 1.5.2
+Version: 2.0.0
 Summary: Minimal, read-only, PII-safe MCP server for SQL databases.
 License: MIT License
         
@@ -26,10 +26,10 @@ License: MIT License
 License-File: LICENSE
 Requires-Python: <3.15,>=3.12
 Requires-Dist: anyio<5,>=4.8
-Requires-Dist: cryptography<47,>=46.0.7
+Requires-Dist: cryptography<51,>=48.0.1
 Requires-Dist: mcp<3,>=2
 Requires-Dist: pydantic<3,>=2.10
-Requires-Dist: pymysql>=1.2.3
+Requires-Dist: pymysql<2,>=1.2.3
 Requires-Dist: pyodbc<6,>=5.2
 Requires-Dist: pyyaml<7,>=6
 Requires-Dist: sqlalchemy<3,>=2.0
@@ -133,7 +133,7 @@ or
 pip install sql-safe-mcp
 ```
 
-Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.5.2`.
+Pin a version when you want a fixed surface: `uvx sql-safe-mcp==2.0.0`.
 
 Requires Python 3.12–3.14, [uv](https://docs.astral.sh/uv/) (or `pip`), and
 [Microsoft ODBC Driver 18 for SQL Server](https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server)
@@ -278,6 +278,8 @@ Protection covers the columns you list, so list every column that holds personal
   limits, and logging.
 - [Tool reference](docs/tools.md) - arguments, responses, errors, and the accepted SQL subset.
 - [Security model](docs/security-model.md) - trust boundaries, guarantees, limitations, and verification.
+- [Health data of minors](docs/health-data.md) - requirements, mechanisms, and an operator
+  checklist for medical deployments.
 - [Checks](docs/checks.md) - local, integration, and security verification commands.
 
 ## Security

{sql_safe_mcp-1.5.2 → sql_safe_mcp-2.0.0}/README.md

@@ -95,7 +95,7 @@ or
 pip install sql-safe-mcp
 ```
 
-Pin a version when you want a fixed surface: `uvx sql-safe-mcp==1.5.2`.
+Pin a version when you want a fixed surface: `uvx sql-safe-mcp==2.0.0`.
 
 Requires Python 3.12–3.14, [uv](https://docs.astral.sh/uv/) (or `pip`), and
 [Microsoft ODBC Driver 18 for SQL Server](https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server)
@@ -240,6 +240,8 @@ Protection covers the columns you list, so list every column that holds personal
   limits, and logging.
 - [Tool reference](docs/tools.md) - arguments, responses, errors, and the accepted SQL subset.
 - [Security model](docs/security-model.md) - trust boundaries, guarantees, limitations, and verification.
+- [Health data of minors](docs/health-data.md) - requirements, mechanisms, and an operator
+  checklist for medical deployments.
 - [Checks](docs/checks.md) - local, integration, and security verification commands.
 
 ## Security

{sql_safe_mcp-1.5.2 → sql_safe_mcp-2.0.0}/pyproject.toml

@@ -1,16 +1,16 @@
 [project]
 name = "sql-safe-mcp"
-version = "1.5.2"
+version = "2.0.0"
 description = "Minimal, read-only, PII-safe MCP server for SQL databases."
 readme = "README.md"
 requires-python = ">=3.12,<3.15"
 license = { file = "LICENSE" }
 dependencies = [
     "anyio>=4.8,<5",
-    "cryptography>=46.0.7,<47",
+    "cryptography>=48.0.1,<51",
     "mcp>=2,<3",
     "pydantic>=2.10,<3",
-    "pymysql>=1.2.3",
+    "pymysql>=1.2.3,<2",
     "pyodbc>=5.2,<6",
     "pyyaml>=6,<7",
     "sqlalchemy>=2.0,<3",
@@ -63,7 +63,7 @@ markers = [
 [tool.mutmut]
 source_paths = ["src/sql_safe_mcp"]
 also_copy = ["server.json", "README.md", "tools", "scripts", "compose.sqlserver.yml", "compose.mysql.yml"]
-only_mutate = ["*security/*.py", "*config.py"]
+only_mutate = ["*security/*.py", "*config.py", "*diagnostics.py", "*service.py"]
 mutate_only_covered_lines = true
 pytest_add_cli_args = ["-q", "-m", "not integration and not deep", "-p", "no:cacheprovider"]
 pytest_add_cli_args_test_selection = ["tests/unit", "tests/security", "tests/contract"]

{sql_safe_mcp-1.5.2 → sql_safe_mcp-2.0.0}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/proprock/sql-safe-mcp",
     "source": "github"
   },
-  "version": "1.5.2",
+  "version": "2.0.0",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "sql-safe-mcp",
-      "version": "1.5.2",
+      "version": "2.0.0",
       "transport": {
         "type": "stdio"
       }

{sql_safe_mcp-1.5.2 → sql_safe_mcp-2.0.0}/sql-safe-mcp.example-multi.yaml

@@ -19,11 +19,14 @@ servers:
   billing:
     # `sqlserver` uses an mssql+pyodbc URL; the URL dialect must match this engine.
     engine: sqlserver
-    # all_pii_safe requires both `pii_key_env` and at least one effective local PII rule.
+    # all_pii_safe requires a key (`pii_key_env` or `pii_key_file`) and at least one effective PII rule.
     access_level: all_pii_safe
+    # all_pii_safe requires verified TLS: the URL must set Encrypt=yes and must not set
+    # TrustServerCertificate=yes. `require_tls: false` turns the check off for a dev server.
     connection_url: "${BILLING_SQL_URL}"
     # Environment-variable name for one base64-encoded 32-byte key. Names must match
-    # ^[A-Z_][A-Z0-9_]*$; each all_pii_safe alias needs a different key.
+    # ^[A-Z_][A-Z0-9_]*$; each all_pii_safe alias needs a different key. Instead of
+    # pii_key_env you may set `pii_key_file: secrets/billing.key` (relative to this file).
     pii_key_env: BILLING_PII_KEY
     pii:
       # Only local rules are used in this file; `include` is intentionally absent.
@@ -42,6 +45,7 @@ servers:
     # mysql and mariadb both use mysql+pymysql URLs. Select the engine matching the server.
     engine: mysql
     access_level: all_pii_safe
+    # Verified TLS for MySQL/MariaDB: the URL must set ssl_ca (or ssl_capath).
     connection_url: "${SHOP_MYSQL_URL}"
     pii_key_env: SHOP_PII_KEY
     pii:

{sql_safe_mcp-1.5.2 → sql_safe_mcp-2.0.0}/sql-safe-mcp.example-shared.yaml

@@ -38,6 +38,9 @@ pii_rules:
         schema: dbo # Optional for SQL Server; omit it to match every schema.
         table: "Users[0-9]?"
         columns: [Email, FirstName, LastName]
+        # Optional token domain (alias character set). Tokens of one domain are accepted only on
+        # columns of that domain; without it the domain is the server alias.
+        domain: users_identity
 
 servers:
   legacy-prod:
@@ -65,6 +68,21 @@ servers:
           table: Cards
           columns: [HolderName]
 
+  peds-deny-by-default:
+    engine: sqlserver
+    access_level: all_pii_safe
+    connection_url: "${PEDS_SQL_URL}"
+    pii_key_env: PEDS_PII_KEY
+    pii:
+      # `deny-by-default` protects every column that exposed_columns does not list.
+      mode: deny-by-default
+      exposed_columns: # `database` is optional here and defaults to "*".
+        - table: Visits
+          columns: [VisitId, DepartmentCode, VisitYear]
+      deny: # Unreachable even as a token; columns: ["*"] denies a whole table.
+        - table: "*"
+          columns: [Notes, Anamnesis, Attachment]
+
   reporting-metadata:
     engine: sqlserver
     access_level: metadata

{sql_safe_mcp-1.5.2 → sql_safe_mcp-2.0.0}/src/sql_safe_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Minimal, PII-safe MCP server for relational databases."""
 
-__version__ = "1.5.2"
+__version__ = "2.0.0"

{sql_safe_mcp-1.5.2 → sql_safe_mcp-2.0.0}/src/sql_safe_mcp/__main__.py

@@ -10,6 +10,7 @@ from pathlib import Path
 from sql_safe_mcp.config import load_config
 from sql_safe_mcp.errors import DomainError
 from sql_safe_mcp.mcp_server import create_server
+from sql_safe_mcp.pii_audit import collect_catalog, verify_pii_rules
 
 
 def _positive_int(value: str) -> int:
@@ -41,11 +42,24 @@ def _parser() -> argparse.ArgumentParser:
         metavar="N",
         help="Print N base64-encoded 32-byte PII keys (default: 1) and exit.",
     )
+    actions.add_argument(
+        "--verify-pii-rules",
+        action="store_true",
+        help="Connect to each all_pii_safe alias and report PII rules that match nothing.",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="With --verify-pii-rules, exit 2 when any rule matches nothing.",
+    )
     return parser
 
 
 def main() -> None:
-    args = _parser().parse_args()
+    parser = _parser()
+    args = parser.parse_args()
+    if args.strict and not args.verify_pii_rules:
+        parser.error("--strict requires --verify-pii-rules")
     if args.gen_pii_key is not None:
         for _ in range(args.gen_pii_key):
             print(base64.b64encode(secrets.token_bytes(32)).decode("ascii"))
@@ -58,6 +72,12 @@ def main() -> None:
     if args.check_config:
         print(f"Configuration valid: {len(config.servers)} server alias(es).")
         return
+    if args.verify_pii_rules:
+        report = verify_pii_rules(config, collect_catalog)
+        print("\n".join(report.lines), file=sys.stderr)
+        if report.errors or (args.strict and report.unmatched_rules):
+            raise SystemExit(2)
+        return
     create_server(config).run("stdio")
 
 

{sql_safe_mcp-1.5.2 → sql_safe_mcp-2.0.0}/src/sql_safe_mcp/config.py

@@ -4,6 +4,8 @@ import base64
 import binascii
 import os
 import re
+import stat
+import sys
 from collections.abc import Mapping
 from copy import deepcopy
 from pathlib import Path
@@ -32,6 +34,10 @@ class RuntimeConfig(BaseModel):
     pool_timeout_seconds: int = Field(default=10, ge=1, le=300)
     statement_timeout_seconds: int = Field(default=30, ge=1, le=3600)
     max_definition_chars: int = Field(default=262_144, ge=1024, le=10_000_000)
+    # None keeps tokens valid until the key changes; otherwise a token expires this many whole
+    # seconds after it was issued.
+    token_ttl_seconds: int | None = Field(default=None, ge=1, le=315_360_000, strict=True)
+    min_count_cell: int = Field(default=0, ge=0, le=1000, strict=True)
     default_max_rows: int = Field(default=200, ge=1, le=100_000)
     hard_max_rows: int = Field(default=1000, ge=1, le=100_000)
     max_sql_chars: int = Field(default=65_536, ge=256, le=1_000_000)
@@ -50,6 +56,7 @@ class LoggingConfig(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"
+    audit: bool = False
 
 
 class PiiRule(BaseModel):
@@ -59,6 +66,7 @@ class PiiRule(BaseModel):
     schema_: str | None = Field(default=None, alias="schema")
     table: str = Field(min_length=1)
     columns: list[str] = Field(min_length=1)
+    domain: str | None = Field(default=None, pattern=rf"^{_SERVER_ALIAS_PATTERN}$")
 
     @model_validator(mode="after")
     def validate_wildcards(self) -> PiiRule:
@@ -72,10 +80,41 @@ class PiiRule(BaseModel):
         return self
 
 
+class PiiScopeRule(PiiRule):
+    """An `exposed_columns` or `deny` entry; the database defaults to any."""
+
+    database: str = Field(default="*", min_length=1)
+
+    @model_validator(mode="after")
+    def validate_no_domain(self) -> PiiScopeRule:
+        if self.domain is not None:
+            raise ValueError("domain is allowed only on pii rules")
+        return self
+
+
+def _check_column_wildcards(
+    rules: list[PiiRule], exposed: list[PiiScopeRule], deny: list[PiiScopeRule]
+) -> None:
+    if any("*" in column for rule in [*rules, *exposed] for column in rule.columns):
+        raise ValueError("pii rules and exposed_columns cannot list '*' columns; only deny can")
+    if any("*" in column and rule.columns != ["*"] for rule in deny for column in rule.columns):
+        raise ValueError("a deny column wildcard must be exactly ['*']")
+
+
 class PiiConfig(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
-    rules: list[PiiRule] = Field(min_length=1)
+    mode: Literal["protect", "deny-by-default"] = "protect"
+    rules: list[PiiRule] = Field(default_factory=list)
+    exposed_columns: list[PiiScopeRule] = Field(default_factory=list)
+    deny: list[PiiScopeRule] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> PiiConfig:
+        _check_column_wildcards(self.rules, self.exposed_columns, self.deny)
+        if self.mode == "protect" and not (self.rules or self.deny):
+            raise ValueError("pii requires at least one rule or deny entry")
+        return self
 
 
 class PiiConfigInput(BaseModel):
@@ -83,15 +122,26 @@ class PiiConfigInput(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
+    mode: Literal["protect", "deny-by-default"] = "protect"
     include: list[str] = Field(default_factory=list)
     rules: list[PiiRule] = Field(default_factory=list)
+    exposed_columns: list[PiiScopeRule] = Field(default_factory=list)
+    deny: list[PiiScopeRule] = Field(default_factory=list)
 
 
 class PiiRuleSet(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     name: str | None = Field(default=None, pattern=rf"^{_SERVER_ALIAS_PATTERN}$")
-    rules: list[PiiRule] = Field(min_length=1)
+    rules: list[PiiRule] = Field(default_factory=list)
+    exposed_columns: list[PiiScopeRule] = Field(default_factory=list)
+    deny: list[PiiScopeRule] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def validate_not_empty(self) -> PiiRuleSet:
+        if not (self.rules or self.exposed_columns or self.deny):
+            raise ValueError("a pii rule set needs rules, exposed_columns or deny")
+        return self
 
 
 _PERCENT_ESCAPE = re.compile(r"%[0-9A-Fa-f]{2}")
@@ -110,7 +160,9 @@ class ServerConfigBase(BaseModel):
     access_level: Literal["metadata", "meta_and_code", "all_pii_safe"] = "metadata"
     connection_url: SecretStr
     pii_key_env: str | None = Field(default=None, pattern=r"^[A-Z_][A-Z0-9_]*$")
+    pii_key_file: str | None = Field(default=None, min_length=1)
     pii_key: SecretStr | None = Field(default=None, exclude=True)
+    require_tls: bool = Field(default=True, strict=True)
 
     @model_validator(mode="after")
     def validate_connection_url(self) -> ServerConfigBase:
@@ -136,20 +188,84 @@ class ServerConfigBase(BaseModel):
         return base64.b64decode(self.pii_key.get_secret_value(), validate=True)
 
 
+_TLS_ERROR = "all_pii_safe servers require verified TLS: "
+# Allowlists: only these values prove an encrypted connection with a checked certificate.
+_MSSQL_ENCRYPT_ON = frozenset({"yes", "true", "mandatory", "strict"})
+_MSSQL_TRUST_OFF = frozenset({"no", "false"})
+# PyMySQL options that replace or weaken the certificate checks SQLAlchemy builds from ssl_ca.
+_MYSQL_TLS_OVERRIDES = ("ssl_verify_cert", "ssl_verify_identity", "ssl_disabled")
+
+
+def _tls_options(url: str) -> dict[str, str]:
+    """Casefolded query options; a repeated option (in any case) is refused."""
+    options: dict[str, str] = {}
+    for name, value in make_url(url).query.items():
+        key = name.casefold()
+        if key in options or not isinstance(value, str):
+            raise ValueError(f"{_TLS_ERROR}connection_url sets {key!r} more than once")
+        options[key] = value
+    return options
+
+
+def _weakened(option: str) -> ValueError:
+    return ValueError(
+        f"{_TLS_ERROR}connection_url option {option!r} disables certificate checks; "
+        "remove it, or set require_tls: false"
+    )
+
+
+def _check_verified_tls(engine: str, url: str) -> None:
+    options = _tls_options(url)
+    if engine == "sqlserver":
+        if "odbc_connect" in options:
+            raise ValueError(
+                f"{_TLS_ERROR}odbc_connect cannot be checked; use URL query options, "
+                "or set require_tls: false"
+            )
+        if options.get("encrypt", "").casefold() not in _MSSQL_ENCRYPT_ON:
+            raise ValueError(
+                f"{_TLS_ERROR}set Encrypt=yes in connection_url, or require_tls: false"
+            )
+        trust = options.get("trustservercertificate")
+        if trust is not None and trust.casefold() not in _MSSQL_TRUST_OFF:
+            raise _weakened("trustservercertificate")
+        return
+    if not options.get("ssl_ca") and not options.get("ssl_capath"):
+        raise ValueError(
+            f"{_TLS_ERROR}set ssl_ca or ssl_capath in connection_url, or require_tls: false"
+        )
+    for option in _MYSQL_TLS_OVERRIDES:
+        if option in options:
+            raise _weakened(option)
+    hostname = options.get("ssl_check_hostname")
+    if hostname is not None and hostname.casefold() != "true":
+        raise _weakened("ssl_check_hostname")
+
+
 class ServerConfig(ServerConfigBase):
     pii: PiiConfig | None = None
 
     @model_validator(mode="after")
     def validate_security_shape(self) -> ServerConfig:
         if self.access_level == "all_pii_safe":
-            if not self.pii_key_env or self.pii is None:
-                raise ValueError("all_pii_safe servers require pii_key_env and pii rules")
-            if self.engine != "sqlserver" and any(rule.schema_ for rule in self.pii.rules):
+            if self.pii_key_env and self.pii_key_file:
+                raise ValueError("set either pii_key_env or pii_key_file, not both")
+            if not (self.pii_key_env or self.pii_key_file) or self.pii is None:
+                raise ValueError(
+                    "all_pii_safe servers require pii_key_env or pii_key_file, and pii rules"
+                )
+            scoped = [*self.pii.rules, *self.pii.exposed_columns, *self.pii.deny]
+            if self.engine != "sqlserver" and any(rule.schema_ for rule in scoped):
                 raise ValueError(f"pii rules for engine {self.engine!r} cannot set schema")
-        elif self.pii_key_env is not None or self.pii is not None:
+            if self.require_tls:
+                _check_verified_tls(self.engine, self.connection_url.get_secret_value())
+        elif self.pii_key_env is not None or self.pii_key_file is not None or self.pii is not None:
             raise ValueError(
-                f"{self.access_level} servers cannot configure pii_key_env or pii rules"
+                f"{self.access_level} servers cannot configure "
+                "pii_key_env, pii_key_file or pii rules"
             )
+        elif "require_tls" in self.model_fields_set:
+            raise ValueError(f"{self.access_level} servers cannot configure require_tls")
         return self
 
 
@@ -227,17 +343,17 @@ def _validation_summary(error: ValidationError) -> str:
 def _resolve_pii_rules(raw: dict[object, object], config: AppConfigInput) -> dict[object, object]:
     """Flatten shared PII rules before runtime configuration is constructed."""
 
-    default_rules: list[PiiRule] = []
-    named_rules: dict[str, list[PiiRule]] = {}
+    default_set: PiiRuleSet | None = None
+    named_sets: dict[str, PiiRuleSet] = {}
     for rule_set in config.pii_rules or []:
         if rule_set.name is None:
-            if default_rules:
+            if default_set is not None:
                 raise ValueError("at most one unnamed pii rule set is allowed")
-            default_rules = rule_set.rules
+            default_set = rule_set
             continue
-        if rule_set.name in named_rules:
+        if rule_set.name in named_sets:
             raise ValueError(f"duplicate pii rule set name {rule_set.name!r}")
-        named_rules[rule_set.name] = rule_set.rules
+        named_sets[rule_set.name] = rule_set
 
     resolved = deepcopy(raw)
     resolved.pop("pii_rules", None)
@@ -249,31 +365,94 @@ def _resolve_pii_rules(raw: dict[object, object], config: AppConfigInput) -> dic
         if server.access_level != "all_pii_safe":
             if server.pii is not None:
                 raise ValueError(
-                    f"{server.access_level} servers cannot configure pii_key_env or pii rules"
+                    f"{server.access_level} servers cannot configure "
+                    "pii_key_env, pii_key_file or pii rules"
                 )
             continue
 
-        effective_rules = list(default_rules)
-        if server.pii is not None:
+        sets: list[PiiRuleSet | PiiConfigInput] = [default_set] if default_set is not None else []
+        mode = "protect"
+        local = server.pii
+        if local is not None:
+            mode = local.mode
             included: set[str] = set()
-            for name in server.pii.include:
-                if name not in named_rules:
+            for name in local.include:
+                if name not in named_sets:
                     raise ValueError(f"server {alias!r} includes unknown pii rule set {name!r}")
                 if name in included:
                     raise ValueError(
                         f"server {alias!r} includes pii rule set {name!r} more than once"
                     )
                 included.add(name)
-                effective_rules.extend(named_rules[name])
-            effective_rules.extend(server.pii.rules)
+                sets.append(named_sets[name])
+            sets.append(local)
+        merged = {
+            field: [
+                rule.model_dump(by_alias=True) for item in sets for rule in getattr(item, field)
+            ]
+            for field in ("rules", "exposed_columns", "deny")
+        }
         server_data["pii"] = (
-            {"rules": [rule.model_dump(by_alias=True) for rule in effective_rules]}
-            if effective_rules
-            else None
+            {"mode": mode, **merged} if any(merged.values()) or mode != "protect" else None
         )
     return resolved
 
 
+_KEY_FILE_LIMIT = 1024
+# Group write/execute and every "other" bit: a key file may be shared with the group read-only.
+_KEY_FILE_FORBIDDEN_BITS = 0o037
+
+
+def _decode_key(alias: object, text: str) -> str:
+    try:
+        decoded = base64.b64decode(text, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise ValueError(f"PII key for server {alias!r} is not valid base64") from exc
+    if len(decoded) != 32:
+        raise ValueError(f"PII key for server {alias!r} must decode to 32 bytes")
+    return text
+
+
+def _check_key_file_owner(alias: object, info: os.stat_result) -> None:
+    if sys.platform != "win32":
+        if info.st_uid not in (0, os.geteuid()):
+            raise ValueError(
+                f"PII key file for server {alias!r} must be owned by the server user or root"
+            )
+        if stat.S_IMODE(info.st_mode) & _KEY_FILE_FORBIDDEN_BITS:
+            raise ValueError(
+                f"PII key file for server {alias!r} must not be writable by group or accessible "
+                "by others (use mode 0600, 0640 or 0440)"
+            )
+
+
+def _read_key_file(alias: object, path: Path) -> str:
+    """Read a base64 key file; permissions are checked on the opened descriptor."""
+    try:
+        if sys.platform == "win32":
+            descriptor = os.open(path, os.O_RDONLY)
+        else:
+            # O_NONBLOCK keeps a FIFO from blocking startup; it is rejected as non-regular below.
+            descriptor = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
+        try:
+            info = os.fstat(descriptor)
+            if not stat.S_ISREG(info.st_mode):
+                raise ValueError(f"PII key file for server {alias!r} is not a regular file")
+            _check_key_file_owner(alias, info)
+            data = os.read(descriptor, _KEY_FILE_LIMIT + 1)
+        finally:
+            os.close(descriptor)
+    except OSError as exc:
+        raise ValueError(f"PII key file for server {alias!r} cannot be read") from exc
+    if len(data) > _KEY_FILE_LIMIT:
+        raise ValueError(f"PII key file for server {alias!r} is larger than 1024 bytes")
+    try:
+        text = data.decode("ascii").strip()
+    except UnicodeDecodeError as exc:
+        raise ValueError(f"PII key for server {alias!r} is not valid base64") from exc
+    return _decode_key(alias, text)
+
+
 def load_config(path: str | Path, environ: Mapping[str, str] | None = None) -> AppConfig:
     env = os.environ if environ is None else environ
     try:
@@ -291,18 +470,23 @@ def load_config(path: str | Path, environ: Mapping[str, str] | None = None) -> A
                 raise ValueError(f"server {alias!r} requires connection_url")
             value["connection_url"] = _expand_connection_url(url, env)
             key_env = value.get("pii_key_env")
+            key_file = value.get("pii_key_file")
             if key_env is not None:
                 if not isinstance(key_env, str) or key_env not in env:
                     raise ValueError(f"missing PII key environment variable {key_env!r}")
-                try:
-                    decoded = base64.b64decode(env[key_env], validate=True)
-                except (binascii.Error, ValueError) as exc:
-                    raise ValueError(f"PII key for server {alias!r} is not valid base64") from exc
-                if len(decoded) != 32:
-                    raise ValueError(f"PII key for server {alias!r} must decode to 32 bytes")
-                value["pii_key"] = env[key_env]
+                value["pii_key"] = _decode_key(alias, env[key_env])
+            elif isinstance(key_file, str) and key_file:
+                # Relative to the YAML file, never to the working directory of the MCP host.
+                value["pii_key"] = _read_key_file(alias, Path(path).parent / key_file)
         input_config = AppConfigInput.model_validate(raw)
-        return AppConfig.model_validate(_resolve_pii_rules(raw, input_config))
+        config = AppConfig.model_validate(_resolve_pii_rules(raw, input_config))
+        if environ is None:
+            # Child processes (ODBC drivers, shells) must not inherit the keys.
+            for server in config.servers.values():
+                if server.pii_key_env is not None:
+                    # Present: loading read it, and aliases cannot share a key variable.
+                    del os.environ[server.pii_key_env]
+        return config
     except ValidationError as exc:
         raise DomainError(
             ErrorCode.CONFIG_ERROR,