Sources Reference

Complete reference for configuring database connection sources in YAML SQL tools.

Official Schema: See the JSON Schema definition for the authoritative source configuration specification.

Sources define database connections that your SQL tools use to execute queries against IBM i systems. Each source specifies connection parameters, credentials, and behavior options.

Quick Reference

All source configuration fields:

Field	Type	Required	Default	Description
host	string	✅ Yes	-	IBM i hostname or IP address
user	string	✅ Yes	-	IBM i user profile
password	string	✅ Yes	-	User profile password
port	integer	No	8076	Mapepire daemon port
ignore-unauthorized	boolean	No	false	Accept self-signed SSL certs
jdbc-options	object	No	{}	JDBC connection options passed to the mapepire driver (libraries, naming, date format, etc.)

---

Basic Source Configuration

Every YAML file starts with a sources section that defines one or more database connections:

sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 8076
    ignore-unauthorized: true

Source Naming: Choose descriptive source names like ibmi-production, ibmi-dev, or ibmi-system. Tools reference these names in their source field to specify which connection to use.

---

Source Fields Reference

Required Fields

All sources must include these three fields:

Field	Type	Description	Example
host	string	Hostname or IP address of IBM i system running Mapepire daemon	${DB2i_HOST}
user	string	IBM i user profile for database authentication	${DB2i_USER}
password	string	Password for the IBM i user profile	${DB2i_PASS}

Security Requirement: Always use environment variables for credentials. Never hardcode sensitive values in YAML files.

Examples:

Environment Variables (Recommended)

sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}

.env file:

DB2i_HOST=ibmi-prod.example.com
DB2i_USER=MCPUSER
DB2i_PASS=SecurePassword123

✅ Best for: All environments (development, testing, production)

✅ Security: Credentials never stored in version control

Direct Values (Development Only)

sources:
  ibmi-dev:
    host: ibmi-dev.local
    user: DEVUSER
    password: DevPassword123

⚠️ Use only for: Local development with test credentials

❌ Never use for: Production or shared repositories

IP Address

sources:
  ibmi-system:
    host: ${DB2i_HOST}  # Can be IP: 192.168.1.100
    user: ${DB2i_USER}
    password: ${DB2i_PASS}

.env file:

DB2i_HOST=192.168.1.100
DB2i_USER=MCPUSER
DB2i_PASS=SecurePassword123

✅ Best for: Systems without DNS resolution

Authority Requirements:

The IBM i user profile must have:

• Object authority to tables, views, and procedures accessed by tools
• Special authorities for system services (e.g., *AUDIT for security tools)
• IBM i object-level security applies to all SQL queries

---

Optional Fields

These fields have sensible defaults and can be omitted for most configurations:

Field	Type	Default	Description
port	integer	8076	Port number where Mapepire daemon listens
ignore-unauthorized	boolean	false	Accept self-signed SSL certificates
jdbc-options	object	{}	JDBC connection options forwarded to the mapepire driver

Detailed Configuration:

Port Configuration

Default port (8076):

sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    # port: 8076  ← Can be omitted (uses default)

Custom port:

sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 9000

Environment variable with default:

sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: ${DB2i_PORT:8076}  # Uses 8076 if not set

The default port 8076 is the standard port for the Mapepire daemon on IBM i systems.

SSL Configuration

Production (valid certificates):

sources:
  ibmi-production:
    host: ${PROD_DB2i_HOST}
    user: ${PROD_DB2i_USER}
    password: ${PROD_DB2i_PASS}
    port: 8076
    ignore-unauthorized: false  # Require valid certs

Development (self-signed certificates):

sources:
  ibmi-dev:
    host: ${DEV_DB2i_HOST}
    user: ${DEV_DB2i_USER}
    password: ${DEV_DB2i_PASS}
    port: 8076
    ignore-unauthorized: true  # Allow self-signed

Environment-specific:

sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 8076
    ignore-unauthorized: ${DB2i_IGNORE_UNAUTHORIZED:false}

Production Security: Only use ignore-unauthorized: true in development. Production must use valid SSL certificates with ignore-unauthorized: false.

---

JDBC Options

Forward any mapepire JDBC option to the underlying driver. The jdbc-options field accepts any property supported by the IBM i JDBC driver — library list, SQL naming convention, date format, time format, and many more.

Common Options

Option	Purpose	Example
libraries	Library list for unqualified name resolution	[MYLIB, DEVDATA, QGPL]
naming	SQL naming convention	sql or system
date format	Date literal format	iso, usa, eur, jis, mdy, dmy, ymd, julian
time format	Time literal format	hms, usa, iso, eur, jis
date separator	Date component separator	/, -, ., ,, b

Library List

sources:
  ibmi-dev:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    jdbc-options:
      libraries:
        - MYLIB
        - DEVDATA
        - QGPL

Use for: Resolving unqualified object names against a specific set of libraries.

libraries also accepts a comma-separated string: libraries: "MYLIB, DEVDATA, QGPL" — the server splits and trims it into an array.

Date Format

sources:
  ibmi-iso:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    jdbc-options:
      date format: iso    # YYYY-MM-DD

Output: CURRENT_DATE → 2026-04-17 (ISO 8601)

Other formats:

• usa → 04/17/2026 (MM/DD/YYYY)
• eur → 17.04.2026 (DD.MM.YYYY)
• jis → 2026-04-17 (same as ISO)

Job default caveat: If you don’t set date format, the driver inherits the connected job’s DATFMT system value — which on many systems produces two-digit years (e.g., 04/17/26). Set date format: iso explicitly if unambiguous serialization matters to your application.

SQL Naming

sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    jdbc-options:
      naming: system   # LIBRARY/OBJECT syntax

Use for: Legacy SQL using LIBRARY/OBJECT slash-notation instead of standard LIBRARY.OBJECT dot-notation.

Values:

• sql (default) — standard SCHEMA.OBJECT
• system — IBM i legacy LIBRARY/OBJECT

Combined

sources:
  ibmi-reporting:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    jdbc-options:
      libraries: [REPORTS, SALESDATA, QGPL]
      naming: system
      date format: iso
      time format: iso

Use for: Reporting pipelines that need ISO-formatted dates and access to a specific library set.

Full Property List

The field accepts any property from the mapepire JDBCOptions interface — over 60 settings covering SQL behavior, date/time formatting, locale, tracing, and more. Refer to the IBM i JDBC properties reference for the complete catalog.

Passthrough validation: Unknown keys pass through the schema validator without error and are forwarded to the driver as-is. This is intentional — it avoids coupling the schema to the driver’s exact property surface. The tradeoff is that typos (e.g., librarys instead of libraries) are silently accepted at config load time and only surface when the driver rejects them at connection time.

Environment Variable Override

The DB2i_JDBC_OPTIONS environment variable overrides jdbc-options set in YAML — operators can enforce a fleet-wide JDBC configuration without editing per-deployment YAML. Env values are shallow-merged over YAML values (env wins on each key).

# Every source in every YAML file runs with these options,
# plus whatever is set per-source in YAML (env wins on collisions)
export DB2i_JDBC_OPTIONS='naming=system;date format=iso;libraries=AUDITLIB,QGPL'

See the Configuration Reference → DB2i_JDBC_OPTIONS for the full syntax and parser rules.

Security: Credential Logging

The server logs only the libraries field of jdbc-options at pool initialization. All other JDBC fields — including potentially sensitive ones like key ring password, proxy server, and trace — are intentionally excluded from logs to prevent credential leakage.

If you need to verify other JDBC options took effect, query the JDBC driver’s runtime metadata (for example, execute SELECT CURRENT_DATE and inspect the format) rather than relying on log inspection.

---

Environment Variables

Use environment variables to externalize sensitive configuration and support multiple environments:

Basic Pattern

sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 8076

.env file:

DB2i_HOST=ibmi-prod.example.com
DB2i_USER=MCPUSER
DB2i_PASS=SecurePassword123

Default Values

Provide fallback values for optional settings:

sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: ${DB2i_PORT:8076}                           # Defaults to 8076
    ignore-unauthorized: ${DB2i_IGNORE_UNAUTHORIZED:false}  # Defaults to false

Syntax: ${VARIABLE_NAME:default_value} - Use : to specify default values that apply when the environment variable is not set.

---

Multiple Sources

Define multiple sources for different environments, systems, or use cases:

Multi-Environment Setup

sources:
  production:
    host: ${PROD_DB2i_HOST}
    user: ${PROD_DB2i_USER}
    password: ${PROD_DB2i_PASS}
    port: 8076
    ignore-unauthorized: false
    connectionTimeout: 30000
    requestTimeout: 120000

  development:
    host: ${DEV_DB2i_HOST}
    user: ${DEV_DB2i_USER}
    password: ${DEV_DB2i_PASS}
    port: 8076
    ignore-unauthorized: true  # Self-signed certs OK in dev
    connectionTimeout: 10000
    requestTimeout: 60000

  testing:
    host: ${TEST_DB2i_HOST}
    user: ${TEST_DB2i_USER}
    password: ${TEST_DB2i_PASS}
    port: 8076
    ignore-unauthorized: true
    connectionTimeout: 15000
    requestTimeout: 30000

Tool Usage:

tools:
  production_health_check:
    source: production  # Uses production source
    description: "Production system health metrics"
    # ... rest of configuration

  development_sandbox:
    source: development  # Uses development source
    description: "Development environment testing"
    # ... rest of configuration

Multi-System Setup

Connect to multiple IBM i systems in a single configuration:

sources:
  primary-ibmi:
    host: ${PRIMARY_DB2i_HOST}
    user: ${PRIMARY_DB2i_USER}
    password: ${PRIMARY_DB2i_PASS}
    port: 8076
    ignore-unauthorized: false

  secondary-ibmi:
    host: ${SECONDARY_DB2i_HOST}
    user: ${SECONDARY_DB2i_USER}
    password: ${SECONDARY_DB2i_PASS}
    port: 8076
    ignore-unauthorized: false

  reporting-ibmi:
    host: ${REPORTING_DB2i_HOST}
    user: ${REPORTING_DB2i_USER}
    password: ${REPORTING_DB2i_PASS}
    port: 8076
    ignore-unauthorized: false

---

Complete Configuration Examples

Development Configuration

sources:
  ibmi-dev:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 8076
    ignore-unauthorized: true

.env:

DB2i_HOST=ibmi-dev.local
DB2i_USER=DEVUSER
DB2i_PASS=DevPassword123

Production Configuration

sources:
  ibmi-production:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 8076
    ignore-unauthorized: false

.env:

DB2i_HOST=ibmi-prod.example.com
DB2i_USER=MCPUSER
DB2i_PASS=SecureProductionPassword

Custom Port Configuration

sources:
  ibmi-custom:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 9000  # Custom Mapepire port
    ignore-unauthorized: false

---

Security Best Practices

Environment Variables

Always use environment variables for:

• Hostnames
• User profiles
• Passwords
• Ports (if non-standard)

Never hardcode:

# ❌ BAD - Hardcoded credentials
sources:
  ibmi-system:
    host: ibmi-prod.example.com
    user: ADMIN
    password: Password123

# ✅ GOOD - Environment variables
sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}

Credential Rotation

Regular rotation strategy:

1. Update .env file with new credentials
2. Restart MCP server to apply changes
3. Test connection with simple tool
4. Update production after successful testing

Automated rotation:

• Use secrets management systems (Vault, AWS Secrets Manager)
• Configure automatic credential refresh
• Monitor for rotation failures

SSL/TLS Configuration

Production requirements:

• Valid SSL certificates from trusted CA
• ignore-unauthorized: false enforced
• Regular certificate renewal
• Strong cipher suites

Development exceptions:

• Self-signed certificates allowed
• ignore-unauthorized: true for testing only
• Never deploy to production with this setting

File Permissions

Protect YAML configuration files:

# Restrict to owner read/write only
chmod 600 my-tools.yaml

# Protect .env files
chmod 600 .env

# Never commit to version control
echo ".env" >> .gitignore
echo "*.yaml" >> .gitignore  # If contains secrets

---

Troubleshooting

Connection Refused

Symptom: ECONNREFUSED or “Connection refused” errors

Solutions:

1. Verify Mapepire daemon is running on IBM i:
   netstat -an | grep 8076
   
2. Check firewall rules allow connections
3. Verify hostname resolves correctly:
   ping ${DB2i_HOST}
   
4. Test port connectivity:
   telnet ${DB2i_HOST} 8076
   

Authentication Failures

Symptom: “Invalid credentials” or “User not authorized” errors

Solutions:

1. Verify environment variables are set:
   echo $DB2i_USER
   echo $DB2i_HOST
   
2. Test credentials directly on IBM i
3. Check user profile status (not disabled/expired)
4. Verify user has database authorities

Timeout Errors

Symptom: “Request timeout” or “Connection timeout” errors

Solutions:

1. Increase requestTimeout for long-running queries
2. Increase connectionTimeout for slow networks
3. Optimize SQL queries to run faster
4. Check network latency between server and IBM i

SSL Certificate Errors

Symptom: “Certificate verification failed” or “Self-signed certificate” errors

Solutions:

1. Development: Set ignore-unauthorized: true
2. Production: Install valid SSL certificates on IBM i
3. Update certificate trust store if needed
4. Verify certificate has not expired

---

Next Steps

Tools Reference

Learn about tool definitions and configuration

Toolsets Reference

Organize tools into logical groups

Building SQL Tools

Step-by-step guide to creating custom tools

Configuration Guide

Complete server configuration reference

Source Design Philosophy: Sources represent database connections, not business logic. Keep source configurations simple, secure, and environment-specific. Use environment variables for all sensitive data and support multiple environments with distinct source names.