Configuration Reference

Complete guide to configuring the IBM i MCP Server with environment variables, authentication modes, and deployment options.

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.

Quick Setup

Create your configuration file:

cp .env.example .env

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

Core Configuration

Server Transport

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)

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

Session Management (HTTP Only)

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

Authentication Modes

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

No Authentication

MCP_AUTH_MODE=none

Use for: Development, internal networks, trusted environments

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

Security Requirements for IBM i Auth:

• Generate RSA keypair: openssl genpkey -algorithm RSA -out secrets/private.pem -pkeyopt rsa_keygen_bits:2048
• Use HTTPS in production (IBMI_AUTH_ALLOW_HTTP=false)
• Secure file permissions on key files

IBM i Database Connection

Connection Settings

Variable	Description	Default	Example
DB2i_HOST	IBM i host (Mapepire daemon)	(none)	my-ibmi-system.company.com
DB2i_USER	IBM i user profile	(none)	MYUSER
DB2i_PASS	IBM i user password	(none)	mypassword
DB2i_PORT	Mapepire daemon port	8076	8076
DB2i_IGNORE_UNAUTHORIZED	Skip TLS verification	true	false

Development

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

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

Control how YAML-based SQL tools are loaded and managed. 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)	prebuiltconfigs
SELECTED_TOOLSETS	Comma-separated toolset names	(none)	performance,monitoring
YAML_MERGE_ARRAYS	Merge arrays when combining files	false	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_AUTO_RELOAD	Auto-reload on file changes	true	false

YAML Configuration Examples

Single File:

TOOLS_YAML_PATH=prebuiltconfigs/system-tools.yaml

Directory (loads all .yaml files):

TOOLS_YAML_PATH=prebuiltconfigs

Specific Toolsets:

TOOLS_YAML_PATH=prebuiltconfigs
SELECTED_TOOLSETS=performance,security,monitoring

Glob Pattern:

TOOLS_YAML_PATH=configs/**/*.yaml

Observability & Monitoring

Logging

Variable	Description	Default	Options
MCP_LOG_LEVEL	Logging level	info	debug, info, warn, error
LOG_FORMAT	Log output format	json	json, text

OpenTelemetry

Variable	Description	Default	Example
OTEL_ENABLED	Enable OpenTelemetry	false	true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	OTLP traces endpoint	(none)	http://localhost:4318/v1/traces
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	OTLP metrics endpoint	(none)	http://localhost:4318/v1/metrics
OTEL_SERVICE_NAME	Service name for tracing	ibmi-mcp-server	production-mcp
OTEL_RESOURCE_ATTRIBUTES	Resource attributes	(none)	environment=production,version=1.0.0

Jaeger

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

External Service Integration

OpenRouter AI

Variable	Description	Default	Example
OPENROUTER_API_KEY	OpenRouter.ai API key	(none)	sk-or-v1-...

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=prebuiltconfigs
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

Configuration Validation

Validate Configuration

# Check configuration without starting server
npm run validate-config

# List available toolsets
npm run start:http -- --list-toolsets

# Test connection
npm run test-connection

Security Best Practices

Production Security Checklist:

• ✅ Use HTTPS (IBMI_AUTH_ALLOW_HTTP=false)
• ✅ Secure RSA key files (600 permissions)
• ✅ Use environment-specific credentials
• ✅ Enable proper CORS settings
• ✅ Configure appropriate token expiry
• ✅ Monitor concurrent sessions
• ✅ Enable audit logging

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