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 packages/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

Rate Limiting (HTTP Only)

Control request rate limiting for the HTTP transport. Rate limiting prevents abuse and manages server load. For agentic AI workflows that make many parallel tool calls (e.g., Agno AgentOS), you can increase the limit or disable rate limiting entirely.

Variable	Description	Default	Example
`MCP_RATE_LIMIT_ENABLED`	Enable or disable rate limiting	`true`	`false`
`MCP_RATE_LIMIT_MAX_REQUESTS`	Max requests per window	`100`	`1000`
`MCP_RATE_LIMIT_WINDOW_MS`	Window duration (ms)	`900000` (15 min)	`60000`
`MCP_RATE_LIMIT_SKIP_DEV`	Skip in development mode	`false`	`true`

Default
Agentic Workflows
Disabled

MCP_RATE_LIMIT_ENABLED=true
MCP_RATE_LIMIT_MAX_REQUESTS=100
MCP_RATE_LIMIT_WINDOW_MS=900000

Use for: Standard deployments with moderate request volumes

MCP_RATE_LIMIT_ENABLED=true
MCP_RATE_LIMIT_MAX_REQUESTS=1000
MCP_RATE_LIMIT_WINDOW_MS=60000

Use for: AI agents (Agno, LangChain, etc.) making many parallel tool calls per turn

MCP_RATE_LIMIT_ENABLED=false

Use for: Trusted internal networks, development environments, Docker Compose setups with controlled access

Docker / Reverse Proxy: The server reads X-Forwarded-For and X-Real-IP headers for client identification. When these headers are absent (e.g., behind Docker without proxy header forwarding), the server falls back to the TCP socket’s remote address. Configure your reverse proxy to forward these headers for accurate per-client rate limiting.

Connection Pool Timeouts

Control automatic cleanup of idle database connections and query timeouts. In cloud deployments (Railway, Heroku, etc.), reverse proxies silently kill idle TCP connections. The Mapepire connection pool may still report as initialized, but queries sent over a dead WebSocket will hang indefinitely. These settings prevent that by proactively closing idle pools and aborting stale queries.

Variable	Description	Default	Example
`MCP_POOL_IDLE_TIMEOUT_MS`	Idle timeout for connection pools (ms). Pools are closed after this period of inactivity.	`300000` (5 min)	`60000`
`MCP_POOL_QUERY_TIMEOUT_MS`	Query execution timeout (ms). Queries are aborted if they exceed this duration.	`30000` (30s)	`60000`

Default
Cloud Deployment
Disabled

MCP_POOL_IDLE_TIMEOUT_MS=300000
MCP_POOL_QUERY_TIMEOUT_MS=30000

Use for: Most deployments — 5-minute idle timeout and 30-second query timeout

MCP_POOL_IDLE_TIMEOUT_MS=60000
MCP_POOL_QUERY_TIMEOUT_MS=30000

Use for: Cloud platforms with aggressive proxy timeouts (Railway, Heroku, etc.)

MCP_POOL_IDLE_TIMEOUT_MS=0
MCP_POOL_QUERY_TIMEOUT_MS=0

Use for: Stable network environments where connections are long-lived and reliable

How it works: The idle timer checks pools at an interval of max(10s, timeout/2). When a pool exceeds the idle timeout, it is closed automatically. The next query triggers a transparent re-initialization through the existing lazy-init path — no manual intervention needed. The query timeout uses Promise.race() to abort queries on stale connections, marking the pool unhealthy so it is re-created on the next request.

Setting MCP_POOL_QUERY_TIMEOUT_MS=0 disables query timeouts entirely. This means queries on dead connections will hang until the client’s own timeout fires. Only disable this in trusted, stable network environments.

Pagination

Controls the per-fetch page size and the safety ceiling used when SQL tools paginate large result sets. fetchAllRows: true tools and the built-in execute_sql tool share these values. YAML tools override per-call via rowsToFetch; these env vars govern the defaults.

Variable	Description	Default	Example
`IBMI_PAGINATION_DEFAULT_PAGE_SIZE`	Rows per `fetchMore` call when a tool paginates without specifying its own page size.	`1000`	`500`
`IBMI_PAGINATION_MAX_ROWS`	Hard upper bound on total rows from a single paginated tool call. Pagination stops and flags the result as truncated once this is reached.	`30000`	`100000`

Why these defaults: At 1000 rows/fetch, the server makes at most 30 round-trips before hitting the 30,000-row ceiling — around 3 seconds of tail latency on a healthy WebSocket link. The ceiling itself is the practical LLM-ingestion limit: 30k rows typically serialize to 3-6M tokens, already beyond most context windows. Operators running bulk CLI exports can raise IBMI_PAGINATION_MAX_ROWS; LLM-facing deployments rarely should.

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
`DB2i_JDBC_OPTIONS`	Mapepire JDBC options (syntax)	(none)	`naming=system;date format=iso`	`key ring password` redacted from logs

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

DB2i_JDBC_OPTIONS Env Var

Forward any mapepire JDBC option to the underlying driver via a single environment variable. The DB2i_JDBC_OPTIONS env var accepts a semicolon-separated list of key=value pairs modeled on DB2 JDBC URL syntax — letting you set library list, naming convention, date format, and any other JDBC property without editing YAML.

DB2i_JDBC_OPTIONS='naming=system;date format=iso;libraries=MYLIB,DEVDATA'

Format Rules

Rule	Behavior
Outer separator	`;` splits pairs; empty segments are ignored
Inner separator	First `=` in each pair splits key/value (values may contain `=`)
Whitespace	Trimmed around both key and value
Arrays	Only `libraries` is array-valued; comma-split within a single pair
Types	All other values forwarded as strings — no boolean/number coercion
Keys with spaces	Work unquoted: `date format=iso` is valid
Malformed pairs	A non-empty segment with no `=` throws a clear error at startup

Library List
Date Format
Combined Options

DB2i_JDBC_OPTIONS='libraries=MYLIB,DEVDATA,QGPL'

Use for: Resolving unqualified object names. Comma-split within the single libraries= pair.

DB2i_JDBC_OPTIONS='date format=iso'

Output: SELECT CHAR(CURRENT_DATE) → 2026-04-17Other values: usa (04/17/2026), eur (17.04.2026), jis (2026-04-17), mdy, dmy, ymd, julian

Job default caveat: If date format is unset, the driver inherits the connected job’s DATFMT system value — which may produce two-digit years (e.g., 04/17/26). Set date format=iso explicitly for unambiguous date serialization.

DB2i_JDBC_OPTIONS='naming=system;date format=iso;libraries=REPORTS,SALESDATA,QGPL'

Use for: Reporting or audit pipelines that need a specific library list, legacy slash-notation naming, and ISO date format.

Precedence and YAML Interaction

DB2i_JDBC_OPTIONS is shallow-merged over the jdbc-options field in each YAML source. Env values win on per-key collisions; YAML-only keys are preserved.

Scenario	Result
Only YAML sets `jdbc-options`	YAML values flow through unchanged
Only env sets `DB2i_JDBC_OPTIONS`	Env values apply to every source
Both set the same key	Env wins for that key
Both set different keys	Both apply (shallow merge, union of keys)

Why env overrides YAML: Operators can enforce a fleet-wide JDBC configuration (for example, forcing naming=system or a standard library list across all environments) without editing per-deployment YAML files.

Example merge:

# YAML source
jdbc-options:
  libraries: [YAMLLIB]
  naming: sql
  date format: iso

# Env var
DB2i_JDBC_OPTIONS='libraries=ENVLIB;naming=system'

# Effective JDBC options sent to mapepire
libraries: [ENVLIB]      # env wins
naming: system           # env wins
date format: iso         # YAML only, preserved

Security: Log Redaction

The server logs only the libraries field at pool initialization. Other JDBC fields — including potentially sensitive values like key ring password, proxy server, and trace — are intentionally excluded from every log level to prevent credential leakage.

If you need to verify that a non-libraries option took effect, inspect driver behavior directly (for example, run SELECT CHAR(CURRENT_DATE) to confirm date format) rather than searching the logs.

See the YAML Sources Reference → JDBC Options for per-source configuration in YAML.

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

Built-in Tools

Control access to compiled SQL tools. The server includes built-in tools for schema discovery, query validation, and SQL execution. All are disabled by default (except describe_sql_object) and must be explicitly enabled via CLI flags or environment variables.

Tool	Status	Purpose	CLI Flag	Env Variable
`describe_sql_object`	✅ Always enabled	Generate DDL for database objects	—	—
`list_schemas`	Disabled by default	List available schemas/libraries	`--builtin-tools`	`IBMI_ENABLE_DEFAULT_TOOLS`
`list_tables_in_schema`	Disabled by default	List tables, views, physical files	`--builtin-tools`	`IBMI_ENABLE_DEFAULT_TOOLS`
`get_table_columns`	Disabled by default	Get column metadata for a table	`--builtin-tools`	`IBMI_ENABLE_DEFAULT_TOOLS`
`get_related_objects`	Disabled by default	Find dependent objects	`--builtin-tools`	`IBMI_ENABLE_DEFAULT_TOOLS`
`validate_query`	Disabled by default	Validate SQL syntax and verify objects	`--builtin-tools`	`IBMI_ENABLE_DEFAULT_TOOLS`
`execute_sql`	⚠️ Disabled by default	Execute ad-hoc SQL queries (readonly by default)	`--execute-sql`	`IBMI_ENABLE_EXECUTE_SQL`

Use --builtin-tools --execute-sql together for the full text-to-SQL workflow. Use --builtin-tools alone to let agents discover schema while routing queries through curated YAML tools. See the Built-in Tools Reference for complete parameter and response documentation.

Configuration Variables

Variable	Description	Default	Options
`IBMI_ENABLE_DEFAULT_TOOLS`	Enable schema discovery tools	`false`	`true`, `false`
`IBMI_ENABLE_EXECUTE_SQL`	Enable ad-hoc SQL execution	`false`	`true`, `false`
`IBMI_EXECUTE_SQL_READONLY`	Control readonly mode (only SELECT queries)	`true`	`true`, `false`

Security: execute_sql allows clients to run ad-hoc SQL queries. By default (IBMI_EXECUTE_SQL_READONLY=true), only SELECT queries are allowed. Set IBMI_EXECUTE_SQL_READONLY=false to enable write operations (INSERT, UPDATE, DELETE). Enable only in development or trusted environments. Production deployments should use YAML-defined tools for controlled query access.

Full Workflow (CLI)
Schema Discovery Only
Write Mode (Opt-in)
YAML Tools Only (Default)

# Schema discovery + query execution
npx -y @ibm/ibmi-mcp-server@latest --builtin-tools --execute-sql --transport http

Use for: Development with full text-to-SQL capability

# Agents explore schema but can't run arbitrary SQL
npx -y @ibm/ibmi-mcp-server@latest --builtin-tools --tools ./tools

Use for: Production with curated YAML tools + schema exploration

IBMI_EXECUTE_SQL_READONLY=false
npx -y @ibm/ibmi-mcp-server@latest --builtin-tools --execute-sql

Use for: Development when write operations are explicitly needed⚠️ Warning: Only use in trusted environments with proper authentication

npx -y @ibm/ibmi-mcp-server@latest --tools ./tools

Use for: Production with curated YAML tools for controlled access

Tool Capabilities:

Schema Discovery Tools (--builtin-tools)

Five read-only tools that query IBM i system catalog views:

list_schemas: Browse available schemas via QSYS2.SYSSCHEMAS
list_tables_in_schema: Find tables, views, physical files via QSYS2.SYSTABLES
get_table_columns: Inspect column metadata via QSYS2.SYSCOLUMNS2
get_related_objects: Dependency analysis via SYSTOOLS.RELATED_OBJECTS
validate_query: Multi-step SQL validation via QSYS2.PARSE_STATEMENT

All are safe, read-only catalog queries with zero risk to data.

describe_sql_object (Always Available)

Generates SQL DDL for IBM i database objects using QSYS2.GENERATE_SQL:

Input: Object name, library, type (TABLE, VIEW, INDEX, etc.)
Output: Complete DDL with constraints, indexes, and properties
Security: Read-only, describes objects without modification
Use case: Schema discovery, documentation, AI context

execute_sql (--execute-sql)

Executes ad-hoc SQL queries with multi-layered security controls:

Readonly by default: Only SELECT/QUERY statements allowed when IBMI_EXECUTE_SQL_READONLY=true (default)
Write operations opt-in: Set IBMI_EXECUTE_SQL_READONLY=false to enable INSERT, UPDATE, DELETE, etc.
PARSE_STATEMENT validation: Uses IBM i’s native SQL parser (QSYS2.PARSE_STATEMENT) for authoritative statement type detection
AST/Regex validation: Fast pattern matching to catch dangerous SQL keywords
Fail-closed security: All validation failures result in query rejection
Query length limit: Maximum 10,000 characters per query
Use case: Development exploration, debugging queries, ad-hoc data analysis

Built-in vs YAML Tools:

Built-in tools: Compiled TypeScript, controlled by feature flags, runtime validation with PARSE_STATEMENT
YAML tools: User-defined, curated queries with parameters, explicit query control
Security: Built-in tools use IBM i’s SQL parser for defense-in-depth; YAML tools use explicit query whitelisting
Recommendation: Use YAML tools in production for explicit query control and parameterization

See SQL Tools Overview for creating YAML tools.

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"
}

{
  "traceId": "d4e5f6a7b8c9d0e1",
  "spanId": "a1b2c3d4e5f6",
  "msg": "Processing MCP tool request"
}

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

# Connection Pool Timeouts (recommended for cloud deployments)
MCP_POOL_IDLE_TIMEOUT_MS=300000
MCP_POOL_QUERY_TIMEOUT_MS=30000

# 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"
      MCP_RATE_LIMIT_MAX_REQUESTS: "1000"  # Higher limit for agentic workflows
      MCP_POOL_IDLE_TIMEOUT_MS: "300000"
      MCP_POOL_QUERY_TIMEOUT_MS: "30000"
    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.

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)

Rate Limiting (HTTP Only)

Connection Pool Timeouts

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

DB2i_JDBC_OPTIONS Env Var

Format Rules

Precedence and YAML Interaction

Security: Log Redaction

SQL Tools Configuration

YAML Tool Settings

Built-in Tools

Configuration Variables

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)

​Rate Limiting (HTTP Only)

​Connection Pool Timeouts

​Pagination

​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

​DB2i_JDBC_OPTIONS Env Var

​Format Rules

​Precedence and YAML Interaction

​Security: Log Redaction

​SQL Tools Configuration

​YAML Tool Settings

​Built-in Tools

​Configuration Variables

​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)

Rate Limiting (HTTP Only)

Connection Pool Timeouts

Pagination

Authentication Configuration

Choosing an Authentication Mode

Authentication Mode Configuration

IBM i Authentication Settings

Setting Up RSA Encryption Keys

IBM i Database Connection

Connection Settings

DB2i_JDBC_OPTIONS Env Var

Format Rules

Precedence and YAML Interaction

Security: Log Redaction

SQL Tools Configuration

YAML Tool Settings

Built-in Tools

Configuration Variables

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