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

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

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.

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

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

​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

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