Configuration

Configuration file format, environment variables, CLI flag overrides, and authentication token storage for the MCP Client.

6 min read

The MCP Client uses a layered configuration system. Settings are resolved in the following precedence order (highest to lowest):

CLI flags – Passed directly on the command line
Environment variables – Set in the shell or .env file
Configuration file – ~/.mcp/config.yaml
Built-in defaults – Hardcoded fallback values

Configuration File

The configuration file lives at ~/.mcp/config.yaml. If it does not exist, the client uses built-in defaults for all settings.

Full Configuration Reference

# ~/.mcp/config.yaml

# ============================================================
# Registry
# ============================================================
registry:
  # URL of the MCP registry to resolve and download packages from.
  url: "https://registry.mcp-hub.io"

  # HTTP timeout for registry API calls (resolve, download).
  timeout: "30s"

  # Maximum number of retries for failed requests (5xx errors).
  max_retries: 3

  # Whether to verify TLS certificates. Set to false only for
  # local development with self-signed certificates.
  tls_verify: true

# ============================================================
# Cache
# ============================================================
cache:
  # Directory where downloaded manifests and bundles are stored.
  # Uses content-addressed storage (SHA-256 digests as filenames).
  directory: "~/.mcp/cache"

  # Maximum total size of cached artifacts. When exceeded, the
  # least recently used artifacts are evicted.
  max_size: "10GB"

  # Time-to-live for cached metadata (not bundles). Bundles are
  # cached indefinitely since they are content-addressed.
  ttl: "24h"

# ============================================================
# Executor
# ============================================================
executor:
  # Default execution timeout. Can be overridden per-run with
  # the --timeout flag.
  default_timeout: "5m"

  # Default resource limits applied to every MCP server process.
  # These can be overridden per-run with CLI flags.
  resource_limits:
    # Maximum memory allocation.
    max_memory: "256m"

    # Maximum CPU cores (fractional values allowed).
    max_cpu: 1.0

    # Maximum number of child processes (PIDs).
    max_pids: 64

    # Maximum number of open file descriptors.
    max_fds: 256

  # Working directory for MCP server processes. If "auto", a
  # temporary directory is created per execution.
  workdir: "auto"

# ============================================================
# Security
# ============================================================
security:
  # Default network policy for MCP server processes.
  # "deny" blocks all outbound connections (Linux only).
  # "allow" permits all network access.
  network_default: "deny"

  # Subprocess control. When true, MCP servers cannot spawn
  # child processes unless the manifest explicitly grants
  # subprocess permissions.
  restrict_subprocess: true

  # Whether to enforce digest validation on cached artifacts
  # before every run. Strongly recommended to leave enabled.
  verify_on_run: true

# ============================================================
# Audit
# ============================================================
audit:
  # Enable audit logging of all executions.
  enabled: true

  # Path to the audit log file. Supports absolute paths or
  # paths relative to ~/.mcp/.
  log_file: "~/.mcp/audit.log"

  # Audit log format: "json" (structured) or "text" (human-readable).
  format: "json"

  # Whether to include environment variable names (not values)
  # in audit logs.
  log_env_names: true

# ============================================================
# Policy
# ============================================================
policy:
  # Minimum certification level required to run a package.
  # 0 = Integrity Verified (any package)
  # 1 = Static Verified (score >= 60)
  # 2 = Security Certified (score >= 80)
  # 3 = Runtime Certified (score >= 90)
  min_cert_level: 0

  # List of allowed origin types. Packages with origins not
  # in this list are rejected.
  allowed_origins:
    - "Official"
    - "Verified"
    - "Community"

  # Environment variable filtering. Only variables matching
  # these patterns are passed to MCP server processes.
  # Use "*" to allow all, or specify exact names or glob
  # patterns.
  allowed_env:
    - "PATH"
    - "HOME"
    - "LANG"
    - "LC_*"
    - "TZ"

  # Blocked environment variables. These are never passed to
  # MCP server processes, regardless of allowed_env.
  blocked_env:
    - "AWS_*"
    - "GITHUB_TOKEN"
    - "MCP_REGISTRY_TOKEN"
    - "*_SECRET*"
    - "*_PASSWORD*"
    - "*_KEY*"

  # Whether to allow MCP servers to spawn subprocesses.
  allow_subprocess: false

Minimal Configuration

For most users, only the registry URL needs to be configured:

# ~/.mcp/config.yaml
registry:
  url: "https://registry.mcp-hub.io"

All other values use sensible defaults.

Local Development Configuration

For development against a local MCP Hub Platform instance:

# ~/.mcp/config.yaml
registry:
  url: "http://localhost:8081"
  tls_verify: false
  timeout: "60s"

executor:
  default_timeout: "10m"
  resource_limits:
    max_memory: "1g"

security:
  network_default: "allow"

policy:
  min_cert_level: 0
  allowed_origins:
    - "Official"
    - "Verified"
    - "Community"

Environment Variables

Environment variables follow the MCP_ prefix convention and use underscores to represent nesting.

Variable	Config Equivalent	Default	Description
`MCP_REGISTRY_URL`	`registry.url`	`https://registry.mcp-hub.io`	Registry endpoint URL
`MCP_REGISTRY_TOKEN`	(auth.json)	none	Authentication token (overrides auth.json)
`MCP_REGISTRY_TIMEOUT`	`registry.timeout`	`30s`	Registry API timeout
`MCP_CACHE_DIR`	`cache.directory`	`~/.mcp/cache`	Cache directory path
`MCP_CACHE_MAX_SIZE`	`cache.max_size`	`10GB`	Maximum cache size
`MCP_LOG_LEVEL`	(global)	`info`	Log verbosity: `debug`, `info`, `warn`, `error`
`MCP_TIMEOUT`	`executor.default_timeout`	`5m`	Default execution timeout
`MCP_MAX_MEMORY`	`executor.resource_limits.max_memory`	`256m`	Default memory limit
`MCP_MAX_CPU`	`executor.resource_limits.max_cpu`	`1.0`	Default CPU limit
`MCP_NETWORK_DEFAULT`	`security.network_default`	`deny`	Network policy
`MCP_MIN_CERT_LEVEL`	`policy.min_cert_level`	`0`	Minimum certification level
`MCP_ALLOWED_ORIGINS`	`policy.allowed_origins`	`Official,Verified,Community`	Allowed origin types (comma-separated)
`MCP_AUDIT_FILE`	`audit.log_file`	`~/.mcp/audit.log`	Audit log file path
`MCP_AUDIT_FORMAT`	`audit.format`	`json`	Audit log format

Example: CI/CD Pipeline

export MCP_REGISTRY_URL="https://registry.mcp-hub.io"
export MCP_REGISTRY_TOKEN="$CI_MCP_TOKEN"
export MCP_CACHE_DIR="/tmp/mcp-cache"
export MCP_MIN_CERT_LEVEL=2
export MCP_ALLOWED_ORIGINS="Official,Verified"
export MCP_LOG_LEVEL="warn"

mcp pull acme/[email protected]
mcp run acme/[email protected]

CLI Flag Overrides

CLI flags provide the highest precedence and are useful for one-off overrides:

# Override registry for a single command
mcp pull acme/[email protected] --registry http://localhost:8081

# Override resource limits for a single run
mcp run acme/[email protected] --max-memory 2g --max-cpu 4.0

# Override policy for a single run
mcp run acme/[email protected] --min-cert-level 2 --allowed-origins Official,Verified

Precedence Example

Given the following configuration:

# ~/.mcp/config.yaml
executor:
  resource_limits:
    max_memory: "256m"

export MCP_MAX_MEMORY="512m"

mcp run acme/[email protected] --max-memory 1g

The effective memory limit is 1g, because CLI flags have the highest precedence.

Authentication Token Storage

Authentication tokens are stored separately from the configuration file, in ~/.mcp/auth.json with 0600 permissions (owner read/write only).

File Format

{
  "registries": {
    "https://registry.mcp-hub.io": {
      "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
      "created_at": "2025-01-15T10:00:00Z"
    },
    "http://localhost:8081": {
      "token": "eyJhbGciOiJIUzI1NiJ9...",
      "created_at": "2025-01-15T12:00:00Z"
    }
  }
}

Security Considerations

Tokens are stored on disk with restrictive file permissions (0600).
The MCP_REGISTRY_TOKEN environment variable overrides the token from auth.json. This is the recommended approach for CI/CD pipelines where you do not want tokens written to disk.
Tokens are not auto-refreshed. When a token expires, run mcp login again.
The mcp logout command removes tokens from the file.
Tokens are never logged in plaintext. Audit logs record that a token was used, but redact the token value.

Do Not Commit auth.json

The ~/.mcp/auth.json file contains sensitive credentials. Never commit it to version control. It is located in the home directory specifically to avoid accidental inclusion in project repositories.

Configuration Directory Structure

The MCP Client uses ~/.mcp/ as its base directory:

~/.mcp/
  config.yaml       # Configuration file
  auth.json          # Authentication tokens (0600 perms)
  audit.log          # Audit log (if enabled)
  cache/             # Content-addressed artifact cache
    sha256/
      a1b2c3d4e5f6.../   # Cached manifest + bundle
      f6e5d4c3b2a1.../

Creating the Configuration Directory

The directory is created automatically on first use. To create it manually:

mkdir -p ~/.mcp
chmod 700 ~/.mcp

Custom Configuration File Location

To use a different configuration file:

# Via CLI flag
mcp run acme/[email protected] --config /etc/mcp/config.yaml

# Via environment variable (Viper convention)
export MCP_CONFIG=/etc/mcp/config.yaml
mcp run acme/[email protected]