Configuration

OpenMaskit needs no configuration to start. Run uvx openmaskit and add servers from the dashboard. Everything you configure via the UI persists to ~/.openmaskit/store.db.

If you'd rather declare servers in a file (handy for reproducible setups, CI environments, or version control), drop an openmaskit.yaml in the directory you start OpenMaskit from, or pass an explicit path:

uvx openmaskit ./openmaskit.yaml

openmaskit.yaml

Minimal example

targets:
  time:
    upstream:
      transport: stdio
      command: uvx
      args: ["mcp-server-time"]

Full example

# Optional dashboard / MCP ports
web_port: 9473
mcp_port: 9474

# Optional storage location
store_path: "~/.openmaskit/store.db"

# Optional container-runtime override (auto-detected if not set)
# container_runtime: "podman"  # docker, podman, nerdctl, or finch

targets:
  # Local stdio MCP server
  time:
    upstream:
      transport: stdio
      command: uvx
      args: ["mcp-server-time"]
    rules:
      - tool_name: get_current_time
        field_path: timezone
        action: mask

  # Containerized stdio MCP server with env-var secret
  postgres:
    upstream:
      transport: stdio
      command: docker
      args:
        - "run"
        - "-i"
        - "--rm"
        - "-e"
        - "DATABASE_URI"
        - "crystaldba/postgres-mcp"
      env:
        DATABASE_URI: postgresql://user:pass@localhost:5432/mydb
    guardrails:
      - tool_name: execute_sql
        argument_name: query
        match_type: contains
        pattern: "DROP TABLE"
        message: "Destructive SQL blocked"

  # Remote HTTP MCP server with static-header auth
  datadog:
    upstream:
      transport: http
      url: https://mcp.datadoghq.eu/api/unstable/mcp-server/mcp
      headers:
        DD-API-KEY: replace-with-your-key
        DD-APPLICATION-KEY: replace-with-your-key

targets.<name>.upstream

Field	Transport	Description
transport	both	stdio or http.
command	stdio	Executable to spawn.
args	stdio	List of command-line arguments.
env	stdio	Env vars to pass to the subprocess.
url	http	Upstream MCP endpoint URL.
headers	http	Static HTTP headers (for API-key style auth).
oauth	http	OAuth 2.1 config block (see below).

targets.<name>.rules

rules:
  - tool_name: get_user
    field_path: email
    action: mask           # or `strip`
    prefix: email          # optional — defaults derived from field name

targets.<name>.guardrails

guardrails:
  - tool_name: execute_sql
    argument_name: query         # or "*" to scan all string args recursively
    match_type: contains         # contains | equals | regex
    pattern: "DROP TABLE"
    message: "Destructive SQL blocked"

Static HTTP headers

Marketplace servers, custom HTTP servers, and openmaskit.yaml HTTP targets all support a headers map for API-key style auth. Values are encrypted at rest in store.db.

Reserved transport / MCP-protocol names are rejected at submit-time:

• Transport layer: Host, Content-Length, Transfer-Encoding, Connection.
• MCP protocol: mcp-protocol-version, mcp-session-id.
• Any header name containing openmaskit.

OAuth-protected HTTP servers

OpenMaskit supports three OAuth flows for HTTP MCP servers — see Concepts → OAuth install modes and the README for the full breakdown. The dashboard install modal picks the right one based on the catalog entry's oauth_mode field; for custom servers added via UI, you choose between BYO credentials and Dynamic Client Registration.

Environment variables

All env vars are optional. Defaults are listed.

Networking and ports

Variable	Default	Description
OPENMASKIT_HOST	127.0.0.1	Bind address for dashboard and MCP endpoint.

Storage

Variable	Default	Description
OPENMASKIT_STORE_PATH	~/.openmaskit/store.db	Masking config + state database.
OPENMASKIT_TRAFFIC_DB_PATH	~/.openmaskit/traffic.db	Audit log database (separate file).
OPENMASKIT_ENCRYPTION_KEY	reads ~/.openmaskit/.key	Fernet key for OAuth tokens, encrypted server configs, and the encrypted audit-log columns.
OPENMASKIT_TRAFFIC_MAX_ROWS	10000	Global row cap on the audit log.

Hardening

Variable	Default	Description
OPENMASKIT_MAX_REQUEST_BYTES	1048576	Body size cap on the dashboard and MCP endpoints. Oversized = 413.
OPENMASKIT_MAX_PARSE_BYTES	1048576	Per-text-block cap when OpenMaskit tries to parse an upstream tool response. Larger blocks pass through unparsed (and so unmasked at the JSON-path level).

Backend

Variable	Default	Description
OPENMASKIT_MARKETPLACE_API_URL	https://api.maskitmcp.com	Marketplace catalog backend.
OPENMASKIT_DISABLE_MARKETPLACE	unset	Set to 1 to opt out of all backend calls. Custom servers continue to work; the marketplace tab will be empty.

Anonymous telemetry

Marketplace requests carry an anonymous installation ID (~/.openmaskit/.installation_id) and the OpenMaskit version, for usage analytics on which marketplace entries see traffic. No tool args, responses, server configs, secrets, or per-user data are sent. Set OPENMASKIT_DISABLE_MARKETPLACE=1 to opt out entirely.

CLI flags

openmaskit [config_path] [options]

  -c, --config PATH       Config file path (positional `config_path` takes priority)
  -w, --web-port PORT     Override dashboard port
  -m, --mcp-port PORT     Override MCP endpoint port
  -s, --store-path PATH   Override masking-config DB path
      --version           Print version and exit

CLI flags override openmaskit.yaml. openmaskit.yaml overrides built-in defaults.