Using Default Tools

The IBM i MCP Server includes a curated collection of pre-built SQL tools in the tools/ directory. These production-ready tools cover common IBM i operations from system monitoring to security analysis, allowing you to start building AI agents immediately without writing custom YAML configurations.

Prerequisites: This guide assumes you’ve completed the Quickstart and have:

IBM i database credentials configured (DB2i_HOST, DB2i_USER, DB2i_PASS)
Access to the pre-built tools directory (clone or download from GitHub)

Getting the Tools Directory

Download the pre-built tools from the repository:

git clone https://github.com/IBM/ibmi-mcp-server.git
cd ibmi-mcp-server

All examples use npx @ibm/ibmi-mcp-server to run the published package. Point --tools to wherever you’ve saved the tools/ directory.

Available Tool Categories

The tools/ directory contains pre-built tool configurations organized by functional domain:

Directory	Category	Description	Key Tools
sample/	Sample Data	Demonstration tools using IBM i SAMPLE schema (employee, department, project data)	Employee lookup, department analysis, project management
sys-admin/	System Administration	High-level system service discovery and metadata exploration	Service catalogs, schema browsing, example queries
security/	Security Analysis	Library list security assessment and vulnerability detection	Library list configuration, authority checks, security analysis
performance/	Performance Monitoring	System performance metrics and resource utilization	System status, active jobs, memory pools, HTTP server stats
developer/	Development Tools	Object statistics and dependency analysis for developers	Recently used objects, stale object detection, dependency tracking

List All Available Toolsets:

npx @ibm/ibmi-mcp-server --list-toolsets --tools ./tools

This command shows all toolsets with descriptions and tool counts.

Loading Strategies

1. Load All Tools from Directory

Load every YAML file in the tools/ directory and all subdirectories:

# Set environment variable to allow duplicate sources
export YAML_ALLOW_DUPLICATE_SOURCES=true

# HTTP transport (recommended for testing)
npx @ibm/ibmi-mcp-server --transport http --tools ./tools

# STDIO transport (for MCP client integration)
npx @ibm/ibmi-mcp-server --transport stdio --tools ./tools

Important: When loading all tools from the directory, you must set YAML_ALLOW_DUPLICATE_SOURCES=true. Multiple YAML files define the same database sources (e.g., ibmi-system), and this setting allows the server to merge them instead of failing with a duplicate source error.

Alternative: Use .env file Create a .env file in your working directory:

# .env
YAML_ALLOW_DUPLICATE_SOURCES=true
DB2i_HOST=your-ibmi-system.local
DB2i_USER=YOURUSERID
DB2i_PASS=YourPassword

Then start the server:

npx @ibm/ibmi-mcp-server --transport http --tools ./tools

What happens:

Recursively scans tools/ for all .yaml files
Loads all tools from all categories
Makes every toolset available to AI agents
Merges sources, tools, and toolsets across files
Allows duplicate source definitions (e.g., ibmi-system appears in multiple files)

Why Duplicate Sources? Each YAML file is designed to be self-contained with its own source definitions. When loading multiple files, the same database connection (like ibmi-system) appears in multiple files. The YAML_ALLOW_DUPLICATE_SOURCES=true setting intelligently merges these duplicate definitions.

2. Load Specific Configuration File

Target a single YAML file for focused operations:

Performance Monitoring
Security Analysis
Sample Data

# Load only performance monitoring tools
npx @ibm/ibmi-mcp-server \
  --transport http \
  --tools ./tools/performance/performance.yaml

Includes tools for:

System status and health
Active job monitoring
Memory pool utilization
HTTP server statistics

# Load only security analysis tools
npx @ibm/ibmi-mcp-server \
  --transport http \
  --tools ./tools/security/library-list-security.yaml

Includes tools for:

Library list configuration
Authority validation
Security vulnerability detection

# Load sample employee database tools
npx @ibm/ibmi-mcp-server \
  --transport http \
  --tools ./tools/sample/employee-info.yaml

Includes tools for:

Employee information lookup
Department analysis
Project assignment queries

Benefits:

Fast startup - Only loads tools from specified file
Clear scope - Agent sees only relevant tools for the task
Easy debugging - Isolated tool configuration
Production ready - Minimal resource usage
No duplicate sources - Single file = single source definition

3. Load Specific Toolsets

Select logical groups of tools across multiple files using toolset filtering:

Discover Available Toolsets: Before loading specific toolsets, list all available default toolsets and their tools:

npx @ibm/ibmi-mcp-server --list-toolsets --tools ./tools

This shows toolset names, descriptions, and tool counts to help you choose which ones to load.

Single Toolset

Performance Only
Security Only

export YAML_ALLOW_DUPLICATE_SOURCES=true

npx @ibm/ibmi-mcp-server \
  --transport http \
  --tools ./tools \
  --toolsets performance_monitoring

Result: Only tools tagged with performance_monitoring toolset are loaded, even though all YAML files are scanned.

export YAML_ALLOW_DUPLICATE_SOURCES=true

npx @ibm/ibmi-mcp-server \
  --transport http \
  --tools ./tools \
  --toolsets security_audit

Result: Only security analysis tools are available to AI agents.

Multiple Toolsets

Combine related toolsets for comprehensive operations:

# Required when loading from directory
export YAML_ALLOW_DUPLICATE_SOURCES=true

# System administration and monitoring
npx @ibm/ibmi-mcp-server \
  --transport http \
  --tools ./tools \
  --toolsets performance_monitoring,system_admin

# Development workflow
npx @ibm/ibmi-mcp-server \
  --transport http \
  --tools ./tools \
  --toolsets developer_tools,sample_data

# Security and compliance
npx @ibm/ibmi-mcp-server \
  --transport http \
  --tools ./tools \
  --toolsets security_audit,system_admin

Toolset Names: Use the exact toolset identifiers from the YAML configurations. Run --list-toolsets to see available names.

Environment Variables

Configure database connections and runtime behavior:

Required Database Credentials

# IBM i connection details
export DB2i_HOST="your-ibmi-system.local"
export DB2i_USER="YOURUSERID"
export DB2i_PASS="YourPassword"

# Optional: Custom port (default: 8076)
export DB2i_PORT=8076

# Optional: SSL validation (default: true in production)
export DB2i_IGNORE_UNAUTHORIZED=true  # Development only

Server Configuration

# HTTP transport settings
export MCP_HTTP_PORT=3010
export MCP_HTTP_HOST="0.0.0.0"

# Logging configuration
export MCP_LOG_LEVEL=debug  # debug | info | warning | error

# Pre-select toolsets at startup
export SELECTED_TOOLSETS="performance_monitoring,security_audit"

# YAML configuration (important when loading all tools)
export YAML_ALLOW_DUPLICATE_SOURCES=true  # Required when loading tools/ directory
export YAML_ALLOW_DUPLICATE_TOOLS=false   # Prevent accidental tool name conflicts

Complete Example

# Set environment variables
export DB2i_HOST="ibmi-dev.mycompany.local"
export DB2i_USER="DEVUSER"
export DB2i_PASS="DevPassword123"
export MCP_LOG_LEVEL=debug
export MCP_HTTP_PORT=3010

# Required when loading all tools from directory
export YAML_ALLOW_DUPLICATE_SOURCES=true

# Start server with specific toolsets
npx @ibm/ibmi-mcp-server \
  --transport http \
  --tools ./tools \
  --toolsets performance_monitoring,developer_tools

Use .env Files: Create a .env file in your working directory for persistent configuration:

# .env
DB2i_HOST=ibmi-dev.mycompany.local
DB2i_USER=DEVUSER
DB2i_PASS=DevPassword123
MCP_LOG_LEVEL=debug
YAML_ALLOW_DUPLICATE_SOURCES=true

The server automatically loads environment variables from .env files in the current directory.

Usage Scenarios

Testing Your Server: Each scenario includes examples for testing with:

MCP Inspector: Interactive browser-based tool for exploring and testing MCP tools
Agno Agent (Python): Quick AI agent testing with natural language prompts (setup guide)

Scenario 1: Quick System Health Check

Goal: Monitor IBM i system health with AI assistance. Start the server:

# Load performance monitoring tools (single file - no duplicate sources needed)
npx @ibm/ibmi-mcp-server \
  --transport http \
  --tools ./tools/performance/performance.yaml

Test with MCP Inspector
Test with Agno Agent

# Open MCP Inspector in browser
npx @modelcontextprotocol/inspector \
  npx @ibm/ibmi-mcp-server --transport stdio --tools ./tools/performance/performance.yaml

In Inspector: Select any performance tool and fill in parameters to execute queries.

# From the client directory (requires setup - see link above)
cd client
uv run agent.py -p "Check the system health and identify any resource bottlenecks. Show me the top 5 CPU consumers."

The agent will automatically select and execute appropriate tools based on your natural language prompt.

Scenario 2: Security Audit

Goal: Perform comprehensive security analysis. Start the server:

# Allow duplicate sources when loading multiple toolsets
export YAML_ALLOW_DUPLICATE_SOURCES=true

# Load security and system admin tools
npx @ibm/ibmi-mcp-server \
  --transport http \
  --tools ./tools \
  --toolsets security_audit,system_admin

Test with MCP Inspector
Test with Agno Agent

# Set environment variable first
export YAML_ALLOW_DUPLICATE_SOURCES=true

# Open MCP Inspector
npx @modelcontextprotocol/inspector \
  npx @ibm/ibmi-mcp-server --transport stdio --tools ./tools --toolsets security_audit,system_admin

In Inspector: Explore security tools like library list analysis and authority checks.

# From the client directory
cd client
uv run agent.py -p "Analyze the library list configuration for security vulnerabilities. Check for any unauthorized access or suspicious authority levels."

The agent will use security-focused tools to perform the analysis.

Scenario 3: Development Workflow

Goal: Help developers find and manage IBM i objects. Start the server:

# Allow duplicate sources when loading multiple toolsets
export YAML_ALLOW_DUPLICATE_SOURCES=true

# Load developer tools and sample data
npx @ibm/ibmi-mcp-server \
  --transport http \
  --tools ./tools \
  --toolsets developer_tools,sample_data

Test with MCP Inspector
Test with Agno Agent

# Set environment variable first
export YAML_ALLOW_DUPLICATE_SOURCES=true

# Open MCP Inspector
npx @modelcontextprotocol/inspector \
  npx @ibm/ibmi-mcp-server --transport stdio --tools ./tools --toolsets developer_tools,sample_data

In Inspector: Test developer tools for object statistics and dependency tracking.

# From the client directory
cd client
uv run agent.py -p "Find all objects I modified in the last 7 days. Show me any stale objects that haven't been accessed recently."

The agent will query object statistics and provide development insights.

Scenario 4: Production Monitoring Dashboard

Goal: Create a monitoring agent with specific tool access. Start the server:

# Production configuration
export MCP_LOG_LEVEL=info
export MCP_HTTP_PORT=8080
export DB2i_IGNORE_UNAUTHORIZED=false  # Enforce SSL in production
export YAML_ALLOW_DUPLICATE_SOURCES=true  # Required for directory loading

# Start with performance monitoring only
npx @ibm/ibmi-mcp-server \
  --transport http \
  --tools ./tools \
  --toolsets performance_monitoring

Test with MCP Inspector
Test with Agno Agent

# Set environment variables
export YAML_ALLOW_DUPLICATE_SOURCES=true
export MCP_LOG_LEVEL=info

# Open MCP Inspector
npx @modelcontextprotocol/inspector \
  npx @ibm/ibmi-mcp-server --transport stdio --tools ./tools --toolsets performance_monitoring

In Inspector: Monitor real-time system performance metrics.

# From the client directory
# Update url in agent.py if using custom port (default: 3010)
cd client
uv run agent.py -p "Show me current system status and identify any performance issues."

The agent provides continuous monitoring with natural language queries.

Command Reference

CLI Options

Option	Alias	Description	Example
`--tools <path>`	-	Path to YAML tools (file, directory, or glob pattern)	`--tools tools/performance/performance.yaml`
`--toolsets <list>`	`-ts`	Comma-separated list of toolsets to load	`--toolsets performance_monitoring,security_audit`
`--transport <type>`	`-t`	Transport protocol: `stdio` or `http`	`--transport http`
`--list-toolsets`	-	Show all available toolsets and exit	`--list-toolsets --tools tools`
`--help`	`-h`	Display help message and exit	`--help`

Path Formats

The --tools argument accepts multiple formats:

Single File
Directory
Glob Pattern

# Specific YAML file
--tools tools/performance/performance.yaml
--tools /absolute/path/to/config.yaml
--tools ../relative/path/to/config.yaml

# All YAML files in directory (recursive)
--tools tools
--tools tools/performance
--tools /absolute/path/to/tools

# Pattern matching (quote for shell safety)
--tools "tools/**/*.yaml"
--tools "tools/performance/*.yaml"
--tools "custom-tools/**/*-dev.yaml"

Troubleshooting

No Tools Loaded

Symptom: Server starts but no tools are available. Solutions:

Verify path exists:

ls -la ./tools/performance/performance.yaml

Check path is relative to current directory:

# Use ./ prefix for relative paths
npx @ibm/ibmi-mcp-server --tools ./tools

# Or use absolute paths
npx @ibm/ibmi-mcp-server --tools /full/path/to/tools

Check for duplicate source errors:

# If loading from directory, ensure this is set
export YAML_ALLOW_DUPLICATE_SOURCES=true

Review server logs: The server outputs to console when using --transport http. Look for YAML parsing errors in the startup output.

Connection Failures

Symptom: Tools load but queries fail with connection errors. Solutions:

Verify environment variables:

echo $DB2i_HOST
echo $DB2i_USER
# DB2i_PASS won't echo for security

Test connection manually:

# Use IBM i Access Client Solutions or similar tool
# to verify credentials and network access

Check SSL configuration:

# For development, disable SSL verification
export DB2i_IGNORE_UNAUTHORIZED=true

Toolset Not Found

Symptom: --toolsets specified but tools don’t load. Solutions:

List available toolsets:

npx @ibm/ibmi-mcp-server \
  --list-toolsets \
  --tools ./tools

Check exact toolset names:
- Toolset names are case-sensitive
- Use underscores, not spaces: performance_monitoring not performance monitoring
Verify toolset exists in YAML:
```
grep -r "toolsets:" ./tools/
```

Best Practices

Development vs Production

Development:

Use --transport http for easier debugging
Load all tools: --tools ./tools (no toolset filter)
Enable debug logging: MCP_LOG_LEVEL=debug
Allow SSL bypass: DB2i_IGNORE_UNAUTHORIZED=true
Set YAML_ALLOW_DUPLICATE_SOURCES=true in .env

Production:

Use --transport stdio for MCP client integration
Load specific toolsets: --toolsets performance_monitoring
Use info logging: MCP_LOG_LEVEL=info
Enforce SSL: DB2i_IGNORE_UNAUTHORIZED=false
Still need YAML_ALLOW_DUPLICATE_SOURCES=true if loading from directory

Organize by Access Level

Create environment-specific configurations:

# Developer access
--toolsets developer_tools,sample_data,system_admin

# DBA access
--toolsets performance_monitoring,security_audit,system_admin

# Auditor access (read-only)
--toolsets security_audit

Performance Optimization

Load only needed tools: Use --toolsets to reduce memory
Use specific files: Target exact YAML files instead of directories
Monitor resource usage: Check logs/combined.log for performance metrics
Cache connections: The server automatically pools database connections

Security Considerations

Credential management: Use environment variables, never hardcode
Least privilege: Load only toolsets needed for the agent’s role
Audit logging: Enable MCP_LOG_LEVEL=info in production
SSL enforcement: Set DB2i_IGNORE_UNAUTHORIZED=false for production
Read-only tools: Prefer query-only tools for non-admin agents

Next Steps

Building Custom Tools

Learn to create your own YAML SQL tools for custom IBM i operations

Tools Reference

Complete YAML tools configuration reference with all options

Toolsets Guide

Organize tools into logical groups for better agent discovery

Configuration Guide

Complete server configuration and environment variables

Examples Repository

View Default Tools on GitHub

Browse the complete collection of pre-built YAML tools with documentation and examples →

Contributing: Found a bug or want to add a new default tool? Contributions are welcome! See the Contributing Guide for details.

Getting Started

Core Concepts

Server Configuration

SQL Tools System

Getting the Tools Directory

Available Tool Categories

Loading Strategies

1. Load All Tools from Directory

2. Load Specific Configuration File

3. Load Specific Toolsets

Single Toolset

Multiple Toolsets

Environment Variables

Required Database Credentials

Server Configuration

Complete Example

Usage Scenarios

Scenario 1: Quick System Health Check

Scenario 2: Security Audit

Scenario 3: Development Workflow

Scenario 4: Production Monitoring Dashboard

Command Reference

CLI Options

Path Formats

Troubleshooting

No Tools Loaded

Connection Failures

Toolset Not Found

Best Practices

Next Steps

Building Custom Tools

Tools Reference

Toolsets Guide

Configuration Guide

Examples Repository

View Default Tools on GitHub

Getting Started

Core Concepts

Server Configuration

SQL Tools System

​Getting the Tools Directory

​Available Tool Categories

​Loading Strategies

​1. Load All Tools from Directory

​2. Load Specific Configuration File

​3. Load Specific Toolsets

​Single Toolset

​Multiple Toolsets

​Environment Variables

​Required Database Credentials

​Server Configuration

​Complete Example

​Usage Scenarios

​Scenario 1: Quick System Health Check

​Scenario 2: Security Audit

​Scenario 3: Development Workflow

​Scenario 4: Production Monitoring Dashboard

​Command Reference

​CLI Options

​Path Formats

​Troubleshooting

​No Tools Loaded

​Connection Failures

​Toolset Not Found

​Best Practices

​Next Steps

Building Custom Tools

Tools Reference

Toolsets Guide

Configuration Guide

​Examples Repository

View Default Tools on GitHub

Getting the Tools Directory

Available Tool Categories

Loading Strategies

1. Load All Tools from Directory

2. Load Specific Configuration File

3. Load Specific Toolsets

Single Toolset

Multiple Toolsets

Environment Variables

Required Database Credentials

Server Configuration

Complete Example

Usage Scenarios

Scenario 1: Quick System Health Check

Scenario 2: Security Audit

Scenario 3: Development Workflow

Scenario 4: Production Monitoring Dashboard

Command Reference

CLI Options

Path Formats

Troubleshooting

No Tools Loaded

Connection Failures

Toolset Not Found

Best Practices

Next Steps

Examples Repository