Configuration

Configuration file reference and environment variables

3 min read

The smcp CLI is configured through a YAML file, environment variables, and command-line flags. For most users, the defaults work out of the box with no configuration needed.

Config File Location

The default configuration file location is:

~/.mcp/config.yaml

You can override this with the --config flag or the MCP_CONFIG environment variable:

# Using a flag
smcp run --config /etc/mcp/config.yaml cr0hn/mcp-schrodinger@latest

# Using an environment variable
export MCP_CONFIG=/etc/mcp/config.yaml
smcp run cr0hn/mcp-schrodinger@latest

Full Configuration Schema

# Registry settings
registry:
  url: "https://registry.mcp-hub.info"
  timeout: 30s

# Local cache
cache:
  directory: "~/.mcp/cache"
  max_size: "5GB"
  ttl: "168h"  # 7 days

# Execution defaults
executor:
  timeout: "30m"

# Resource limits (always enforced, these are defaults)
resources:
  max_memory: "512MB"
  max_cpu: 2
  max_pids: 100
  max_fds: 256

# Security policy
policy:
  min_cert_level: 0        # Minimum certification level (0-3)
  min_score: 0             # Minimum security score (0-100)
  allowed_origins:         # Allowed origin types
    - official
    - verified
    - community
  cert_mode: "warn"        # strict | warn | disabled
  warning_threshold: 80    # LLM security warning score threshold

# Audit logging
audit:
  enabled: true
  file: "~/.mcp/audit.log"
  format: "json"

Registry Settings

Key	Type	Default	Description
`registry.url`	string	`https://registry.mcp-hub.info`	Registry endpoint URL
`registry.timeout`	duration	`30s`	HTTP timeout for registry requests

Cache Settings

Key	Type	Default	Description
`cache.directory`	path	`~/.mcp/cache`	Local cache directory
`cache.max_size`	string	`5GB`	Maximum cache size on disk
`cache.ttl`	duration	`168h`	Time-to-live for cached entries (7 days)

Executor Settings

Key	Type	Default	Description
`executor.timeout`	duration	`30m`	Default execution timeout

Resource Limits

Resource limits are always enforced to prevent runaway processes. These values set the defaults:

Key	Type	Default	Description
`resources.max_memory`	string	`512MB`	Maximum memory per MCP process
`resources.max_cpu`	integer	`2`	Maximum CPU cores
`resources.max_pids`	integer	`100`	Maximum number of child processes
`resources.max_fds`	integer	`256`	Maximum open file descriptors

Security Policy

Key	Type	Default	Description
`policy.min_cert_level`	integer	`0`	Minimum certification level (0-3)
`policy.min_score`	integer	`0`	Minimum security score (0-100)
`policy.allowed_origins`	list	`[official, verified, community]`	Allowed origin types
`policy.cert_mode`	string	`warn`	Enforcement mode: `strict`, `warn`, or `disabled`
`policy.warning_threshold`	integer	`80`	Security score below which LLM security warnings are injected into the MCP protocol when using `--trust`. See LLM Security Warnings.

See Security Policies for detailed policy configuration.

Audit Logging

Key	Type	Default	Description
`audit.enabled`	boolean	`true`	Enable audit logging
`audit.file`	path	`~/.mcp/audit.log`	Audit log file path
`audit.format`	string	`json`	Log format: `json` or `text`

Environment Variable Overrides

All configuration values can be overridden with environment variables using the MCP_ prefix:

Variable	Config Path	Description
`MCP_CONFIG`	–	Config file path
`MCP_REGISTRY_URL`	`registry.url`	Registry endpoint
`MCP_REGISTRY_TOKEN`	–	Auth token (alternative to `smcp login`)
`MCP_CACHE_DIR`	`cache.directory`	Cache directory
`MCP_LOG_LEVEL`	–	Log level (`debug`, `info`, `warn`, `error`)
`MCP_TIMEOUT`	`executor.timeout`	Default execution timeout

Priority Order

Configuration values are resolved in the following order, from highest to lowest priority:

CLI flags – Always take precedence
Environment variables – Override config file values
Config file – ~/.mcp/config.yaml or path from --config / MCP_CONFIG
Defaults – Built-in default values

Auth Token Storage

Authentication tokens are stored in:

~/.mcp/auth.json

This file is created by smcp login with 0600 permissions (owner read/write only). It contains registry tokens used to authenticate API requests.

You can also provide a token via the MCP_REGISTRY_TOKEN environment variable, which is useful for CI/CD environments where you do not want to run smcp login interactively.

Minimal Configuration

For most users, no configuration file is needed. The defaults connect to the public registry at registry.mcp-hub.info and apply sensible resource limits. Simply run:

smcp login
smcp run cr0hn/mcp-schrodinger@latest

Create a configuration file only when you need to customize policies, resource limits, or point to a private registry.