Configuration System

RMCP includes a comprehensive configuration management system that supports multiple configuration sources with a clear priority order.

Configuration Sources (Priority Order)

  1. Command-line arguments (highest priority)

  2. Environment variables (RMCP_* prefix)

  3. User config file (~/.rmcp/config.json)

  4. System config file (/etc/rmcp/config.json)

  5. Built-in defaults (lowest priority)

Development Configuration

Environment Variables

# Environment variables for development
export RMCP_LOG_LEVEL=DEBUG
export RMCP_HTTP_PORT=9000
export RMCP_R_TIMEOUT=300

Configuration File

# Configuration file for development
echo '{"debug": true, "logging": {"level": "DEBUG"}}' > ~/.rmcp/config.json

CLI Options

# CLI options override everything
uv run rmcp --debug --config custom.json start

Docker Configuration

Environment Variables in Docker

docker run -e RMCP_HTTP_HOST=0.0.0.0 -e RMCP_HTTP_PORT=8000 rmcp:latest

Mount Configuration File

docker run -v $(pwd)/config.json:/etc/rmcp/config.json rmcp:latest

Configuration Examples

Production Configuration

{
  "debug": false,
  "logging": {
    "level": "INFO",
    "format": "json"
  },
  "http": {
    "host": "0.0.0.0",
    "port": 8000,
    "cors_origins": ["https://yourdomain.com"]
  },
  "r": {
    "timeout": 300,
    "memory_limit": "2GB"
  }
}

High-Performance Configuration

{
  "r": {
    "timeout": 600,
    "memory_limit": "8GB",
    "parallel_workers": 4
  },
  "http": {
    "workers": 8,
    "max_connections": 1000
  }
}

Configuration API Documentation

For complete configuration options and validation, see the auto-generated API documentation:

Configuration data models for RMCP.

This module defines the complete configuration structure for RMCP with type hints, defaults, and validation. Configuration values are resolved in hierarchical order:

  1. Command-line arguments (highest priority)

  2. Environment variables (RMCP_* prefix)

  3. User configuration file (~/.rmcp/config.json)

  4. System configuration file (/etc/rmcp/config.json)

  5. Built-in defaults (lowest priority)

Examples

Environment variable configuration:

export RMCP_HTTP_HOST=0.0.0.0
export RMCP_HTTP_PORT=9000
export RMCP_R_TIMEOUT=180

Configuration file (~/.rmcp/config.json):

{
  "http": {"host": "0.0.0.0", "port": 9000},
  "r": {"timeout": 180, "max_sessions": 20},
  "logging": {"level": "DEBUG"}
}

Command-line override:

rmcp --config custom.json --debug start
class rmcp.config.models.HTTPConfig(host: str = 'localhost', port: int = 8000, ssl_keyfile: str | None = None, ssl_certfile: str | None = None, ssl_keyfile_password: str | None = None, cors_origins: list[str | ~typing.Literal['*']] = <factory>)[source]

Bases: object

HTTP transport configuration.

Controls the HTTP server behavior for RMCP when running in HTTP mode.

Environment Variables:

  • RMCP_HTTP_HOST - Server binding address

  • RMCP_HTTP_PORT - Server port number

  • RMCP_HTTP_CORS_ORIGINS - Allowed CORS origins (comma-separated)

  • RMCP_HTTP_SSL_KEYFILE - SSL private key file path

  • RMCP_HTTP_SSL_CERTFILE - SSL certificate file path

Security Considerations:

  • Default binding to localhost for security

  • Set host="0.0.0.0" for remote access (implement authentication)

  • Configure cors_origins appropriately for web clients

  • SSL files must both be provided if either is specified

Examples

Development configuration:

http = HTTPConfig(
    host="localhost",
    port=8000
)

Production with SSL:

http = HTTPConfig(
    host="0.0.0.0",
    port=443,
    ssl_keyfile="/etc/ssl/private/rmcp.key",
    ssl_certfile="/etc/ssl/certs/rmcp.crt",
    cors_origins=["https://myapp.example.com"]
)
host: str

localhost for security. Use 0.0.0.0 for remote access.

Type:

Server binding address. Default

port: int

Server port number. Must be between 1-65535.

ssl_keyfile: str | None

SSL private key file path. Required if ssl_certfile is specified.

ssl_certfile: str | None

SSL certificate file path. Required if ssl_keyfile is specified.

ssl_keyfile_password: str | None

SSL private key password if the key file is encrypted.

cors_origins: list[str | Literal['*']]

Allowed CORS origins for cross-origin requests. Supports wildcards.

__init__(host: str = 'localhost', port: int = 8000, ssl_keyfile: str | None = None, ssl_certfile: str | None = None, ssl_keyfile_password: str | None = None, cors_origins: list[str | ~typing.Literal['*']] = <factory>) → None
class rmcp.config.models.RConfig(timeout: int = 120, session_timeout: int = 3600, max_sessions: int = 10, binary_path: str | None = None, version_check_timeout: int = 30)[source]

Bases: object

R process configuration.

Controls R process execution, session management, and resource limits.

Environment Variables:

  • RMCP_R_TIMEOUT - R script execution timeout (seconds)

  • RMCP_R_SESSION_TIMEOUT - R session lifetime (seconds)

  • RMCP_R_MAX_SESSIONS - Maximum concurrent R sessions

  • RMCP_R_BINARY_PATH - Custom R binary path

  • RMCP_R_VERSION_CHECK_TIMEOUT - R version check timeout

Resource Considerations:

  • Limit max_sessions based on available memory (R sessions consume ~100-200MB each)

  • Set reasonable timeout to prevent runaway processes

  • Use session_timeout to free resources from idle sessions

Examples

Development configuration:

r = RConfig(
    timeout=300,
    max_sessions=5
)

Production configuration:

r = RConfig(
    timeout=120,
    session_timeout=1800,
    max_sessions=50,
    binary_path="/usr/local/bin/R"
)
timeout: int

R script execution timeout in seconds. Prevents runaway processes.

session_timeout: int

R session lifetime in seconds. Sessions are cleaned up after this time.

max_sessions: int

Maximum concurrent R sessions. Limit based on available memory.

binary_path: str | None

Custom R binary path. Auto-detected if None.

version_check_timeout: int

R version check timeout in seconds during startup.

__init__(timeout: int = 120, session_timeout: int = 3600, max_sessions: int = 10, binary_path: str | None = None, version_check_timeout: int = 30) → None
class rmcp.config.models.SecurityConfig(vfs_max_file_size: int = 52428800, vfs_allowed_paths: list[str] = <factory>, vfs_read_only: bool = True, vfs_allowed_mime_types: list[str] = <factory>)[source]

Bases: object

Security and filesystem configuration.

Controls Virtual File System (VFS) security boundaries and access controls.

Environment Variables:

  • RMCP_VFS_MAX_FILE_SIZE - Maximum file size in bytes

  • RMCP_VFS_ALLOWED_PATHS - Additional allowed paths (comma-separated)

  • RMCP_VFS_READ_ONLY - Enable read-only mode (true/false)

Security Considerations:

  • Keep vfs_read_only=True in production to prevent file modification

  • Restrict vfs_allowed_paths to necessary directories only

  • Set appropriate vfs_max_file_size limits to prevent resource exhaustion

  • Only trusted file types are allowed by default

Examples

Production security (read-only):

security = SecurityConfig(
    vfs_max_file_size=104857600,  # 100MB
    vfs_read_only=True,
    vfs_allowed_paths=["/data/readonly"]
)

Development (write access):

security = SecurityConfig(
    vfs_read_only=False,
    vfs_allowed_paths=["/tmp", "/home/user/datasets"]
)
vfs_max_file_size: int

50MB.

Type:

Maximum file size for VFS operations in bytes. Default

vfs_allowed_paths: list[str]

Additional filesystem paths accessible via VFS. Empty = temp directory only.

vfs_read_only: bool

Enable VFS read-only mode. Prevents file modification in production.

vfs_allowed_mime_types: list[str]

Allowed MIME types for file operations. Only trusted formats by default.

__init__(vfs_max_file_size: int = 52428800, vfs_allowed_paths: list[str] = <factory>, vfs_read_only: bool = True, vfs_allowed_mime_types: list[str] = <factory>) → None
class rmcp.config.models.PerformanceConfig(threadpool_max_workers: int = 2, callback_timeout: int = 300, process_cleanup_timeout: int = 5)[source]

Bases: object

Performance and resource configuration.

Controls concurrency, timeouts, and resource management.

Environment Variables:

  • RMCP_THREADPOOL_MAX_WORKERS - Max workers for stdio transport

  • RMCP_CALLBACK_TIMEOUT - Bidirectional callback timeout (seconds)

  • RMCP_PROCESS_CLEANUP_TIMEOUT - Process cleanup timeout (seconds)

Performance Tuning:

  • Adjust threadpool_max_workers based on CPU cores

  • Increase callback_timeout for slow operations

  • Keep process_cleanup_timeout low for faster resource cleanup

Examples

High-performance server:

performance = PerformanceConfig(
    threadpool_max_workers=8,
    callback_timeout=600
)

Resource-constrained environment:

performance = PerformanceConfig(
    threadpool_max_workers=1,
    callback_timeout=120
)
threadpool_max_workers: int

Maximum workers for stdio transport. Adjust based on CPU cores.

__init__(threadpool_max_workers: int = 2, callback_timeout: int = 300, process_cleanup_timeout: int = 5) → None
callback_timeout: int

Bidirectional callback timeout in seconds. For slow operations.

process_cleanup_timeout: int

Process cleanup timeout in seconds. Keep low for faster cleanup.

class rmcp.config.models.LoggingConfig(level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = 'INFO', format: str = '%(asctime)s - %(name)s - %(levelname)s - %(message)s', stderr_output: bool = True)[source]

Bases: object

Logging configuration.

Controls log output format and verbosity.

Environment Variables:

  • RMCP_LOG_LEVEL - Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

  • RMCP_LOG_FORMAT - Log message format string

Log Levels:

  • DEBUG - Detailed debugging information

  • INFO - General operational messages

  • WARNING - Warning messages about potential issues

  • ERROR - Error messages for failed operations

  • CRITICAL - Critical errors that may cause shutdown

Examples

Development logging:

logging = LoggingConfig(
    level="DEBUG",
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s"
)

Production logging:

logging = LoggingConfig(
    level="INFO",
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
__init__(level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = 'INFO', format: str = '%(asctime)s - %(name)s - %(levelname)s - %(message)s', stderr_output: bool = True) → None
level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']

Logging level. Must be DEBUG, INFO, WARNING, ERROR, or CRITICAL.

format: str

Log message format string. Python logging format.

stderr_output: bool

Log to stderr. Required for MCP protocol compliance.

class rmcp.config.models.RMCPConfig(http: ~rmcp.config.models.HTTPConfig = <factory>, r: ~rmcp.config.models.RConfig = <factory>, security: ~rmcp.config.models.SecurityConfig = <factory>, performance: ~rmcp.config.models.PerformanceConfig = <factory>, logging: ~rmcp.config.models.LoggingConfig = <factory>, config_file: ~pathlib.Path | None = None, debug: bool = False)[source]

Bases: object

Main RMCP configuration.

Root configuration object containing all subsystem configurations. Provides validation and hierarchical configuration loading.

Environment Variables:

  • RMCP_DEBUG - Enable debug mode (true/false)

Configuration Loading:

  1. Command-line arguments (highest priority)

  2. Environment variables (RMCP_* prefix)

  3. User config file (~/.rmcp/config.json)

  4. System config file (/etc/rmcp/config.json)

  5. Built-in defaults (lowest priority)

Examples

Complete configuration:

config = RMCPConfig(
    http=HTTPConfig(host="0.0.0.0", port=8000),
    r=RConfig(timeout=180, max_sessions=20),
    security=SecurityConfig(vfs_read_only=True),
    debug=True
)

Minimal configuration (uses defaults):

config = RMCPConfig(debug=True)
__init__(http: ~rmcp.config.models.HTTPConfig = <factory>, r: ~rmcp.config.models.RConfig = <factory>, security: ~rmcp.config.models.SecurityConfig = <factory>, performance: ~rmcp.config.models.PerformanceConfig = <factory>, logging: ~rmcp.config.models.LoggingConfig = <factory>, config_file: ~pathlib.Path | None = None, debug: bool = False) → None
http: HTTPConfig

HTTP transport configuration.

r: RConfig

R process configuration.

security: SecurityConfig

Security and VFS configuration.

performance: PerformanceConfig

Performance and resource configuration.

logging: LoggingConfig

Logging configuration.

config_file: Path | None

Path to configuration file that was loaded.

debug: bool

Enable debug mode for verbose logging and configuration details.