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:Available Tool Categories
Thetools/ directory contains pre-built tool configurations organized by functional domain:
Loading Strategies
1. Load All Tools from Directory
Load every YAML file in thetools/ directory and all subdirectories:
Several of these files define the same
ibmi-system source. The definitions are identical, so the server merges them; YAML_ALLOW_DUPLICATE_SOURCES is not needed. DB2i_HOST, DB2i_USER and DB2i_PASS must be set, because the files reference them and an unset variable fails the load..env file in your working directory:
- Recursively scans
tools/for all.yamlfiles - Loads all tools from all categories
- Makes every toolset available to AI agents
- Merges sources, tools, and toolsets across files, in sorted path order
- Stops if any file fails to parse or validate, naming the file
Duplicate sources. Each YAML file is self-contained with its own source definitions, so the same source (like
ibmi-system) appears in several files. Identical definitions merge. If two files define one source name differently, the load fails and names both files; make them identical, or set YAML_ALLOW_DUPLICATE_SOURCES=true to use the last one.2. Load Specific Configuration File
Target a single YAML file for focused operations:- Performance Monitoring
- Security Analysis
- Sample Data
- System status and health
- Active job monitoring
- Memory pool utilization
- HTTP server statistics
- 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
3. Load Specific Toolsets
Select logical groups of tools across multiple files using toolset filtering:Single Toolset
- Performance Only
- Security Only
performance toolset are loaded, even though all YAML files are scanned.Multiple Toolsets
Combine related toolsets for comprehensive operations:Toolset Names: Use the exact toolset identifiers from the YAML configurations. Run
--list-toolsets to see available names. A name that no file defines stops the server at startup with Unknown toolsets requested: ....Environment Variables
Configure database connections and runtime behavior:Required Database Credentials
Server Configuration
Complete Example
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:- Test with MCP Inspector
- Test with Agno Agent
Scenario 2: Security Audit
Goal: Perform comprehensive security analysis. Start the server:- Test with MCP Inspector
- Test with Agno Agent
Scenario 3: Development Workflow
Goal: Help developers find and manage IBM i objects. Start the server:- Test with MCP Inspector
- Test with Agno Agent
Scenario 4: Production Monitoring Dashboard
Goal: Create a monitoring agent with specific tool access. Start the server:- Test with MCP Inspector
- Test with Agno Agent
Command Reference
CLI Options
Path Formats
The--tools argument accepts multiple formats:
- Single File
- Directory
- Glob Pattern
Troubleshooting
No Tools Loaded
Symptom: Server does not start, or starts with no tools. A tools path that does not exist, a directory without YAML files, an invalid file and an unset${VAR} all stop startup with an error that names the path or file.
Solutions:
-
Verify path exists:
-
Check path is relative to current directory:
-
Check for source errors:
Source '<name>' is defined differently in <fileA> and <fileB>means two files disagree about one source. Make the definitions identical, or setYAML_ALLOW_DUPLICATE_SOURCES=trueto use the last one. -
Review server logs:
The startup error is printed on stderr (
Startup failed. Invalid tool configuration in <file>: ...). With--transport httpthe server also logs to the console.
Connection Failures
Symptom: Tools load but queries fail with connection errors. Solutions:-
Verify environment variables:
-
Test connection manually:
-
Check SSL configuration:
Toolset Not Found
Symptom: The server exits at startup withUnknown toolsets requested: <names>. Available toolsets: <names>.
Solutions:
-
List available toolsets:
-
Check exact toolset names:
- Toolset names are case-sensitive
- Use underscores, not spaces:
security_auditnotsecurity audit
-
Verify toolset exists in YAML:
Best Practices
Development vs Production
Development vs Production
Development:
- Use
--transport httpfor easier debugging - Load all tools:
--tools ./tools(no toolset filter) - Enable debug logging:
MCP_LOG_LEVEL=debug - Allow SSL bypass:
DB2i_IGNORE_UNAUTHORIZED=true
- Use
--transport stdiofor MCP client integration - Load specific toolsets:
--toolsets performance - Use info logging:
MCP_LOG_LEVEL=info - Enforce SSL:
DB2i_IGNORE_UNAUTHORIZED=false
Organize by Access Level
Organize by Access Level
Create environment-specific configurations:
Performance Optimization
Performance Optimization
- Load only needed tools: Use
--toolsetsto reduce memory - Use specific files: Target exact YAML files instead of directories
- Monitor resource usage: Check
logs/combined.logfor performance metrics - Cache connections: The server automatically pools database connections
Security Considerations
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=infoin production - SSL enforcement: Set
DB2i_IGNORE_UNAUTHORIZED=falsefor 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.