Configuration Deep Dive

The 1MCP Agent provides extensive configuration options for runtime behavior, transport settings, authentication, and more. This guide covers command-line flags and environment variables that control how the runtime and agent-facing commands operate.

For MCP server configuration (backend servers, environment management, process control), see the MCP Servers Reference.

Two Configuration Files

Keep backend inventory and 1MCP runtime settings in separate files. They are loaded together from the configuration directory, but they use different schemas.

• mcp.json contains mcpServers: the backend MCP inventory. A server uses type (stdio, http, sse, or streamableHttp) and disabled when it should not start.
• config.toml contains application settings such as authentication, async loading, logging, and runtime defaults. It does not contain mcpServers.

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "tags": ["files"]
    },
    "remote-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "disabled": false
    }
  }
}

# config.toml
[auth]
enabled = true

[asyncLoading]
enabled = true
batchNotifications = true
batchDelay = 250

CLI flags and their ONE_MCP_* environment-variable equivalents override these runtime settings for that process. Do not copy [auth] or [asyncLoading] into mcp.json, and do not put mcpServers in config.toml.

Configuration Methods

The agent supports three configuration methods, applied in this order of precedence:

1. Command-Line Flags: Highest priority when explicitly supplied
2. Environment Variables: ONE_MCP_* defaults for the process
3. Configuration File: Base configuration (covered in MCP Servers Reference)

---

Command-Line Options

All available command-line options and their corresponding environment variables:

Option (CLI)	Environment Variable	Description	Default
--transport, -t	ONE_MCP_TRANSPORT	Choose transport type ("stdio", "http", or "sse")	"http"
--config, -c	ONE_MCP_CONFIG	Use a specific config file
--config-dir, -d	ONE_MCP_CONFIG_DIR	Path to the config directory (overrides default config location)
--cli-session-cache-path	ONE_MCP_CLI_SESSION_CACHE_PATH	Path template for the run/inspect CLI session cache file, supports {pid} and {scope}
--port, -P	ONE_MCP_PORT	Change HTTP port	3050
--host, -H	ONE_MCP_HOST	Change HTTP host	localhost
--external-url, -u	ONE_MCP_EXTERNAL_URL	External URL for OAuth callbacks and public URLs (e.g., https://example.com)
--trust-proxy	ONE_MCP_TRUST_PROXY	Trust proxy configuration for client IP detection (boolean, IP, CIDR, preset)	"loopback"
--filter, -f	ONE_MCP_FILTER	Filter servers exposed by the runtime (simple comma-separated tags or advanced boolean logic)
--pagination, -p	ONE_MCP_PAGINATION	Enable pagination for client/server lists (boolean)	false
--enable-auth	ONE_MCP_ENABLE_AUTH	Enable authentication (OAuth 2.1)	false
--enable-scope-validation	ONE_MCP_ENABLE_SCOPE_VALIDATION	Enable tag-based scope validation (boolean)	true
--enable-enhanced-security	ONE_MCP_ENABLE_ENHANCED_SECURITY	Enable enhanced security middleware (boolean)	false
--session-ttl	ONE_MCP_SESSION_TTL	Session expiry time in minutes (number)	1440
--session-storage-path	ONE_MCP_SESSION_STORAGE_PATH	Custom session storage directory path (string)
--rate-limit-window	ONE_MCP_RATE_LIMIT_WINDOW	OAuth rate limit window in minutes (number)	15
--rate-limit-max	ONE_MCP_RATE_LIMIT_MAX	Maximum requests per OAuth rate limit window (number)	100
--enable-async-loading	ONE_MCP_ENABLE_ASYNC_LOADING	Enable asynchronous MCP server loading(boolean)	false
--async-max-concurrent-loads	ONE_MCP_ASYNC_MAX_CONCURRENT_LOADS	Maximum concurrent backend loads	5
--async-max-retries	ONE_MCP_ASYNC_MAX_RETRIES	Foreground retries after the initial attempt	3
--async-retry-delay	ONE_MCP_ASYNC_RETRY_DELAY	Initial exponential-backoff delay in milliseconds	2000
--async-background-retry	ONE_MCP_ASYNC_BACKGROUND_RETRY	Enable periodic retries for retryable backend failures	true
--async-background-retry-interval	ONE_MCP_ASYNC_BACKGROUND_RETRY_INTERVAL	Background retry interval in milliseconds	60000
--async-background-retry-max-servers	ONE_MCP_ASYNC_BACKGROUND_RETRY_MAX_SERVERS	Maximum failed backends selected per cycle	3
--enable-lazy-loading	ONE_MCP_ENABLE_LAZY_LOADING	Enable meta-tool exposure for progressive tool discovery (boolean)	false
--enable-config-reload	ONE_MCP_ENABLE_CONFIG_RELOAD	Enable configuration file hot-reload (boolean)	true
--config-reload-debounce	ONE_MCP_CONFIG_RELOAD_DEBOUNCE	Configuration reload debounce time in milliseconds (number)	500
--enable-env-substitution	ONE_MCP_ENABLE_ENV_SUBSTITUTION	Enable environment variable substitution in config files (boolean)	true
--enable-session-persistence	ONE_MCP_ENABLE_SESSION_PERSISTENCE	Enable HTTP session persistence (boolean)	true
--session-persist-requests	ONE_MCP_SESSION_PERSIST_REQUESTS	Session persistence request threshold (number)	100
--session-persist-interval	ONE_MCP_SESSION_PERSIST_INTERVAL	Session persistence interval in minutes (number)	5
--session-background-flush	ONE_MCP_SESSION_BACKGROUND_FLUSH	Session background flush interval in seconds (number)	60
--enable-client-notifications	ONE_MCP_ENABLE_CLIENT_NOTIFICATIONS	Enable real-time client notifications (boolean)	true
--enable-internal-tools	ONE_MCP_ENABLE_INTERNAL_TOOLS	Enable ALL MCP internal tools for AI assistants (boolean)	false
--internal-tools	ONE_MCP_INTERNAL_TOOLS	Enable specific internal tool categories (discovery,installation,management,safe)
--health-info-level	ONE_MCP_HEALTH_INFO_LEVEL	Health endpoint information detail level ("full", "basic", "minimal")	"minimal"
--log-level	ONE_MCP_LOG_LEVEL	Set the log level ("debug", "info", "warn", "error")	"info"
--log-file	ONE_MCP_LOG_FILE	Write logs to a file in addition to console (disables console logging only for stdio transport)
--help, -h		Show help

---

Configuration Categories

Transport Options

Control how the agent communicates with clients and backend servers.

--transport, -t <type>

• Values: stdio, http, sse (deprecated)
• Default: http
• Environment: ONE_MCP_TRANSPORT

Examples:

CLI Session Cache Path

The run and inspect commands keep a lightweight session cache file outside the config directory by default.

• Default: ${os.tmpdir()}/1mcp/.cli-session.{pid}.{scope}
• Environment: ONE_MCP_CLI_SESSION_CACHE_PATH
• Placeholders: {pid} resolves to the discovered 1mcp serve process PID when available; {scope} isolates the target URL and CLI context. For the built-in default path, 1MCP falls back to a stable server-specific token when no PID is available.

Example:

ONE_MCP_CLI_SESSION_CACHE_PATH=/tmp/1mcp/.cli-session.{pid}.{scope} npx -y @1mcp/agent run filesystem/read_file --args '{"path":"./README.md"}'

# HTTP transport (default)
npx -y @1mcp/agent --transport http

# Stdio transport for direct MCP client integration
npx -y @1mcp/agent --transport stdio

# Using environment variable
ONE_MCP_TRANSPORT=stdio npx -y @1mcp/agent

Network Configuration

Configure HTTP server settings for network access.

--port, -P <port>

• Default: 3050
• Environment: ONE_MCP_PORT

--host, -H <host>

• Default: localhost
• Environment: ONE_MCP_HOST

--external-url, -u <url>

• Purpose: External URL for OAuth callbacks and public URLs
• Environment: ONE_MCP_EXTERNAL_URL

Examples:

# Custom port and host
npx -y @1mcp/agent --port 3051 --host 0.0.0.0

# External URL for reverse proxy setups
npx -y @1mcp/agent --external-url https://mcp.example.com

# Environment variables for Docker
ONE_MCP_HOST=0.0.0.0 ONE_MCP_PORT=3051 npx -y @1mcp/agent

Configuration Management

Control configuration file location and loading behavior.

--config, -c <path>

• Purpose: Use a specific config file
• Environment: ONE_MCP_CONFIG

--config-dir, -d <path>

• Purpose: Path to the config directory (overrides default location)
• Environment: ONE_MCP_CONFIG_DIR

Examples:

# Use specific config file
npx -y @1mcp/agent --config ./my-config.json

# Use custom config directory
npx -y @1mcp/agent --config-dir ./project-config

# Environment variable for config directory
ONE_MCP_CONFIG_DIR=/opt/1mcp/config npx -y @1mcp/agent

Security Configuration

Authentication, authorization, and security features.

--enable-auth

• Purpose: Enable OAuth 2.1 authentication
• Default: false
• Environment: ONE_MCP_ENABLE_AUTH

--enable-scope-validation

• Purpose: Enable tag-based scope validation
• Default: true
• Environment: ONE_MCP_ENABLE_SCOPE_VALIDATION

--enable-enhanced-security

• Purpose: Enable enhanced security middleware
• Default: false
• Environment: ONE_MCP_ENABLE_ENHANCED_SECURITY

Session Management:

• --session-ttl <minutes>: Session expiry time (default: 1440)
• --session-storage-path <path>: Custom session storage directory
• --rate-limit-window <minutes>: OAuth rate limit window (default: 15)
• --rate-limit-max <requests>: Maximum requests per window (default: 100)

Examples:

# Enable authentication with enhanced security
npx -y @1mcp/agent --enable-auth --enable-enhanced-security

# Custom session configuration
npx -y @1mcp/agent \
  --enable-auth \
  --session-ttl 720 \
  --rate-limit-window 10 \
  --rate-limit-max 50

# Environment variables
ONE_MCP_ENABLE_AUTH=true \
ONE_MCP_ENABLE_ENHANCED_SECURITY=true \
npx -y @1mcp/agent

Network Security

Configure trust proxy settings for reverse proxy deployments.

--trust-proxy <config>

• Default: "loopback"
• Environment: ONE_MCP_TRUST_PROXY
• Values:
  • true: Trust all proxies
  • false: Trust no proxies
  • IP address: Trust specific IP
  • CIDR: Trust IP range
  • "loopback": Trust loopback addresses only

Examples:

# Trust all proxies (CDN/Cloudflare)
npx -y @1mcp/agent --trust-proxy true

# Trust specific proxy IP
npx -y @1mcp/agent --trust-proxy 192.168.1.100

# Trust IP range
npx -y @1mcp/agent --trust-proxy 10.0.0.0/8

For detailed trust proxy configuration, see the Trust Proxy Reference.

For the recommended public HTTPS path with Caddy, Admin Console access, and local CLI Runtime Target setup, see Cloud Deployment with Caddy.

Upstream OAuth authority

HTTP and SSE upstreams use the same OAuth authority rules in both protocol eras. Configure registration and issuer selection in the server's oauth object:

{
  "mcpServers": {
    "reports": {
      "type": "http",
      "url": "https://reports.example/mcp",
      "oauth": {
        "issuer": "https://login.example",
        "clientId": "registered-client-id",
        "redirectUrl": "https://gateway.example/oauth/callback/reports",
        "scopes": ["reports.read"]
      }
    }
  }
}

issuer is an exact approved issuer identifier, including its trailing slash. Without a pin, a compatible previous approval or the sole advertised issuer is selected; an ambiguous list requires configuring issuer. Configured clientId/clientSecret take precedence over persisted dynamic registration. If no client is configured, clientMetadataUrl enables advertised HTTPS Client ID Metadata Documents, followed by advertised Dynamic Client Registration. autoRegister: false disables DCR. Only the legacy upstream adapter permits inferred same-origin registration when authorization-server metadata is absent. Authentication failures never authorize an era downgrade.

Credentials belong to the Runtime Scope, configured source, structured upstream destination, exact issuer and resource, and security-relevant configuration. Changing those inputs requires fresh authorization. Template instances remain separate unless they deliberately use the same oauth.credentialAuthority; sharing also requires identical destination, registration, scopes, and registered redirect URI. This setting does not grant an incoming client permission to use the upstream: existing per-operation authorization remains required.

Each authorization attempt has its own state and PKCE verifier, expires after fifteen minutes, survives restart, and can be consumed once. At most 32 attempt records are retained per authority during that window. Start authorization again after an expired, rejected, or interrupted callback. Old server-name-keyed credentials are quarantined in owner-only client storage and are never automatically promoted; authorize again after upgrading. Quarantine data remains protected rollback material and is not included in configuration exports. Restoring it does not make unbound credentials eligible.

OAuth metadata, registration, and token responses are limited to 1 MiB and ten seconds total. OAuth redirects are rejected. If the configured MCP resource redirects (for example, /mcp to /mcp/), 1MCP reports that the upstream URL must be configured to the final destination; it does not forward credentials through the redirect. Discovered endpoints must use public HTTPS by default. The exact explicitly configured local-IP or localhost resource/issuer origin permits HTTP/private destinations; oauth.privateNetworkOrigins separately permits private destinations for listed HTTPS origins. A separate local authorization server must be explicitly pinned with oauth.issuer; advertising another localhost port or address does not approve it. The exact configured MCP resource route and an accepted same-origin SSE message endpoint retain operator-approved HTTP/private-network access; this does not approve discovered OAuth endpoints. For server network requests, each DNS answer is checked and pinned into that request's actual connection. Validated answers may rotate between requests. Active authority and credential records renew their thirty-day storage lifetime; expired idle records still require fresh authorization. Endpoint URLs and scopes are validated before credentials are sent. A Resource Indicator may identify a same-origin parent path (for example, /api for /api/mcp), with matching query parameters and no fragment. The selected Resource Indicator is retained as the token audience; credentials remain bound to the exact configured upstream route. Upstream resource headers are not forwarded to discovery, registration, or token endpoints. MCP SSE streams retain their normal streaming lifetime. Browser authorization navigation uses the exact validated advertised HTTPS URL (with the configured local-origin exception); the browser controls its own DNS and network connection, which 1MCP does not pin.

Access tokens may be opaque. 1MCP binds the token exchange and Resource Indicator to validated authority; it does not decode arbitrary token claims and claim to verify their signatures. The protected resource remains responsible for cryptographic access-token validation.

Explicit insecure metadata compatibility

Prefer fixing the provider's metadata. If that is not possible, set oauth.insecureAllowIncompleteMetadata: true for that server. This insecure, default-off option works for both public and private providers. It fills an absent issuer from the authorization-server discovery context and resolves relative authorization, token, registration and JWKS endpoints against that issuer. It also permits same-origin authorization-server discovery when protected-resource metadata is unavailable. It does not replace an explicit mismatched issuer, invent missing required endpoints, accept cross-origin relative URLs, or disable resource, redirect, TLS or credential validation.

Private DNS destinations require separate approval. Set oauth.privateNetworkOrigins to exact trusted HTTPS origins (scheme, host and optional port; no credentials, wildcards, paths, queries or fragments). A trailing slash is accepted. This does not permit HTTP for private hostnames or approve another hostname/port advertised by discovery. Avoid placing either exception in serverDefaults.oauth, where it would be inherited by servers without their own OAuth object.

{
  "mcpServers": {
    "home-assistant": {
      "type": "http",
      "url": "https://ha.example/api/mcp",
      "oauth": {
        "insecureAllowIncompleteMetadata": true,
        "privateNetworkOrigins": ["https://ha.example"],
        "clientId": "http://127.0.0.1:3050/",
        "redirectUrl": "http://127.0.0.1:3050/oauth/callback/home-assistant",
        "autoRegister": false
      }
    }
  }
}

The Home Assistant example uses its URL-based client identity, with a matching callback origin, because it does not support Dynamic Client Registration. Adjust the client ID and callback together if your local 1MCP port or origin differs. Other providers may require a registered client ID or a published clientMetadataUrl; disabling registration alone does not supply an identity.

For a public destination, omit privateNetworkOrigins. With complete metadata, omit insecureAllowIncompleteMetadata. Changing either setting requires fresh authorization. These options do not guarantee provider consent.

The private_destination_blocked diagnostic means DNS resolved to a private address without approval; invalid_metadata means the provider document failed format validation; authority_mismatch means authority validation failed.

Native OAuth credential storage

File storage remains the default, with owner-only files and directories, permission checks, and symlink protections. To move inbound and upstream OAuth security records to the OS credential store, set this in config.toml and restart the selected Runtime Scope:

[auth]
credentialStore = "native"

--credential-store native or ONE_MCP_CREDENTIAL_STORE=native overrides the file setting for the process. The setting applies to the whole Runtime Scope and is captured at startup; editing it does not switch an active runtime. One policy protects both inbound and upstream OAuth. auth.enabled controls only whether clients connecting to 1MCP must authenticate; it does not disable upstream credential protection. Admin credentials and sessions remain independently authorized and file-backed.

Install the platform's Docker credential helper on the runtime's trusted executable search path:

Platform	Required helper	Prerequisites
macOS	docker-credential-osxkeychain	An accessible, unlocked Keychain
Windows	docker-credential-wincred.exe	Credential Manager access for the runtime account
Linux	docker-credential-secretservice	A user D-Bus session and an unlocked Secret Service collection, such as GNOME Keyring

Docker itself is not required. These external helpers are required for both npm and standalone installations; 1MCP does not install them automatically. Headless services and containers must supply an accessible Secret Service session explicitly. Missing helpers, locked stores, denied operations, malformed responses, or failed persistence fail affected OAuth operations closed with an actionable, secret-safe error. Inbound authentication is never bypassed and tokens are not issued from uncertain state. There is no automatic plaintext fallback; independent Admin access and unrelated backends remain usable. A running process does not prove that an affected credential domain is ready or its migration complete.

On native startup, 1MCP automatically protects existing eligible inbound and upstream records. Inbound records include access-token sessions, authorization codes, pending consent requests, client registrations and their secrets, refresh-token families, and digest lookup records. Whole records and managed temporary/recovery copies are protected, including arbitrary secret-bearing extensions; inbound refresh tokens remain digest-only. Valid sessions and registrations retain their expiry, client/resource/scope binding, consent state, single-use codes, refresh-family lineage, and revocation. Upstream protection includes token and registration data, pending PKCE attempts, and managed legacy quarantine/rollback records. It verifies the native destination before cleaning the plaintext source. Interrupted migration or incomplete plaintext cleanup retains recovery references, remains incomplete, and can resume after the store is unlocked and the runtime restarted. Malformed authoritative data is preserved for recovery and blocks affected operations; stale remnants are never fallback credentials or allowed to replace newer state. Unbound legacy credentials still require authorization; moving them does not establish authority. Storage identities preserve Runtime Scope, credential-domain, inbound identity, and configured upstream authority isolation. Different Runtime Scopes cannot share the same upstream credential directory; startup rejects that configuration.

Earlier native-store releases protected upstream OAuth only. Upgrading an already-native Runtime Scope automatically extends that policy to inbound OAuth at startup; satisfy the same helper/store prerequisites before upgrading. There is no separate inbound switch or automatic downgrade.

Switching to file requires restart and fresh authorization in both directions unless records were explicitly exported. It does not silently export native secrets or reuse leftover migration sources. For deliberate reverse migration, stop the runtime and use auth export-oauth-credentials, which exports both inbound and upstream OAuth. Use auth export-upstream-credentials to export upstream records only. It displays every plaintext destination, including current and legacy layouts, before requiring interactive or explicit noninteractive confirmation. Admin records are excluded. Repeated export preserves newer credentials and reports unfinished cleanup.

Successful migration removes managed plaintext copies, including managed recovery remnants; it does not securely erase historical backups, external copies, filesystem snapshots, or deleted disk blocks. Review and protect those separately. OS storage improves at-rest handling but is not a universal defense against arbitrary code running as the same OS user.

Server Filtering

Control which backend MCP servers the runtime exposes.

--filter, -f <expression>

• Purpose: Filter runtime server exposure with simple OR syntax or advanced boolean logic
• Environment: ONE_MCP_FILTER

Filter Syntax:

• tag1,tag2: OR logic (either tag)
• tag1+tag2: AND logic (both tags)
• (tag1,tag2)+tag3: Complex expressions
• tag1 and tag2 and not tag3: Natural language syntax

Examples:

# Simple OR filtering
npx -y @1mcp/agent --filter "network,filesystem"

# Advanced filtering
npx -y @1mcp/agent --filter "network+api"
npx -y @1mcp/agent --filter "(web,api)+production-test"
npx -y @1mcp/agent --filter "web and api and not test"

# Environment variables
ONE_MCP_FILTER="network+api" npx -y @1mcp/agent

For client-side narrowing after the runtime is already running, use --preset, --tags, or --tag-filter with instructions, inspect, and run, or use proxy --preset/--filter/--tags for the maximum-compatibility stdio path.

Internal Tools Options

Control MCP internal tools exposure for AI assistants.

--enable-internal-tools

• Purpose: Enable ALL MCP internal tools for AI assistants
• Default: false
• Environment: ONE_MCP_ENABLE_INTERNAL_TOOLS

--internal-tools <categories>

• Purpose: Enable specific internal tool categories
• Values: Comma-separated categories: discovery,installation,management,safe
• Default: No categories enabled
• Environment: ONE_MCP_INTERNAL_TOOLS

Categories:

• discovery - Tools for discovering MCP servers (mcpsearch, mcp_registry*)
• installation - Tools for installing/updating/removing servers (mcp_install, mcp_update, mcp_uninstall)
• management - Tools for managing server lifecycle (mcp_enable, mcp_disable, mcp_list, mcp_status, mcp_reload, mcp_edit)
• safe - Read-only tools only (subset of discovery and management)

Examples:

# Enable ALL internal tools
npx -y @1mcp/agent --enable-internal-tools

# Enable only discovery and management tools
npx -y @1mcp/agent --internal-tools "discovery,management"

# Enable only safe (read-only) tools
npx -y @1mcp/agent --internal-tools "safe"

# Environment variables
ONE_MCP_ENABLE_INTERNAL_TOOLS=true npx -y @1mcp/agent

ONE_MCP_INTERNAL_TOOLS="discovery,management" npx -y @1mcp/agent

Important: Internal tools are different from CLI commands. CLI commands are for human users, while internal tools are MCP protocol tools that AI assistants can use to automate server management tasks. For detailed information about available internal tools, see the Internal Tools Reference.

Performance Options

Control performance and resource usage behavior.

--enable-async-loading

• Purpose: Enable asynchronous MCP server loading
• Default: false
• Environment: ONE_MCP_ENABLE_ASYNC_LOADING

--pagination, -p

• Purpose: Enable pagination for client/server lists
• Default: false
• Environment: ONE_MCP_PAGINATION

Examples:

# Enable async loading for faster startup
npx -y @1mcp/agent --enable-async-loading

# Enable pagination for large server lists
npx -y @1mcp/agent --pagination

# Environment variables
ONE_MCP_ENABLE_ASYNC_LOADING=true \
ONE_MCP_PAGINATION=true \
npx -y @1mcp/agent

Startup-captured operational policies

The following settings are validated when an Aggregated Runtime starts. Editing config.toml does not replace active limiters, retry timers, loading concurrency, journal retention, or Template Instance Pool limits. Restart the Runtime Scope to activate a change.

[asyncLoading]
maxConcurrentLoads = 5
maxRetries = 3
retryDelay = 2000

[asyncLoading.backgroundRetry]
enabled = true
interval = 60000
maxServersPerCycle = 3

[admin.rateLimit.login]
windowSeconds = 900
maxRequests = 30
maxFailedAttempts = 5

[admin.rateLimit.status]
windowSeconds = 60
maxRequests = 120

[admin.rateLimit.sensitive]
windowSeconds = 900
maxRequests = 10

[health.rateLimit]
windowSeconds = 300
maxRequests = 200

[admin.audit]
retentionDays = 30

[templateSettings.pool]
maxInstancesPerTemplate = 50
maxTotalInstances = 100
idleTimeout = 300000
cleanupInterval = 30000

Async CLI values override matching ONE_MCP_* values, which override config.toml. maxRetries = 0 means one initial attempt only; retryDelay = 0 keeps retries finite but removes the delay. The background interval is at least 1000 ms. A backend's connectionTimeout, legacy backend timeout, then 30000 ms fallback is the only connection-attempt deadline. Deprecated asyncLoading.minServers and asyncLoading.timeout remain warning-only no-ops.

Admin and health limits cannot be disabled. Windows accept 1-86400 seconds, request limits 1-100000, failed login attempts 1-100, and audit retention 1-3650 days. These process-local controls are separate from OAuth --rate-limit-* settings. Audit retention applies only to sanitized audit facts; completed/failed idempotency replay remains 24 hours and ambiguous state_unknown outcomes remain 30 days.

Template pool values are milliseconds where applicable. maxInstancesPerTemplate accepts 0-10000, where zero is unlimited within the mandatory global bound. maxTotalInstances accepts 1-10000. idleTimeout accepts 0-2147483647, where zero is immediately cleanup-eligible. cleanupInterval accepts 1000-3600000. Per-template template.maxInstances and template.idleTimeout override only their corresponding fallbacks.

Lazy Loading

Lazy loading is opt-in stable tool-surface compatibility for clients that support progressive discovery. With it disabled (the default), 1MCP exposes every backend tool directly. With it enabled, the backend tool surface is tool_list, tool_schema, and tool_invoke; clients discover schemas and invoke backend tools through those meta-tools. Internal management tools explicitly enabled by the operator remain directly exposed with the 1mcp namespace.

This reduces the initial tool-schema payload. It does not reduce backend connections or processes, make synchronous startup bind earlier, or repair orphaned proxy processes. Do not enable it together with async loading by default: choose each setting for its own runtime behavior. See #392 for the request-time visibility contract that lets a matching late-ready server appear after async capability publication without reconnecting.

Enable it for one launch:

1mcp serve --enable-lazy-loading

Or make it persistent in config.toml and restart the process:

[lazyLoading]
enabled = true

The CLI flag takes precedence over config.toml. Legacy --lazy-mode, [lazyLoading].mode, and --lazy-direct-expose inputs are accepted temporarily but ignored with a deprecation warning; enabled is the only working switch.

Template context trust

Template context can control executable template fields, so the runtime verifies it independently from transport connectivity and OAuth. The default is local-first verification:

[templateContext]
trust = "verified"

The equivalent CLI option is --template-context-trust verified; CLI input takes precedence over config.toml.

Mode	Behavior
verified	First-party local context with a Runtime Scope proof renders templates. Unsigned clients use static servers only.
disabled	Request context never renders templates.
legacy	Unsigned local or remote context renders templates, reopening control of template command, args, cwd, and env.

Using legacy with a non-loopback HTTP host also requires --confirm-untrusted-template-context. GET REST clients keep the existing base64url context query format. The runtime decodes it into a structured redacted audit entry and never prints the raw base64 value or proof signature in general request logs.

Configuration Reload

Control configuration file hot-reload behavior for seamless updates.

With hot reload enabled, setting disabled: true on a static server in mcp.json retains its definition and unloads its runtime connection. Its tools, resources, and prompts become unavailable; an owned stdio child is stopped, while independently hosted HTTP/SSE services keep running. Setting disabled: false loads the latest configuration without restarting 1MCP. Initially disabled servers remain unloaded. Client capability-change notifications follow --enable-client-notifications.

--enable-config-reload

• Purpose: Enable configuration file hot-reload
• Default: true
• Environment: ONE_MCP_ENABLE_CONFIG_RELOAD

--config-reload-debounce <milliseconds>

• Purpose: Debounce time for configuration reload to prevent excessive reloads
• Default: 500
• Environment: ONE_MCP_CONFIG_RELOAD_DEBOUNCE

Examples:

# Enable config reload with custom debounce
npx -y @1mcp/agent --enable-config-reload --config-reload-debounce 1000

# Disable config reload (useful for production stability)
npx -y @1mcp/agent --enable-config-reload false

# Environment variables
ONE_MCP_ENABLE_CONFIG_RELOAD=true \
ONE_MCP_CONFIG_RELOAD_DEBOUNCE=200 \
npx -y @1mcp/agent

Environment Variable Substitution

Enable dynamic configuration using environment variables in config files.

--enable-env-substitution

• Purpose: Enable environment variable substitution in configuration files
• Default: true
• Environment: ONE_MCP_ENABLE_ENV_SUBSTITUTION

Usage:

When enabled, you can use ${VAR_NAME} or $VAR_NAME syntax in your JSON configuration files:

{
  "servers": [
    {
      "name": "database",
      "command": "python",
      "args": ["${DB_SERVER_PATH}", "--port", "$DB_PORT"]
    }
  ],
  "auth": {
    "sessionStoragePath": "${SESSION_STORAGE_DIR}"
  }
}

Examples:

# Enable environment substitution (default)
npx -y @1mcp/agent --enable-env-substitution

# Disable environment substitution
npx -y @1mcp/agent --enable-env-substitution false

# Environment variables
DB_SERVER_PATH=/opt/db-server \
DB_PORT=5432 \
SESSION_STORAGE_DIR=/var/lib/1mcp/sessions \
ONE_MCP_ENABLE_ENV_SUBSTITUTION=true \
npx -y @1mcp/agent

Session Persistence

Control HTTP session persistence for improved reliability across server restarts.

With authentication enabled, older Streamable HTTP sessions without an authorization binding require reinitialization after upgrading. Reconnect without an mcp-session-id to create a fresh session. Renewed tokens can continue a session when their client, resource, and scope set match the original grant. Disabling scope validation keeps authentication and session ownership checks enabled.

--enable-session-persistence

• Purpose: Enable HTTP session persistence
• Default: true
• Environment: ONE_MCP_ENABLE_SESSION_PERSISTENCE

--session-persist-requests <number>

• Purpose: Number of requests before triggering session persistence
• Default: 100
• Environment: ONE_MCP_SESSION_PERSIST_REQUESTS

--session-persist-interval <minutes>

• Purpose: Time interval in minutes for automatic session persistence
• Default: 5
• Environment: ONE_MCP_SESSION_PERSIST_INTERVAL

--session-background-flush <seconds>

• Purpose: Background flush interval in seconds for session persistence
• Default: 60
• Environment: ONE_MCP_SESSION_BACKGROUND_FLUSH

Examples:

# Enable session persistence with default settings
npx -y @1mcp/agent --enable-session-persistence

# Custom session persistence settings
npx -y @1mcp/agent \
  --enable-session-persistence \
  --session-persist-requests 50 \
  --session-persist-interval 10 \
  --session-background-flush 30

# Disable session persistence
npx -y @1mcp/agent --enable-session-persistence false

# Environment variables
ONE_MCP_ENABLE_SESSION_PERSISTENCE=true \
ONE_MCP_SESSION_PERSIST_REQUESTS=200 \
ONE_MCP_SESSION_PERSIST_INTERVAL=15 \
npx -y @1mcp/agent

Client Notifications

Control real-time notifications to connected clients about capability changes.

--enable-client-notifications

• Purpose: Enable real-time client notifications
• Default: true
• Environment: ONE_MCP_ENABLE_CLIENT_NOTIFICATIONS

Examples:

# Enable client notifications (default)
npx -y @1mcp/agent --enable-client-notifications

# Disable client notifications
npx -y @1mcp/agent --enable-client-notifications false

# Environment variable
ONE_MCP_ENABLE_CLIENT_NOTIFICATIONS=true npx -y @1mcp/agent

Monitoring and Health

Configure health check endpoints and information detail levels.

--health-info-level <level>

• Values: "full", "basic", "minimal"
• Default: "minimal"
• Environment: ONE_MCP_HEALTH_INFO_LEVEL

Levels:

• minimal: Basic health status only
• basic: Health status with basic metrics
• full: Complete system information and metrics

Examples:

# Full health information for monitoring
npx -y @1mcp/agent --health-info-level full

# Basic health information
npx -y @1mcp/agent --health-info-level basic

# Environment variable
ONE_MCP_HEALTH_INFO_LEVEL=full npx -y @1mcp/agent

For detailed health check information, see the Health Check Reference.

Logging Configuration

Control log output, levels, and destinations.

--log-level <level>

• Values: "debug", "info", "warn", "error"
• Default: "info"
• Environment: ONE_MCP_LOG_LEVEL

--log-file <path>

• Purpose: Write logs to file in addition to console
• Note: Disables console logging only for stdio transport
• Environment: ONE_MCP_LOG_FILE

Examples:

# Debug logging
npx -y @1mcp/agent --log-level debug

# Log to file
npx -y @1mcp/agent --log-file /var/log/1mcp.log

# Combined logging configuration
npx -y @1mcp/agent --log-level debug --log-file app.log

# Environment variables
ONE_MCP_LOG_LEVEL=debug npx -y @1mcp/agent
ONE_MCP_LOG_FILE=/var/log/1mcp.log npx -y @1mcp/agent

Migration from Legacy LOG_LEVEL: The legacy LOG_LEVEL environment variable is still supported but deprecated:

# ⚠️  Deprecated (shows warning)
LOG_LEVEL=debug npx -y @1mcp/agent

# ✅ Recommended
ONE_MCP_LOG_LEVEL=debug npx -y @1mcp/agent
# or
npx -y @1mcp/agent --log-level debug

---

Environment Variables Reference

All environment variables are prefixed with ONE_MCP_ and override both configuration file and CLI settings:

• ONE_MCP_TRANSPORT
• ONE_MCP_CONFIG
• ONE_MCP_CONFIG_DIR
• ONE_MCP_PORT
• ONE_MCP_HOST
• ONE_MCP_EXTERNAL_URL
• ONE_MCP_TRUST_PROXY
• ONE_MCP_FILTER
• ONE_MCP_PAGINATION
• ONE_MCP_ENABLE_AUTH
• ONE_MCP_ENABLE_SCOPE_VALIDATION
• ONE_MCP_ENABLE_ENHANCED_SECURITY
• ONE_MCP_SESSION_TTL
• ONE_MCP_SESSION_STORAGE_PATH
• ONE_MCP_RATE_LIMIT_WINDOW
• ONE_MCP_RATE_LIMIT_MAX
• ONE_MCP_ENABLE_ASYNC_LOADING
• ONE_MCP_ENABLE_CONFIG_RELOAD
• ONE_MCP_CONFIG_RELOAD_DEBOUNCE
• ONE_MCP_ENABLE_ENV_SUBSTITUTION
• ONE_MCP_ENABLE_SESSION_PERSISTENCE
• ONE_MCP_SESSION_PERSIST_REQUESTS
• ONE_MCP_SESSION_PERSIST_INTERVAL
• ONE_MCP_SESSION_BACKGROUND_FLUSH
• ONE_MCP_ENABLE_CLIENT_NOTIFICATIONS
• ONE_MCP_HEALTH_INFO_LEVEL
• ONE_MCP_LOG_LEVEL
• ONE_MCP_LOG_FILE

---

Configuration Examples

Development Setup

# Development with debug logging and full health info
npx -y @1mcp/agent \
  --log-level debug \
  --health-info-level full \
  --enable-async-loading \
  --enable-config-reload

# Environment variables for development
ONE_MCP_LOG_LEVEL=debug \
ONE_MCP_HEALTH_INFO_LEVEL=full \
ONE_MCP_ENABLE_ASYNC_LOADING=true \
ONE_MCP_ENABLE_CONFIG_RELOAD=true \
npx -y @1mcp/agent

Production Deployment

# Production HTTP server with authentication
npx -y @1mcp/agent \
  --host 0.0.0.0 \
  --port 3051 \
  --enable-auth \
  --enable-enhanced-security \
  --trust-proxy true \
  --external-url https://mcp.yourdomain.com \
  --enable-session-persistence \
  --session-persist-requests 200 \
  --session-persist-interval 10

# Docker environment variables
docker run -p 3051:3051 \
  -e ONE_MCP_HOST=0.0.0.0 \
  -e ONE_MCP_PORT=3051 \
  -e ONE_MCP_ENABLE_AUTH=true \
  -e ONE_MCP_ENABLE_ENHANCED_SECURITY=true \
  -e ONE_MCP_TRUST_PROXY=true \
  -e ONE_MCP_EXTERNAL_URL=https://mcp.yourdomain.com \
  -e ONE_MCP_ENABLE_SESSION_PERSISTENCE=true \
  -e ONE_MCP_SESSION_PERSIST_REQUESTS=200 \
  -e ONE_MCP_SESSION_PERSIST_INTERVAL=10 \
  ghcr.io/1mcp-app/agent

Filtered Server Access

# Only network-capable servers
npx -y @1mcp/agent --filter "network"

# Complex filtering: (web OR api) AND production, NOT test
npx -y @1mcp/agent --filter "(web,api)+production-test"

# Natural language filtering
npx -y @1mcp/agent --filter "api and database and not test"

Advanced Feature Configuration

# Full feature-enabled configuration with environment substitution
API_KEY="${API_KEY}" \
DB_CONNECTION="${DATABASE_URL}" \
npx -y @1mcp/agent \
  --enable-config-reload \
  --config-reload-debounce 1000 \
  --enable-env-substitution \
  --enable-session-persistence \
  --session-persist-requests 150 \
  --session-persist-interval 8 \
  --enable-client-notifications \
  --log-level info

# Configuration reload only (disable other new features for stability)
npx -y @1mcp/agent \
  --enable-config-reload \
  --config-reload-debounce 2000 \
  --enable-env-substitution false \
  --enable-session-persistence false \
  --enable-client-notifications false

# Minimal configuration for high-performance environments
npx -y @1mcp/agent \
  --enable-config-reload false \
  --enable-env-substitution true \
  --enable-session-persistence false \
  --enable-client-notifications false \
  --log-level warn

---

See Also

• MCP Servers Reference - Backend server configuration
• Serve Command Reference - Command-line usage examples
• Trust Proxy Guide - Reverse proxy configuration
• Cloud Deployment with Caddy - Public HTTPS deployment path
• Health Check Reference - Monitoring and health endpoints
• Security Guide - Security best practices