Sources Reference

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)
Direct Values (Development Only)
IP Address

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

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

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
SSL 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.

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
Date Format
SQL Naming
Combined

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.

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.

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

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:

Update .env file with new credentials
Restart MCP server to apply changes
Test connection with simple tool
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” errorsSolutions:

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

Authentication Failures

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

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

Timeout Errors

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

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

SSL Certificate Errors

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

Development: Set ignore-unauthorized: true
Production: Install valid SSL certificates on IBM i
Update certificate trust store if needed
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.

Getting Started

Core Concepts

Server Configuration

SQL Tools System

Quick Reference

Basic Source Configuration

Source Fields Reference

Required Fields

Optional Fields

JDBC Options

Common Options

Full Property List

Environment Variable Override

Security: Credential Logging

Environment Variables

Basic Pattern

Default Values

Multiple Sources

Multi-Environment Setup

Multi-System Setup

Complete Configuration Examples

Development Configuration

Production Configuration

Custom Port Configuration

Security Best Practices

Troubleshooting

Next Steps

Tools Reference

Toolsets Reference

Building SQL Tools

Configuration Guide

Getting Started

Core Concepts

Server Configuration

SQL Tools System

​Quick Reference

​Basic Source Configuration

​Source Fields Reference

​Required Fields

​Optional Fields

​JDBC Options

​Common Options

​Full Property List

​Environment Variable Override

​Security: Credential Logging

​Environment Variables

​Basic Pattern

​Default Values

​Multiple Sources

​Multi-Environment Setup

​Multi-System Setup

​Complete Configuration Examples

​Development Configuration

​Production Configuration

​Custom Port Configuration

​Security Best Practices

​Troubleshooting

​Next Steps

Tools Reference

Toolsets Reference

Building SQL Tools

Configuration Guide

Quick Reference

Basic Source Configuration

Source Fields Reference

Required Fields

Optional Fields

JDBC Options

Common Options

Full Property List

Environment Variable Override

Security: Credential Logging

Environment Variables

Basic Pattern

Default Values

Multiple Sources

Multi-Environment Setup

Multi-System Setup

Complete Configuration Examples

Development Configuration

Production Configuration

Custom Port Configuration

Security Best Practices

Troubleshooting

Next Steps