---
title: "Configuration Reference"
description: "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.
<Warning>
Always use a `.env` file for local development and secure environment variable management in production. Never commit sensitive credentials to version control.
</Warning>
## Quick Setup
Create your configuration file:
```bash
cp .env.example .env
```
<Info>
For a step-by-step walkthrough of basic configuration, see the [Quick Start Guide](/quickstart). For production deployment considerations, refer to the [Production Deployment](/deployment/production) guide.
</Info>
## 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` |
<Tabs>
<Tab title="HTTP Transport (Recommended)">
```bash
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
</Tab>
<Tab title="Stdio Transport">
```bash
MCP_TRANSPORT_TYPE=stdio
```
**Use for**: CLI tools, MCP Inspector, direct process communication
</Tab>
</Tabs>
### Session Management (HTTP Only)
| Variable | Description | Default | Options |
|----------|-------------|---------|---------|
| `MCP_SESSION_MODE` | Session handling mode | `auto` | `stateless`, `stateful`, `auto` |
<Info>
**Session Modes**:
- `auto`: Automatically detects client capabilities (recommended)
- `stateful`: Maintains persistent sessions with connection state
- `stateless`: Each request is independent, no session state
</Info>
## Authentication Configuration
### Authentication Modes
| Variable | Description | Default | Options |
|----------|-------------|---------|---------|
| `MCP_AUTH_MODE` | Authentication mode | `none` | `none`, `jwt`, `oauth`, `ibmi` |
<Tabs>
<Tab title="No Authentication">
```bash
MCP_AUTH_MODE=none
```
**Use for**: Development, internal networks, trusted environments
</Tab>
<Tab title="JWT Authentication">
```bash
MCP_AUTH_MODE=jwt
MCP_AUTH_SECRET_KEY=your-secret-key-min-32-chars
```
**Use for**: Custom authentication systems, token-based auth
</Tab>
<Tab title="OAuth Authentication">
```bash
MCP_AUTH_MODE=oauth
OAUTH_ISSUER_URL=https://your-auth-server.com
OAUTH_AUDIENCE=ibmi-mcp-server
```
**Use for**: Enterprise SSO, external identity providers
</Tab>
<Tab title="IBM i Authentication">
```bash
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
</Tab>
</Tabs>
### 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` |
<Warning>
**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
</Warning>
## 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` |
<Tabs>
<Tab title="Development">
```bash
DB2i_HOST=dev-ibmi.company.com
DB2i_USER=DEVUSER
DB2i_PASS=devpassword
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=true
```
</Tab>
<Tab title="Production">
```bash
DB2i_HOST=prod-ibmi.company.com
DB2i_USER=PRODUSER
DB2i_PASS=${SECURE_PASSWORD}
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=false
```
</Tab>
</Tabs>
<Note>
**IBM i Requirements**:
- User profile must have appropriate database authorities
- Access to QSYS2 system services
- Mapepire daemon must be running on the specified port
</Note>
## 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](/sql-tools/overview) and [Building SQL Tools](/sql-tools/building-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 | `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_AUTO_RELOAD` | Auto-reload on file changes | `true` | `false` |
<Accordion title="YAML Configuration Examples">
**Single File**:
```bash
TOOLS_YAML_PATH=prebuiltconfigs/system-tools.yaml
```
**Directory (loads all .yaml files)**:
```bash
TOOLS_YAML_PATH=prebuiltconfigs
```
**Specific Toolsets**:
```bash
TOOLS_YAML_PATH=prebuiltconfigs
SELECTED_TOOLSETS=performance,security,monitoring
```
**Glob Pattern**:
```bash
TOOLS_YAML_PATH=configs/**/*.yaml
```
</Accordion>
## 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` |
<Tabs>
<Tab title="Jaeger">
```bash
OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:14268/api/traces
OTEL_SERVICE_NAME=ibmi-mcp-server
```
</Tab>
<Tab title="OTLP Collector">
```bash
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
```
</Tab>
</Tabs>
## External Service Integration
### OpenRouter AI
| Variable | Description | Default | Example |
|----------|-------------|---------|---------|
| `OPENROUTER_API_KEY` | OpenRouter.ai API key | (none) | `sk-or-v1-...` |
## Environment-Specific Examples
<Accordion title="Development Environment">
```bash
# 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
```
</Accordion>
<Accordion title="Production Environment">
```bash
# 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
```
</Accordion>
<Accordion title="Docker Compose">
```yaml
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
```
</Accordion>
## Configuration Validation
<CodeGroup>
```bash 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
```
```bash Debug Configuration
# Start with debug logging
MCP_LOG_LEVEL=debug npm run start:http
# Validate specific toolsets
npm run start:http -- --toolsets performance --verbose
```
</CodeGroup>
## Security Best Practices
<Warning>
**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
</Warning>
<Tip>
For additional security considerations and IBM i authority requirements, see the [Authentication](/api/auth-endpoints) and [Production Deployment](/deployment/production) guides.
</Tip>
