Configuration Reference

The IBM i MCP Server is configured through environment variables that control transport, authentication, logging, and IBM i connection settings. This guide covers all configuration options with examples and best practices.

Always use a .env file for local development and secure environment variable management in production. Never commit sensitive credentials to version control.

Loading Your Configuration

Before starting the server, set the MCP_SERVER_CONFIG environment variable to point to your configuration file:

NPM Package
Build from Source

# Point to your .env file
export MCP_SERVER_CONFIG=.env

# Start the server - it will automatically load the config
npx -y @ibm/ibmi-mcp-server@latest --transport http

The server loads the file specified by MCP_SERVER_CONFIG on startup.

# Point to your .env file (from repository root)
export MCP_SERVER_CONFIG=.env

# Or use relative path from server directory
export MCP_SERVER_CONFIG=../.env

# Start the server
cd server
npm run start:http

How it works: The MCP_SERVER_CONFIG environment variable tells the server where to find your configuration file. Without it, you’d need to pass each variable individually as environment variables. CLI arguments (like --transport http) override values in the config file.

Minimal Working Configuration

Start here if you’re setting up for the first time. This minimal configuration is sufficient to get the server running:

# Required: IBM i Connection
DB2i_HOST=your-ibmi-system.com
DB2i_USER=your-username
DB2i_PASS=your-password
DB2i_PORT=8076

# Default SQL tools
TOOLS_YAML_PATH=tools

# Recommended: Basic Server Settings
MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010
MCP_LOG_LEVEL=info

What do these variables do?

Variable	Purpose	When to Change
`DB2i_HOST`	IBM i hostname where Mapepire runs	Always set to your IBM i system
`DB2i_USER`	IBM i user profile	Set to your credentials
`DB2i_PASS`	IBM i password	Set to your credentials
`DB2i_PORT`	Mapepire daemon port	Only if you changed Mapepire’s default
`TOOLS_YAML_PATH`	Location of SQL tool definitions	Change if using custom tools
`MCP_TRANSPORT_TYPE`	How clients connect (http or stdio)	Use `http` for most cases
`MCP_HTTP_PORT`	Port for HTTP server	Change if 3010 is in use
`MCP_LOG_LEVEL`	Logging detail	Use `debug` for troubleshooting

What’s next? This minimal config gets you started. Add authentication, observability, and SQL tools configuration as your needs grow.

Quick Setup

Create your configuration file from the template:

cp .env.example .env

Then edit .env with your IBM i connection details using the minimal configuration above.

For a step-by-step walkthrough, see the Quick Start Guide. For production deployment, refer to the Production Deployment guide.

Core Server Configuration

Below is the reference for core server configuration options. Each section includes detailed explanations, examples, and guidance on when to use specific settings.

Server Transport

How clients connect to your MCP server. The transport type determines whether clients connect via standard input/output (stdio) for local processes or HTTP for remote/web-based connections. Most production deployments use HTTP transport for flexibility and multi-client support.

Variable	Description	Default	Example
`MCP_TRANSPORT_TYPE`	Server transport mode	`stdio`	`http`
`MCP_HTTP_PORT`	HTTP server port	`3010`	`3010`
`MCP_HTTP_HOST`	HTTP server host	`127.0.0.1`	`0.0.0.0`
`MCP_ALLOWED_ORIGINS`	CORS allowed origins (comma-separated)	(none)	`http://localhost:3000,https://myapp.com`

HTTP Transport (Recommended)
Stdio Transport

MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010
MCP_HTTP_HOST=127.0.0.1
MCP_ALLOWED_ORIGINS=http://localhost:3000

Use for: Web applications, REST APIs, development with browser-based tools

MCP_TRANSPORT_TYPE=stdio

Use for: CLI tools, MCP Inspector, direct process communication

Session Management (HTTP Only)

Control how HTTP connections maintain state. Session modes determine whether the server maintains persistent connections (stateful) or treats each request independently (stateless). The auto mode intelligently detects client capabilities and chooses the optimal strategy.

Variable	Description	Default	Options
`MCP_SESSION_MODE`	Session handling mode	`auto`	`stateless`, `stateful`, `auto`

Session Modes:

auto: Automatically detects client capabilities (recommended)
stateful: Maintains persistent sessions with connection state
stateless: Each request is independent, no session state

Authentication Configuration

Choosing an Authentication Mode

Which auth mode should you use? Select based on your deployment scenario:

Development & Testing → Use 'none'

No authentication, shared credentialsBenefits:

Quick setup for local development
Ideal for testing and prototyping
No additional configuration required

Limitations:

Never use in production environments
No per-user tracking or authorities
Security risk for networked deployments

Setup: Simply set MCP_AUTH_MODE=none in your .env file

Production with Multiple Users → Use 'ibmi'

Per-user IBM i authentication with RSA encryptionBenefits:

Each user connects with their own IBM i credentials
Respects individual IBM i object authorities
Full audit trail per user
Enterprise-grade security

Requirements:

RSA keypair generation (public/private keys)
IBM i HTTP authentication endpoints enabled
Per-user credential management

Setup: Requires IBMI_AUTH_PRIVATE_KEY_PATH, IBMI_AUTH_PUBLIC_KEY_PATH, and IBMI_HTTP_AUTH_ENABLED=true

Custom SSO / Identity Provider → Use 'oauth'

External OAuth/OIDC authenticationBenefits:

Integrate with existing enterprise auth systems
Support for SSO (Single Sign-On)
Centralized identity management
Industry-standard OAuth 2.0 / OIDC protocols

Requirements:

OAuth provider configuration (issuer URL, audience)
Token validation infrastructure
External identity provider setup

Setup: Configure OAUTH_ISSUER_URL and OAUTH_AUDIENCE for your identity provider

Custom Token System → Use 'jwt'

JSON Web Token authenticationBenefits:

Custom authentication logic and workflows
Token-based stateless auth
Flexible integration with existing systems
Control over token generation and validation

Requirements:

You manage token generation and signing
Shared secret key (minimum 32 characters)
Custom token issuance logic

Setup: Set MCP_AUTH_SECRET_KEY with a secure secret (min 32 chars)

Authentication Mode Configuration

Variable	Description	Default	Options
`MCP_AUTH_MODE`	Authentication mode	`none`	`none`, `jwt`, `oauth`, `ibmi`

No Authentication
JWT Authentication
OAuth Authentication
IBM i Authentication

MCP_AUTH_MODE=none

Use for: Development, internal networks, trusted environments

MCP_AUTH_MODE=jwt
MCP_AUTH_SECRET_KEY=your-secret-key-min-32-chars

Use for: Custom authentication systems, token-based auth

MCP_AUTH_MODE=oauth
OAUTH_ISSUER_URL=https://your-auth-server.com
OAUTH_AUDIENCE=ibmi-mcp-server

Use for: Enterprise SSO, external identity providers

MCP_AUTH_MODE=ibmi
IBMI_HTTP_AUTH_ENABLED=true
IBMI_AUTH_KEY_ID=development
IBMI_AUTH_PRIVATE_KEY_PATH=secrets/private.pem
IBMI_AUTH_PUBLIC_KEY_PATH=secrets/public.pem

Use for: Per-user IBM i credentials, connection pooling

IBM i Authentication Settings

Variable	Description	Default	Example
`IBMI_HTTP_AUTH_ENABLED`	Enable IBM i HTTP auth endpoints	`false`	`true`
`IBMI_AUTH_ALLOW_HTTP`	Allow HTTP for auth (dev only)	`false`	`true`
`IBMI_AUTH_TOKEN_EXPIRY_SECONDS`	Token lifetime in seconds	`3600`	`7200`
`IBMI_AUTH_CLEANUP_INTERVAL_SECONDS`	Token cleanup interval	`300`	`600`
`IBMI_AUTH_MAX_CONCURRENT_SESSIONS`	Max concurrent sessions	`100`	`50`
`IBMI_AUTH_KEY_ID`	Key identifier for encryption	(none)	`production`
`IBMI_AUTH_PRIVATE_KEY_PATH`	Path to RSA private key	(none)	`secrets/private.pem`
`IBMI_AUTH_PUBLIC_KEY_PATH`	Path to RSA public key	(none)	`secrets/public.pem`

IBM i Authentication Guide →

Complete setup guide: For detailed instructions on IBM i HTTP authentication including RSA key generation, token management, security best practices, and troubleshooting, see the IBM i Authentication page.

Setting Up RSA Encryption Keys

IBM i authentication requires RSA keypairs to protect credentials during transmission. The authentication flow uses RSA and AES encryption to securely exchange IBM i credentials between clients and the server.

Create Secrets Directory

Create a dedicated directory for storing encryption keys:

mkdir -p secrets

Store the secrets/ directory outside of version control. Add it to your .gitignore file.

Generate RSA Private Key

Generate a 2048-bit RSA private key:

openssl genpkey -algorithm RSA \
  -out secrets/private.pem \
  -pkeyopt rsa_keygen_bits:2048

What this does:

Creates a new RSA private key with 2048-bit encryption strength
Saves it to secrets/private.pem
This key will be used by the server to decrypt credentials sent by clients

Extract Public Key

Extract the corresponding public key from the private key:

openssl rsa -pubout \
  -in secrets/private.pem \
  -out secrets/public.pem

What this does:

Derives the public key from your private key
Saves it to secrets/public.pem
Clients use this public key to encrypt credentials before sending them to the server

Set Secure File Permissions

Restrict access to your private key:

# Make private key readable only by owner
chmod 600 secrets/private.pem

# Public key can be more permissive
chmod 644 secrets/public.pem

Critical Security Step: The private key (private.pem) must be protected. Anyone with access to this file can decrypt client credentials.

Configure Environment Variables

Add the keypair paths to your .env file:

# IBM i Authentication Keys
IBMI_AUTH_KEY_ID=production
IBMI_AUTH_PRIVATE_KEY_PATH=secrets/private.pem
IBMI_AUTH_PUBLIC_KEY_PATH=secrets/public.pem

Key Configuration:

IBMI_AUTH_KEY_ID: Identifier for this keypair (used for key rotation)
IBMI_AUTH_PRIVATE_KEY_PATH: Path to your private key file
IBMI_AUTH_PUBLIC_KEY_PATH: Path to your public key file

How the Encryption Works:

Client requests public key from server (/api/v1/auth/public-key)
Client generates a random AES-256-GCM session key
Client encrypts IBM i credentials with the session key
Client encrypts the session key with the server’s RSA public key
Server decrypts the session key using its RSA private key
Server decrypts the credentials using the session key
Server authenticates against IBM i and issues an access token

Key Rotation: To rotate keys, generate a new keypair with a different IBMI_AUTH_KEY_ID. The server can support multiple keypairs simultaneously, allowing gradual migration without service interruption.

Security Best Practices:

Production Deployment

Always use HTTPS: Set IBMI_AUTH_ALLOW_HTTP=false
Rotate keys regularly: Generate new keypairs every 90-180 days
Use strong key sizes: 2048-bit minimum, 4096-bit recommended for high-security environments
Monitor key access: Enable file auditing on the secrets/ directory
Backup keys securely: Store encrypted backups in a secrets management system

File Permissions

Private key: chmod 600 secrets/private.pem (owner read/write only)
Public key: chmod 644 secrets/public.pem (world-readable is safe)
Secrets directory: chmod 700 secrets/ (owner access only)
Owner: Ensure files are owned by the service account running the MCP server

Version Control

Never commit keys: Add secrets/ to .gitignore
Never commit .env: Environment files often contain paths to secrets
Use environment-specific keys: Different keypairs for dev/staging/production
Document setup process: Include key generation in deployment documentation

Secrets Management

For production environments, consider using a secrets management system:

AWS Secrets Manager: Store keys in encrypted AWS vault
HashiCorp Vault: Centralized secrets management with audit logs
Azure Key Vault: Microsoft’s cloud-based secrets storage
Kubernetes Secrets: For containerized deployments

Update IBMI_AUTH_PRIVATE_KEY_PATH to reference the mounted secret location.

IBM i Database Connection

Connect to IBM i DB2 for i databases via Mapepire. These settings configure the connection to your IBM i system through the Mapepire database server. The server uses these credentials to execute SQL tools and access DB2 for i data. All connections are pooled for efficiency and support both shared (development) and per-user (production) authentication modes.

Connection Settings

Variable	Description	Default	Example	Security Impact
`DB2i_HOST`	IBM i host (Mapepire daemon)	(none)	`my-ibmi-system.company.com`	Use hostname, not `127.0.0.1` in Docker
`DB2i_USER`	IBM i user profile	(none)	`MYUSER`	Shared credentials (dev only)
`DB2i_PASS`	IBM i user password	(none)	`mypassword`	Never commit to version control
`DB2i_PORT`	Mapepire daemon port	`8076`	`8076`	Ensure firewall allows this port
`DB2i_IGNORE_UNAUTHORIZED`	Skip TLS certificate verification	`true`	`false`	⚠️ High Risk: Set `false` in production

Security Alert: DB2i_IGNORE_UNAUTHORIZED=true disables TLS certificate verification, making connections vulnerable to man-in-the-middle attacks.Use this setting:

✅ Development with self-signed Mapepire certificates
❌ Production environments (use proper TLS certificates)

Development
Production

DB2i_HOST=dev-ibmi.company.com
DB2i_USER=DEVUSER
DB2i_PASS=devpassword
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=true

DB2i_HOST=prod-ibmi.company.com
DB2i_USER=PRODUSER
DB2i_PASS=${SECURE_PASSWORD}
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=false

IBM i Requirements:

User profile must have appropriate database authorities
Access to QSYS2 system services
Mapepire daemon must be running on the specified port

SQL Tools Configuration

Load and manage YAML-defined SQL tools. These settings control how the server discovers, loads, and reloads SQL tool definitions from YAML configuration files. You can load tools from individual files, entire directories, or use glob patterns to organize tools into logical groups (toolsets) for different use cases.

Path Requirements:

TOOLS_YAML_PATH in .env files should use absolute paths to avoid issues when the server is started from different directories
For relative paths, use the --tools CLI argument instead: npx -y @ibm/ibmi-mcp-server@latest --tools ./tools
CLI arguments override environment variables, so --tools always takes precedence over TOOLS_YAML_PATH

For detailed information on creating SQL tools, see the SQL Tools Overview and Building SQL Tools guides.

YAML Tool Settings

Variable	Description	Default	Example
`TOOLS_YAML_PATH`	Path to YAML tool definitions	(none)	`tools`
`SELECTED_TOOLSETS`	Comma-separated toolset names	(none)	`performance,monitoring`
`YAML_AUTO_RELOAD`	Auto-reload tools when files change	`true`	`false`
`YAML_MERGE_ARRAYS`	Merge arrays when combining files	`true`	`true`
`YAML_ALLOW_DUPLICATE_TOOLS`	Allow duplicate tool names	`false`	`true`
`YAML_ALLOW_DUPLICATE_SOURCES`	Allow duplicate source names	`false`	`true`
`YAML_VALIDATE_MERGED`	Validate merged configuration	`true`	`false`

YAML Configuration Examples

Single File:

TOOLS_YAML_PATH=tools/system-tools.yaml

Directory (loads all .yaml files):

TOOLS_YAML_PATH=tools

Specific Toolsets:

TOOLS_YAML_PATH=tools
SELECTED_TOOLSETS=performance,security,monitoring

Glob Pattern:

TOOLS_YAML_PATH=configs/**/*.yaml

Observability & Monitoring

Track server performance, debug issues, and monitor operations. Observability features help you understand server behavior through logging, distributed tracing (OpenTelemetry), and performance metrics. These settings are crucial for production deployments and troubleshooting.

Server Settings

Basic server identification and environment configuration. These variables set the server’s identity in logs and telemetry data, control the runtime environment, and determine where log files are stored.

Variable	Description	Default	Example
`MCP_SERVER_NAME`	Server name identifier for MCP protocol	Package name	`ibmi-mcp-dev`
`MCP_SERVER_VERSION`	Server version for MCP protocol	Package version	`1.9.1`
`NODE_ENV`	Node environment	`development`	`production`, `test`

Logging Configuration

Control log output, verbosity, and file storage. The server uses Pino for structured logging with automatic log rotation, level-specific log files, and support for both console and file outputs. Logs help you debug issues, track server behavior, and comply with audit requirements.

Log Settings

Variable	Description	Default	Options
`MCP_LOG_LEVEL`	Logging verbosity level	`info`	`debug`, `info`, `notice`, `warning`, `error`, `crit`, `alert`, `emerg`
`LOGS_DIR`	Directory for log files	`~/.ibmi-mcp-server/logs`	Any absolute, relative, or `~/` path
`NO_COLOR`	Disable colored console output	(none)	`1` to disable colors
`FORCE_COLOR`	Force disable colored output	(none)	`0` to disable colors

Log Levels Explained:

debug: Detailed diagnostic information (verbose)
info: General informational messages (recommended)
notice: Significant events worth noting
warning: Warning conditions that should be addressed
error: Error conditions that need attention
crit, alert, emerg: Critical system failures

Log Directory Configuration

Where logs are stored depends on how you specify the path:

Default (OS-Standard)
Absolute Path
Relative Path
Tilde Expansion

# No LOGS_DIR specified - uses OS-standard location
# Logs will be written to: ~/.ibmi-mcp-server/logs/

Default location: ~/.ibmi-mcp-server/logs/Use for: Production with npx, user-specific installationsBenefits:

Works consistently with npx @ibm/ibmi-mcp-server
Persists across package updates
Doesn’t require write permissions to npm cache
Follows OS conventions for user data

# Absolute path - exact location specified
LOGS_DIR=/var/log/ibmi-mcp-server

Use for: System-wide installations, production serversExamples:

/var/log/ibmi-mcp-server - System logs directory
/opt/ibmi-mcp/logs - Custom application directory
/app/logs - Docker container path

# Relative to current working directory (process.cwd())
LOGS_DIR=./logs

Resolves relative to: Directory where you run the serverUse for: Local development, project-specific logsExamples:

./logs - Logs in current directory
../shared-logs - Logs in parent directory
data/logs - Logs in data subdirectory

# User home directory expansion
LOGS_DIR=~/my-project/logs

Expands to: Your home directory + pathUse for: User-specific custom locationsExamples:

~/ibmi-mcp-logs → /Users/username/ibmi-mcp-logs
~/projects/mcp/logs → /Users/username/projects/mcp/logs

Path Resolution:

Absolute paths (/var/log/...) are used as-is
Relative paths (./logs) resolve from current working directory, not package location
Tilde paths (~/logs) expand to your home directory
When using npx, relative paths resolve from where you run the command

Log Files Created

The server creates 6 log files with automatic rotation:

File	Content	Rotation
`combined.log`	All info+ level logs	Daily or 10MB
`error.log`	Error+ level logs only	Daily or 10MB
`warn.log`	Warning+ level logs only	Daily or 10MB
`info.log`	Info+ level logs only	Daily or 10MB
`debug.log`	Debug+ level logs only	Daily or 10MB
`interactions.log`	MCP interaction tracking	Daily or 10MB

Rotation behavior:

Logs rotate when they reach 10MB OR at midnight daily (whichever comes first)
Rotated files are numbered sequentially: combined.log.1, combined.log.2, etc.
Current file + 5 historical versions are kept (6 total files per log level)
When the 7th file would be created, the oldest file is automatically deleted
Daily rotation re-uses the existing file if still within the same day

Log File Examples

Directory structure:

~/.ibmi-mcp-server/logs/
├── combined.log       # Current log (being written to)
├── combined.log.1     # Most recent rotation (yesterday or 10MB ago)
├── combined.log.2     # 2nd most recent
├── combined.log.3     # 3rd most recent
├── combined.log.4     # 4th most recent
├── combined.log.5     # 5th most recent (oldest kept)
├── error.log          # Current error log
├── error.log.1        # Recent error rotation
├── warn.log           # Current warning log
├── info.log           # Current info log
├── debug.log          # Current debug log
└── interactions.log   # Current interaction log

Note: Once combined.log.6 would be created, combined.log.5 is deleted and files shift: .4 → .5, .3 → .4, etc.Sample log entry (JSON format):

{
  "level": "info",
  "time": "2024-12-17T16:30:45.123Z",
  "pid": 12345,
  "env": "production",
  "version": "0.1.2",
  "msg": "Connection pool initialized successfully",
  "operation": "InitializePool",
  "requestId": "req_abc123"
}

Console Output & Colors

Console behavior depends on environment and transport mode:

HTTP Transport (Colored)

In development with HTTP transport, console logs are colored and pretty-printed to stderr:

MCP_TRANSPORT_TYPE=http
MCP_LOG_LEVEL=debug

Output: Human-readable colored logs to stderrDisable colors: Set NO_COLOR=1 or FORCE_COLOR=0

STDIO Transport (Plain)

With STDIO transport, console logs are plain JSON to stderr (MCP spec requirement):

MCP_TRANSPORT_TYPE=stdio

Output: Structured JSON to stderr (no colors, no pretty-printing)Why: MCP protocol requires clean JSON-RPC on stdout with no ANSI codes

Production (JSON)

In production, logs are structured JSON regardless of transport:

NODE_ENV=production

Output: JSON to stderr and log files

NO_COLOR Support: The server respects the NO_COLOR environment variable standard. Set NO_COLOR=1 to disable all colored output, useful for CI/CD pipelines and log aggregation systems.

Session Correlation with OpenTelemetry

How to correlate logs across server restarts: Since logs now append across server sessions (rather than creating timestamped files), use structured logging fields to filter by session:

{
  "requestId": "req_abc123",
  "operation": "ExecuteQuery",
  "msg": "Query executed successfully"
}

Best practice: Enable OpenTelemetry for distributed tracing across restarts:

OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces

This adds traceId and spanId to every log entry, making it easy to:

Filter logs by specific server sessions
Correlate requests across services
Track performance over time
Debug issues with full request context

OpenTelemetry

Enable distributed tracing and metrics collection. OpenTelemetry (OTel) provides enterprise-grade observability by tracking every request through the system, measuring performance, and exporting telemetry data to monitoring platforms like Jaeger, Zipkin, or cloud providers. Essential for production monitoring and performance optimization.

Variable	Description	Default	Example
`OTEL_ENABLED`	Enable OpenTelemetry	`false`	`true`
`OTEL_SERVICE_NAME`	Service name for telemetry data	`ibmi-mcp-server`	`production-mcp`
`OTEL_SERVICE_VERSION`	Service version for telemetry	Package version	`1.9.1`
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	OTLP endpoint for trace export	(none)	`http://localhost:4318/v1/traces`
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	OTLP endpoint for metrics export	(none)	`http://localhost:4318/v1/metrics`
`OTEL_TRACES_SAMPLER_ARG`	Trace sampling ratio (0.0 to 1.0)	`1.0`	`0.1`
`OTEL_LOG_LEVEL`	OTel diagnostic log level	`INFO`	`DEBUG`
`OTEL_RESOURCE_ATTRIBUTES`	Resource attributes	(none)	`environment=production,version=1.0.0`

Supported OTEL_LOG_LEVEL values: NONE, ERROR, WARN, INFO, DEBUG, VERBOSE, ALL

Jaeger
OTLP Collector

OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:14268/api/traces
OTEL_SERVICE_NAME=ibmi-mcp-server

OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4318/v1/traces
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://otel-collector:4318/v1/metrics

Environment-Specific Examples

Development Environment

# Transport
MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010
MCP_HTTP_HOST=127.0.0.1
MCP_SESSION_MODE=auto

# Authentication (disabled for development)
MCP_AUTH_MODE=none

# IBM i Connection
DB2i_HOST=dev-ibmi.company.com
DB2i_USER=DEVUSER
DB2i_PASS=devpassword
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=true

# Tools
TOOLS_YAML_PATH=tools
YAML_AUTO_RELOAD=true

# Logging
MCP_LOG_LEVEL=debug
LOG_FORMAT=text

# Observability (optional)
OTEL_ENABLED=false

Production Environment

# Transport
MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010
MCP_HTTP_HOST=0.0.0.0
MCP_SESSION_MODE=stateful
MCP_ALLOWED_ORIGINS=https://myapp.company.com

# Authentication
MCP_AUTH_MODE=ibmi
IBMI_HTTP_AUTH_ENABLED=true
IBMI_AUTH_KEY_ID=production
IBMI_AUTH_PRIVATE_KEY_PATH=/app/secrets/private.pem
IBMI_AUTH_PUBLIC_KEY_PATH=/app/secrets/public.pem
IBMI_AUTH_ALLOW_HTTP=false
IBMI_AUTH_TOKEN_EXPIRY_SECONDS=7200

# IBM i Connection
DB2i_HOST=prod-ibmi.company.com
DB2i_USER=${IBM_USER}
DB2i_PASS=${IBM_PASS}
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=false

# Tools
TOOLS_YAML_PATH=/app/configs
SELECTED_TOOLSETS=production,monitoring
YAML_AUTO_RELOAD=false

# Logging
MCP_LOG_LEVEL=info
LOG_FORMAT=json

# Observability
OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://traces.company.com/v1/traces
OTEL_SERVICE_NAME=ibmi-mcp-production

Docker Compose

version: '3.8'
services:
  ibmi-mcp-server:
    build: .
    environment:
      MCP_TRANSPORT_TYPE: http
      MCP_HTTP_PORT: 3010
      MCP_AUTH_MODE: ibmi
      IBMI_HTTP_AUTH_ENABLED: "true"
      DB2i_HOST: ${DB2i_HOST}
      DB2i_USER: ${DB2i_USER}
      DB2i_PASS: ${DB2i_PASS}
      TOOLS_YAML_PATH: /app/configs
      OTEL_ENABLED: "true"
    ports:
      - "3010:3010"
    volumes:
      - ./configs:/app/configs:ro
      - ./secrets:/app/secrets:ro

For additional security considerations and IBM i authority requirements, see the Authentication and Production Deployment guides.

IBM i Authentication Guide →

Getting Started

Core Concepts

Server Configuration

SQL Tools System

Loading Your Configuration

Minimal Working Configuration

Quick Setup

Core Server Configuration

Server Transport

Session Management (HTTP Only)

Authentication Configuration

Choosing an Authentication Mode

Authentication Mode Configuration

IBM i Authentication Settings

Setting Up RSA Encryption Keys

IBM i Database Connection

Connection Settings

SQL Tools Configuration

YAML Tool Settings

Observability & Monitoring

Server Settings

Logging Configuration

Log Settings

Log Directory Configuration

Log Files Created

Console Output & Colors

Session Correlation with OpenTelemetry

OpenTelemetry

Environment-Specific Examples

Getting Started

Core Concepts

Server Configuration

SQL Tools System

​Loading Your Configuration

​Minimal Working Configuration

​Quick Setup

​Core Server Configuration

​Server Transport

​Session Management (HTTP Only)

​Authentication Configuration

​Choosing an Authentication Mode

​Authentication Mode Configuration

​IBM i Authentication Settings

IBM i Authentication Guide →

​Setting Up RSA Encryption Keys

​IBM i Database Connection

​Connection Settings

​SQL Tools Configuration

​YAML Tool Settings

​Observability & Monitoring

​Server Settings

​Logging Configuration

​Log Settings

​Log Directory Configuration

​Log Files Created

​Console Output & Colors

​Session Correlation with OpenTelemetry

​OpenTelemetry

​Environment-Specific Examples

Loading Your Configuration

Minimal Working Configuration

Quick Setup

Core Server Configuration

Server Transport

Session Management (HTTP Only)

Authentication Configuration

Choosing an Authentication Mode

Authentication Mode Configuration

IBM i Authentication Settings

Setting Up RSA Encryption Keys

IBM i Database Connection

Connection Settings

SQL Tools Configuration

YAML Tool Settings

Observability & Monitoring

Server Settings

Logging Configuration

Log Settings

Log Directory Configuration

Log Files Created

Console Output & Colors

Session Correlation with OpenTelemetry

OpenTelemetry

Environment-Specific Examples