IBM i MCP Server

--- title: "Configuration Reference" description: "Complete guide to configuring the IBM i MCP Server with environment variables, authentication modes, and deployment options." --- 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> --- ## Loading Your Configuration Before starting the server, set the `MCP_SERVER_CONFIG` environment variable to point to your configuration file: <Tabs> <Tab title="NPM Package"> ```bash # 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. </Tab> <Tab title="Build from Source"> ```bash # 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 ``` </Tab> </Tabs> <Note> **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. </Note> --- ## Minimal Working Configuration **Start here** if you're setting up for the first time. This minimal configuration is sufficient to get the server running: ```bash # 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 ``` <Accordion title="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 | </Accordion> <Info> **What's next?** This minimal config gets you started. Add [authentication](#authentication-configuration), [observability](#observability--monitoring), and [SQL tools configuration](#sql-tools-configuration) as your needs grow. </Info> --- ## Quick Setup Create your configuration file from the template: ```bash cp .env.example .env ``` Then edit `.env` with your IBM i connection details using the minimal configuration above. <Tip> For a step-by-step walkthrough, see the [Quick Start Guide](/quickstart). For production deployment, refer to the [Production Deployment](/deployment/production) guide. </Tip> --- ## 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` | <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) **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` | <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 ### Choosing an Authentication Mode **Which auth mode should you use?** Select based on your deployment scenario: <AccordionGroup> <Accordion title="Development & Testing → Use 'none'" icon="flask"> **No authentication, shared credentials** **Benefits:** - 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 </Accordion> <Accordion title="Production with Multiple Users → Use 'ibmi'" icon="users"> **Per-user IBM i authentication with RSA encryption** **Benefits:** - 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` </Accordion> <Accordion title="Custom SSO / Identity Provider → Use 'oauth'" icon="building"> **External OAuth/OIDC authentication** **Benefits:** - 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 </Accordion> <Accordion title="Custom Token System → Use 'jwt'" icon="key"> **JSON Web Token authentication** **Benefits:** - 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) </Accordion> </AccordionGroup> ### Authentication Mode Configuration | 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` | <Card title="IBM i Authentication Guide →" icon="key" href="/server-config/ibmi-auth"> **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](/server-config/ibmi-auth) page. </Card> ### 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. <Steps> <Step title="Create Secrets Directory"> Create a dedicated directory for storing encryption keys: ```bash mkdir -p secrets ``` <Tip> Store the `secrets/` directory outside of version control. Add it to your `.gitignore` file. </Tip> </Step> <Step title="Generate RSA Private Key"> Generate a 2048-bit RSA private key: ```bash 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 </Step> <Step title="Extract Public Key"> Extract the corresponding public key from the private key: ```bash 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 </Step> <Step title="Set Secure File Permissions"> Restrict access to your private key: ```bash # Make private key readable only by owner chmod 600 secrets/private.pem # Public key can be more permissive chmod 644 secrets/public.pem ``` <Warning> **Critical Security Step**: The private key (`private.pem`) must be protected. Anyone with access to this file can decrypt client credentials. </Warning> </Step> <Step title="Configure Environment Variables"> Add the keypair paths to your `.env` file: ```bash # 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 </Step> </Steps> **How the Encryption Works:** 1. **Client requests public key** from server (`/api/v1/auth/public-key`) 2. **Client generates** a random AES-256-GCM session key 3. **Client encrypts** IBM i credentials with the session key 4. **Client encrypts** the session key with the server's RSA public key 5. **Server decrypts** the session key using its RSA private key 6. **Server decrypts** the credentials using the session key 7. **Server authenticates** against IBM i and issues an access token <Note> **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. </Note> **Security Best Practices:** <AccordionGroup> <Accordion title="Production Deployment" icon="shield-check"> - **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 </Accordion> <Accordion title="File Permissions" icon="lock"> - **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 </Accordion> <Accordion title="Version Control" icon="code-branch"> - **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 </Accordion> <Accordion title="Secrets Management" icon="vault"> 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. </Accordion> </AccordionGroup> ## 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 | <Warning> **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) </Warning> <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 **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. <Warning> **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` </Warning> 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) | `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` | <Accordion title="YAML Configuration Examples"> **Single File**: ```bash TOOLS_YAML_PATH=tools/system-tools.yaml ``` **Directory (loads all .yaml files)**: ```bash TOOLS_YAML_PATH=tools ``` **Specific Toolsets**: ```bash TOOLS_YAML_PATH=tools SELECTED_TOOLSETS=performance,security,monitoring ``` **Glob Pattern**: ```bash TOOLS_YAML_PATH=configs/**/*.yaml ``` </Accordion> ## 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 | <Info> **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 </Info> #### Log Directory Configuration **Where logs are stored depends on how you specify the path:** <Tabs> <Tab title="Default (OS-Standard)"> ```bash # 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 installations **Benefits**: - 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 </Tab> <Tab title="Absolute Path"> ```bash # Absolute path - exact location specified LOGS_DIR=/var/log/ibmi-mcp-server ``` **Use for**: System-wide installations, production servers **Examples**: - `/var/log/ibmi-mcp-server` - System logs directory - `/opt/ibmi-mcp/logs` - Custom application directory - `/app/logs` - Docker container path </Tab> <Tab title="Relative Path"> ```bash # Relative to current working directory (process.cwd()) LOGS_DIR=./logs ``` **Resolves relative to**: Directory where you run the server **Use for**: Local development, project-specific logs **Examples**: - `./logs` - Logs in current directory - `../shared-logs` - Logs in parent directory - `data/logs` - Logs in data subdirectory </Tab> <Tab title="Tilde Expansion"> ```bash # User home directory expansion LOGS_DIR=~/my-project/logs ``` **Expands to**: Your home directory + path **Use for**: User-specific custom locations **Examples**: - `~/ibmi-mcp-logs` → `/Users/username/ibmi-mcp-logs` - `~/projects/mcp/logs` → `/Users/username/projects/mcp/logs` </Tab> </Tabs> <Warning> **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 </Warning> #### 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 <Accordion title="Log File Examples"> **Directory structure:** ```bash ~/.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):** ```json { "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" } ``` </Accordion> #### Console Output & Colors **Console behavior depends on environment and transport mode:** <AccordionGroup> <Accordion title="HTTP Transport (Colored)" icon="palette"> In development with HTTP transport, console logs are **colored and pretty-printed** to stderr: ```bash MCP_TRANSPORT_TYPE=http MCP_LOG_LEVEL=debug ``` **Output**: Human-readable colored logs to `stderr` **Disable colors**: Set `NO_COLOR=1` or `FORCE_COLOR=0` </Accordion> <Accordion title="STDIO Transport (Plain)" icon="terminal"> With STDIO transport, console logs are **plain JSON** to stderr (MCP spec requirement): ```bash 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 </Accordion> <Accordion title="Production (JSON)" icon="server"> In production, logs are **structured JSON** regardless of transport: ```bash NODE_ENV=production ``` **Output**: JSON to `stderr` and log files </Accordion> </AccordionGroup> <Note> **NO_COLOR Support**: The server respects the [NO_COLOR](https://no-color.org/) environment variable standard. Set `NO_COLOR=1` to disable all colored output, useful for CI/CD pipelines and log aggregation systems. </Note> #### 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: <CodeGroup> ```json Example: Filter by Request ID { "requestId": "req_abc123", "operation": "ExecuteQuery", "msg": "Query executed successfully" } ``` ```json Example: Filter by Trace ID (OpenTelemetry) { "traceId": "d4e5f6a7b8c9d0e1", "spanId": "a1b2c3d4e5f6", "msg": "Processing MCP tool request" } ``` </CodeGroup> **Best practice**: Enable OpenTelemetry for distributed tracing across restarts: ```bash 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` | <Note> **Supported OTEL_LOG_LEVEL values**: `NONE`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `VERBOSE`, `ALL` </Note> <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> ## 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=tools 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> <Tip> For additional security considerations and IBM i authority requirements, see the [Authentication](/api/auth-endpoints) and [Production Deployment](/deployment/production) guides. </Tip>