@ibm/ibmi-mcp-server
Advanced tools
Note — CLI moved. The
ibmicommand-line interface used to ship with this package. As of v0.5.0 it's a separate package: install it withnpm i -g @ibm/ibmi-cli. This package continues to provide theibmi-mcp-serverbinary. See packages/cli.
Get started with the IBM i MCP Server using the official npm package.
Create a .env file with your IBM i connection details:
cat > .env << 'EOF'
# IBM i DB2 for i Connection Settings
DB2i_HOST=your-ibmi-host.com
DB2i_USER=your-username
DB2i_PASS=your-password
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=true
# MCP Server Settings
MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010
MCP_LOG_LEVEL=info
# Tools Configuration
TOOLS_YAML_PATH=./tools
EOF
📖 Configuration Guide: See the complete Configuration section for all available settings.
Create a tools directory and a basic tool configuration file:
mkdir -p tools
sources:
ibmi-system:
host: ${DB2i_HOST}
user: ${DB2i_USER}
password: ${DB2i_PASS}
port: 8076
ignore-unauthorized: true
tools:
system_status:
source: ibmi-system
description: "Overall system performance statistics with CPU, memory, and I/O metrics"
parameters: []
statement: |
SELECT * FROM TABLE(QSYS2.SYSTEM_STATUS(RESET_STATISTICS=>'YES',DETAILED_INFO=>'ALL')) X
system_activity:
source: ibmi-system
description: "Current system activity information including active jobs and resource utilization"
parameters: []
statement: |
SELECT * FROM TABLE(QSYS2.SYSTEM_ACTIVITY_INFO())
active_job_info:
source: ibmi-system
description: "Find the top 10 consumers of CPU in the QUSRWRK and QSYSWRK subsystems"
parameters:
- name: limit
type: integer
default: 10
description: "Number of top CPU consumers to return"
statement: |
SELECT CPU_TIME, A.* FROM
TABLE(QSYS2.ACTIVE_JOB_INFO(SUBSYSTEM_LIST_FILTER => 'QUSRWRK,QSYSWRK')) A
ORDER BY CPU_TIME DESC
FETCH FIRST :limit ROWS ONLY
toolsets:
performance:
tools:
- system_status
- system_activity
- active_job_info
Create the file:
cat > tools/quickstart.yaml << 'EOF'
sources:
ibmi-system:
host: ${DB2i_HOST}
user: ${DB2i_USER}
password: ${DB2i_PASS}
port: 8076
ignore-unauthorized: true
tools:
system_status:
source: ibmi-system
description: "Overall system performance statistics with CPU, memory, and I/O metrics"
parameters: []
statement: |
SELECT * FROM TABLE(QSYS2.SYSTEM_STATUS(RESET_STATISTICS=>'YES',DETAILED_INFO=>'ALL')) X
system_activity:
source: ibmi-system
description: "Current system activity information including active jobs and resource utilization"
parameters: []
statement: |
SELECT * FROM TABLE(QSYS2.SYSTEM_ACTIVITY_INFO())
active_job_info:
source: ibmi-system
description: "Find the top 10 consumers of CPU in the QUSRWRK and QSYSWRK subsystems"
parameters:
- name: limit
type: integer
default: 10
description: "Number of top CPU consumers to return"
statement: |
SELECT CPU_TIME, A.* FROM
TABLE(QSYS2.ACTIVE_JOB_INFO(SUBSYSTEM_LIST_FILTER => 'QUSRWRK,QSYSWRK')) A
ORDER BY CPU_TIME DESC
FETCH FIRST :limit ROWS ONLY
toolsets:
performance:
tools:
- system_status
- system_activity
- active_job_info
EOF
This creates three tools:
system_status - System performance metricssystem_activity - Current activity informationactive_job_info - Top CPU consumers (with customizable limit parameter)[!NOTE] 📖 More Tools: The repository includes many ready-to-use tools in the
tools/directory covering performance monitoring, security, job management, and more. See SQL Tool Configuration to create your own custom tools.
Point the server to your configuration file using the MCP_SERVER_CONFIG environment variable:
# Set configuration file path
export MCP_SERVER_CONFIG=.env
Note: CLI arguments override settings in the configuration file.
Start the server in HTTP mode with your new tools:
# Start the server with HTTP transport
npx -y @ibm/ibmi-mcp-server@latest --transport http --tools ./tools/quckstart.yaml
The server will:
.env (via MCP_SERVER_CONFIG)http://localhost:3010/mcptools/quickstart.yamlTest the server endpoint:
# Check health
curl http://localhost:3010/healthz
# List available tools (requires running server)
curl -X POST http://localhost:3010/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'
Install and run the example Python client:
# Navigate to client directory
cd client/
# Install dependencies with uv
uv sync
# List available tools
uv run mcp_client.py
# Run agent with LLM (requires API key)
export OPENAI_API_KEY=your-api-key
uv run agent.py -p "What is my system status?"
📖 Client Documentation: See client/README.md for detailed setup instructions.
[!TIP] Explore More SQL Tools: The
tools/directory contains many ready-to-use SQL tool configurations for common IBM i tasks. Browse the collection and customize them for your needs. See the Tools Guide for more details.
Choose your path based on what you want to accomplish:
| Path | Guide | Description |
|---|---|---|
| MCP Client Integration | Installing in MCP Clients | Connect to Claude Desktop, VSCode, Cursor, and other MCP clients |
| Custom SQL Tools | SQL Tool Configuration | Create YAML-based SQL tools for your IBM i use cases |
| Server Configuration | Configuration Guide | Explore authentication, transport modes, and environment variables |
| Production Deployment | Deployment Options | Deploy with Docker, Podman, or OpenShift |
| AI Agent Development | IBM i Agents | Build custom AI agents that interact with IBM i systems |
| Development & Contributing | Running the Server (Development) | Build from source, run tests, and contribute |
The IBM i MCP Server provides a command-line interface with flexible options for running and configuring the server.
npx -y @ibm/ibmi-mcp-server@latest [options]
Note: The
-yflag automatically accepts the npm package installation prompt.
| Option | Description |
|---|---|
--tools <path> | Path to YAML tools (file, directory, or glob pattern) |
--toolsets <list> | Comma-separated list of toolsets to load |
--list-toolsets | List all available toolsets and exit |
--transport <type> | Transport type: stdio (default) or http |
--builtin-tools | Enable built-in schema discovery tools (list_schemas, list_tables_in_schema, get_table_columns, get_related_objects, validate_query) |
--execute-sql | Enable the execute_sql tool for ad-hoc queries |
--help | Show help message |
Full text-to-SQL workflow (schema discovery + query execution):
npx -y @ibm/ibmi-mcp-server@latest --builtin-tools --execute-sql --transport http
Schema discovery only (agents explore but can't run arbitrary SQL):
npx -y @ibm/ibmi-mcp-server@latest --builtin-tools --tools ./tools
Run server with YAML tools only:
npx -y @ibm/ibmi-mcp-server@latest --transport http --tools ./tools
Load specific toolsets only:
npx -y @ibm/ibmi-mcp-server@latest --toolsets performance,security --tools ./tools
List available toolsets:
npx -y @ibm/ibmi-mcp-server@latest --list-toolsets --tools ./tools
This server can be integrated into any MCP-compatible client using either local (stdio) or remote (HTTP) connections.
The server is available as an npm package and can be used directly with npx:
# Test the server is available
npx -y @ibm/ibmi-mcp-server@latest --help
Note: The
-yflag automatically accepts the npm package installation prompt.TOOLS_YAML_PATHmust be an absolute path to your tools configuration directory (e.g.,/full/path/to/tools).
For HTTP remote connections, you need to:
Start the server with IBM i authentication enabled:
# Ensure your .env has these settings:
MCP_AUTH_MODE=ibmi
IBMI_HTTP_AUTH_ENABLED=true
IBMI_AUTH_ALLOW_HTTP=true # For development only!
npm run start:http
Obtain an access token:
# Use the token script to authenticate
node get-access-token.js --verbose
# Or set it directly in your environment
export IBMI_MCP_ACCESS_TOKEN="your-token-here"
See IBM i HTTP Authentication for detailed authentication setup.
Configure your client with the server URL and Bearer token (examples below).
⚠️ Production Note: Replace
http://localhost:3010with your production endpoint URL and ensure HTTPS is enabled (IBMI_AUTH_ALLOW_HTTP=false).
In production environments, it is strongly recommended to deploy the MCP server behind a reverse proxy server such as Nginx, HAProxy, or Caddy. The reverse proxy server can provide TLS/SSL termination for the MCP server to handle HTTPS connections and SSL/TLS certificate management. Below is an example of an Nginx configuration. You may need to adjust it according to your specific networking configuration and security requirements.
pid /run/nginx.pid;
events {}
http {
server {
listen 443 ssl;
ssl_certificate <path_to_certificate>;
ssl_certificate_key <path_to_privatekey>;
ssl_protocols TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_session_cache shared:SSL:50m;
ssl_prefer_server_ciphers on;
# This is needed for getting access token when IBM i HTTP authentication enabled with HTTPS only
proxy_set_header X-Forwarded-Proto https;
location / {
proxy_pass http://mcp_server;
}
}
upstream mcp_server {
server 127.0.0.1:3010;
}
}
Claude Code supports both local (stdio) and remote (HTTP) MCP server connections. You can configure servers using the CLI or by editing .mcp.json directly.
Using CLI:
# Add local stdio server
claude mcp add ibmi-mcp \
--env DB2i_HOST=your-ibmi-host.com \
--env DB2i_USER=your-username \
--env DB2i_PASS=your-password \
--env DB2i_PORT=8076 \
--env MCP_TRANSPORT_TYPE=stdio \
-- npx -y @ibm/ibmi-mcp-server@latest --transport stdio --tools /absolute/path/to/tools
Using .mcp.json:
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["@ibm/ibmi-mcp-server@latest", "-y", "--transport", "stdio", "--tools", "/absolute/path/to/tools"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076",
"NODE_OPTIONS": "--no-deprecation"
}
}
}
}
Using CLI:
# Add remote HTTP server with authentication
claude mcp add --transport http ibmi-mcp http://localhost:3010/mcp \
--header "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"
Using .mcp.json:
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
Claude Code supports environment variable expansion in .mcp.json files, allowing you to keep credentials secure:
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["@ibm/ibmi-mcp-server@latest", "-y", "--transport", "stdio", "--tools", "${IBMI_TOOLS_PATH}"],
"env": {
"DB2i_HOST": "${DB2i_HOST}",
"DB2i_USER": "${DB2i_USER}",
"DB2i_PASS": "${DB2i_PASS}",
"DB2i_PORT": "${DB2i_PORT:-8076}"
}
}
}
}
Supported syntax:
${VAR} - Expands to the value of environment variable VAR${VAR:-default} - Expands to VAR if set, otherwise uses default# List configured servers
claude mcp list
# Get server details
claude mcp get ibmi-mcp
# Remove a server
claude mcp remove ibmi-mcp
# Check server status in Claude Code
/mcp
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["@ibm/ibmi-mcp-server@latest", "-y", "--transport", "stdio", "--tools", "/absolute/path/to/tools"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076"
}
}
}
}
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
VSCode supports MCP servers through Copilot Chat. You can configure servers at the user or workspace level using configuration files or the CLI.
Prerequisites: Ensure GitHub Copilot is installed and enabled.
.vscode/mcp.json (shared with team via version control)mcp.json in your user profile directory
~/.config/Code/User/globalStorage/modelcontextprotocol.mcp/mcp.json%APPDATA%\Code\User\globalStorage\modelcontextprotocol.mcp\mcp.jsonUsing CLI:
# Add local stdio server
code --add-mcp '{
"name": "ibmiMcp",
"type": "stdio",
"command": "npx",
"args": ["@ibm/ibmi-mcp-server@latest", "-y", "--transport", "stdio", "--tools", "/absolute/path/to/tools"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076"
}
}'
Using mcp.json:
{
"servers": {
"ibmiMcp": {
"type": "stdio",
"command": "npx",
"args": ["@ibm/ibmi-mcp-server@latest", "-y", "--transport", "stdio", "--tools", "/absolute/path/to/tools"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076"
}
}
}
}
Using CLI:
# Add remote HTTP server
code --add-mcp '{
"name": "ibmiMcp",
"type": "http",
"url": "http://localhost:3010/mcp",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}'
Using mcp.json:
{
"servers": {
"ibmiMcp": {
"type": "http",
"url": "http://localhost:3010/mcp",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
VSCode supports input variables to avoid hardcoding sensitive credentials:
{
"inputs": [
{
"id": "db2iHost",
"type": "promptString",
"description": "IBM i DB2 host address"
},
{
"id": "db2iUser",
"type": "promptString",
"description": "IBM i username"
},
{
"id": "db2iPass",
"type": "promptString",
"description": "IBM i password",
"password": true
}
],
"servers": {
"ibmiMcp": {
"type": "stdio",
"command": "npx",
"args": ["@ibm/ibmi-mcp-server@latest", "-y", "--transport", "stdio", "--tools", "/absolute/path/to/tools"],
"env": {
"DB2i_HOST": "${input:db2iHost}",
"DB2i_USER": "${input:db2iUser}",
"DB2i_PASS": "${input:db2iPass}",
"DB2i_PORT": "8076"
}
}
}
}
VSCode will prompt for these values when the server starts, keeping credentials secure.
Cmd/Ctrl+Shift+P) → "MCP: Restart Server"mcp.json or disable in settingsAdd to Cursor settings or .cursor/mcp.json:
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["@ibm/ibmi-mcp-server@latest", "-y", "--transport", "stdio", "--tools", "/absolute/path/to/tools"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076"
}
}
}
}
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
Add to Windsurf configuration:
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["@ibm/ibmi-mcp-server@latest", "-y", "--transport", "stdio", "--tools", "/absolute/path/to/tools"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076"
}
}
}
}
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
Configure in Roo Code settings:
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["@ibm/ibmi-mcp-server@latest", "-y", "--transport", "stdio", "--tools", "/absolute/path/to/tools"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076"
}
}
}
}
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["@ibm/ibmi-mcp-server@latest", "-y", "--transport", "stdio", "--tools", "/absolute/path/to/tools"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076",
"NODE_OPTIONS": "--no-deprecation"
}
}
}
}
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
Add local MCP servers using "type": "local" within the MCP object. Multiple MCP servers can be added. The key string for each server can be any arbitrary name.
opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"ibmi-mcp": {
"type": "local",
"enabled": true,
"command": ["npx", "@ibm/ibmi-mcp-server@latest", "-y", "--transport", "stdio", "--tools", "/absolute/path/to/tools"],
"environment": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076"
},
"enabled": true
}
}
}
You can also disable a server by setting enabled to false. This is useful if you want to temporarily disable a server without removing it from your config.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"ibmi-mcp": {
"type": "remote",
"enabled": true,
"url": "http://localhost:3010/mcp",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
See Gemini CLI Configuration for details.
~/.gemini/settings.json (where ~ is your home directory).mcpServers object in your settings.json file:Configure in Gemini CLI settings:
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["@ibm/ibmi-mcp-server@latest", "-y", "--transport", "stdio", "--tools", "/absolute/path/to/tools"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076"
}
}
}
}
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
Cline supports MCP servers through both the marketplace and manual configuration.
Prerequisites: Ensure Cline is installed in VSCode.
For Local (Stdio) Server:
{
"mcpServers": {
"ibmi-mcp": {
"command": "npx",
"args": ["@ibm/ibmi-mcp-server@latest", "-y", "--transport", "stdio", "--tools", "/absolute/path/to/tools"],
"env": {
"DB2i_HOST": "your-ibmi-host.com",
"DB2i_USER": "your-username",
"DB2i_PASS": "your-password",
"DB2i_PORT": "8076"
}
}
}
}
For Remote (HTTP) Server:
{
"mcpServers": {
"ibmi-mcp": {
"url": "http://localhost:3010/mcp",
"type": "streamableHttp",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
}
}
}
}
import asyncio
import os
from agno.agent import Agent
from agno.tools.mcp import MCPTools, StreamableHTTPClientParams
# Get access token from environment
token = os.environ.get('IBMI_MCP_ACCESS_TOKEN')
if not token:
raise ValueError("IBMI_MCP_ACCESS_TOKEN not set")
url = "http://localhost:3010/mcp"
server_params = StreamableHTTPClientParams(
url=url,
headers={"Authorization": f"Bearer {token}"}
)
async def main():
async with MCPTools(
url=url,
server_params=server_params,
transport="streamable-http"
) as tools:
# List available tools
result = await tools.session.list_tools()
print(f"Available tools: {[t.name for t in result.tools]}")
# Create agent
agent = Agent(
model="openai:gpt-4o", # or your preferred model
tools=[tools],
name="ibmi-agent",
show_tool_calls=True
)
# Run query
await agent.aprint_response("What is the system status?")
if __name__ == "__main__":
asyncio.run(main())
import asyncio
import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async def main():
token = os.environ.get('IBMI_MCP_ACCESS_TOKEN')
if not token:
raise ValueError("IBMI_MCP_ACCESS_TOKEN not set")
headers = {"Authorization": f"Bearer {token}"}
async with streamablehttp_client(
"http://localhost:3010/mcp",
headers=headers
) as (read_stream, write_stream, _):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
# List tools
tools = await session.list_tools()
print(f"Tools: {[t.name for t in tools.tools]}")
# Execute a tool
result = await session.call_tool("system_status", {})
print(result)
if __name__ == "__main__":
asyncio.run(main())
MCP servers can be added directly in IBM watsonx Orchestrate GUI or using the Agent Development Kit (ADK). Refer to Adding MCP servers in IBM watsonx Orchestrate for more details.
It's not supported to run a local IBM i MCP server in IBM watsonx Orchestrate for now. Support will be added in a later release.
The example below shows how to add a remote IBM i MCP server in IBM watsonx Orchestrate using using the Agent Development Kit (ADK). Refer to Adding remote MCP server in IBM watsonx Orchestrate for more details.
Create Connections to contain the environment variables and authentication token for the MCP server
# create connection for environment variables
orchestrate connections add -a <application_id>
orchestrate connections configure -a <application_id> --env draft -t team -k key_value
orchestrate connections set-credentials -a application_id --env draft -e "DB2i_HOST=your-ibmi-host.com" -e "DB2i_USER=your-username" -e "DB2i_PASS=your-password" -e "DB2i_PORT=8076"
# create connection for credential user for authentication if authentication is enabled on the MCP server
orchestrate connections add -a <application_id>
orchestrate connections configure -a <application_id> --env draft --type team --kind bearer
orchestrate connections set-credentials -a <application_id> --env draft --token <bearer_token>
Import remote IBM i MCP server by Importing remote MCP toolkits
orchestrate toolkits add \
--kind mcp \
--name <toolkit_name> \
--description "toolkit description" \
--url "<mcp_url>" \
--transport "streamable_http" \
--tools "*" \
--app-id "<connection_application_id>"
Create an agent to use the imported toolkit
orchestrate agents create \
--name <agent_name> \
--kind native \
--description "agent description" \
--llm groq/openai/gpt-oss-120b \
--style default \
--tools <toolkit_name> \
--output "agent_name.agent.yaml
Network Configuration for On-Premises Deployments: If the MCP server is deployed on an on-premises IBM i system behind an enterprise firewall, proper network configuration must be implemented to ensure accessibility from IBM watsonx Orchestrate. IBM Cloud Satellite Connector provides a secure solution for this scenario by establishing connectivity between on-premises resources and IBM Cloud services. For detailed information, refer to the IBM Cloud Satellite Connector documentation.
The primary way to configure tools used by this MCP server is through tools.yaml files (see tools/ for examples). There are 3 main sections to each yaml file: sources, tools, and toolsets. Below is a breakdown of each section.
The sources section of your tools.yaml defines the data sources the MCP server has access to:
sources:
ibmi-system:
host: ${DB2i_HOST}
user: ${DB2i_USER}
password: ${DB2i_PASS}
port: 8076
ignore-unauthorized: true
[!NOTE] The environment variables
DB2i_HOST,DB2i_USER,DB2i_PASS, andDB2i_PORTcan be set in the server.envfile. See Configuration for all available settings.
The tools section of your tools.yaml defines the actions your agent can take: what kind of tool it is, which source(s) it affects, what parameters it uses, etc.
tools:
system_status:
source: ibmi-system
description: "Overall system performance statistics with CPU, memory, and I/O metrics"
parameters: []
statement: |
SELECT * FROM TABLE(QSYS2.SYSTEM_STATUS(RESET_STATISTICS=>'YES',DETAILED_INFO=>'ALL')) X
The toolsets section of your tools.yaml allows you to define groups of tools that you want to be able to load together. This can be useful for defining different sets for different agents or different applications.
toolsets:
performance:
tools:
- system_status
- system_activity
- remote_connections
- memory_pools
- temp_storage_buckets
- unnamed_temp_storage
- http_server
- system_values
- collection_services
- collection_categories
- active_job_info
[!TIP] Advanced Tool Configuration: For detailed documentation on creating custom SQL tools, parameter validation, advanced queries, and more, see tools/README.md.
IBM i Agents are specialized components designed to interact with the IBM i system, providing capabilities such as monitoring, management, and automation.
Navigate to the agents directory and follow the setup instructions in the README. This includes details on configuration, running agents, and examples. Most agent examples require the MCP server to be running in HTTP mode. Read the docs for each agent example for details.
The server is configured using environment variables, typically set in a .env file at the project root. Configuration is organized into logical groups for easier management.
Quick Start:
cp .env.example .env
code .env # Edit with your settings
Core server configuration including server identity, transport mode, and logging.
| Variable | Description | Default | Required |
|---|---|---|---|
MCP_SERVER_NAME | Server name identifier for MCP protocol | Package name from package.json | No |
MCP_SERVER_VERSION | Server version for MCP protocol | Version from package.json | No |
MCP_TRANSPORT_TYPE | Transport protocol: stdio (local) or http (remote) | stdio | No |
MCP_LOG_LEVEL | Logging verbosity: error, warn, info, debug | debug | No |
LOGS_DIR | Directory for log files (relative to project root) | logs | No |
NODE_ENV | Node environment: development, production, test | development | No |
Examples:
# Development with verbose logging
MCP_SERVER_NAME=ibmi-mcp-dev
MCP_TRANSPORT_TYPE=http
MCP_LOG_LEVEL=debug
NODE_ENV=development
# Production with minimal logging
MCP_SERVER_NAME=ibmi-mcp-prod
MCP_TRANSPORT_TYPE=stdio
MCP_LOG_LEVEL=warn
NODE_ENV=production
Configuration for HTTP transport mode, including network settings, session management, and CORS.
| Variable | Description | Default | Required |
|---|---|---|---|
MCP_HTTP_PORT | HTTP server port | 3010 | No |
MCP_HTTP_HOST | HTTP server bind address | 127.0.0.1 | No |
MCP_HTTP_ENDPOINT_PATH | MCP endpoint path | /mcp | No |
MCP_SESSION_MODE | Session handling: stateless, stateful, or auto | auto | No |
MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS | Timeout for idle stateful sessions (milliseconds) | 1800000 (30 min) | No |
MCP_HTTP_MAX_PORT_RETRIES | Max attempts to find available port if default is in use | 15 | No |
MCP_HTTP_PORT_RETRY_DELAY_MS | Delay between port retry attempts (milliseconds) | 50 | No |
MCP_ALLOWED_ORIGINS | Comma-separated CORS allowed origins | None (all origins blocked) | No |
Session Modes:
auto: Automatically detects client capabilities and uses the best session modestateful: Maintains persistent sessions with connection state (best for long-running interactions)stateless: Each request is independent (best for load balancing and horizontal scaling)Examples:
# Development server with CORS for local web clients
MCP_HTTP_PORT=3010
MCP_HTTP_HOST=0.0.0.0 # Listen on all interfaces
MCP_SESSION_MODE=auto
MCP_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
# Production server with strict security
MCP_HTTP_PORT=443
MCP_HTTP_HOST=0.0.0.0
MCP_SESSION_MODE=stateful
MCP_ALLOWED_ORIGINS=https://app.example.com,https://dashboard.example.com
MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS=3600000 # 1 hour
Controls request rate limiting for the HTTP transport. Rate limiting prevents abuse and manages server load. For agentic AI workflows with parallel tool calls, increase the limit or disable rate limiting entirely.
| Variable | Description | Default | Required |
|---|---|---|---|
MCP_RATE_LIMIT_ENABLED | Enable or disable HTTP rate limiting | true | No |
MCP_RATE_LIMIT_MAX_REQUESTS | Maximum requests allowed per window | 100 | No |
MCP_RATE_LIMIT_WINDOW_MS | Rate limit window in milliseconds | 900000 (15 min) | No |
MCP_RATE_LIMIT_SKIP_DEV | Skip rate limiting when NODE_ENV=development | false | No |
Examples:
# Default: 100 requests per 15 minutes
MCP_RATE_LIMIT_ENABLED=true
MCP_RATE_LIMIT_MAX_REQUESTS=100
MCP_RATE_LIMIT_WINDOW_MS=900000
# Agentic workflows: higher limit, shorter window
MCP_RATE_LIMIT_MAX_REQUESTS=1000
MCP_RATE_LIMIT_WINDOW_MS=60000
# Disable rate limiting entirely (trusted environments)
MCP_RATE_LIMIT_ENABLED=false
Docker / Reverse Proxy: The server reads
X-Forwarded-ForandX-Real-IPheaders for client identification. When these are absent (e.g., behind Docker without proxy header forwarding), it falls back to the TCP socket's remote address. Configure your reverse proxy to forward these headers for accurate per-client rate limiting.
Controls automatic cleanup of idle Mapepire connection pools and query execution timeouts. Essential for cloud deployments (Railway, Heroku, etc.) where reverse proxies silently kill idle TCP connections, causing queries on stale WebSocket connections to hang indefinitely.
| Variable | Description | Default | Required |
|---|---|---|---|
MCP_POOL_IDLE_TIMEOUT_MS | Idle timeout for connection pools (ms). Pools closed after inactivity. Fresh connections established automatically on next request. Set to 0 to disable. | 300000 (5 min) | No |
MCP_POOL_QUERY_TIMEOUT_MS | Query execution timeout (ms). Queries aborted after this period. Pool re-initialized on next request after timeout. Set to 0 to disable. | 30000 (30s) | No |
Examples:
# Default: 5-minute idle timeout, 30-second query timeout
MCP_POOL_IDLE_TIMEOUT_MS=300000
MCP_POOL_QUERY_TIMEOUT_MS=30000
# Cloud deployment: shorter idle timeout for aggressive proxies
MCP_POOL_IDLE_TIMEOUT_MS=60000
MCP_POOL_QUERY_TIMEOUT_MS=30000
# Disable both timeouts (stable network environments only)
MCP_POOL_IDLE_TIMEOUT_MS=0
MCP_POOL_QUERY_TIMEOUT_MS=0
How it works: The idle timer checks pools at an interval of
max(10s, timeout/2). When a pool exceeds the idle timeout, it is closed — the next query triggers transparent re-initialization via the existing lazy-init path. The query timeout wrapspool.execute()withPromise.race(), so dead connections fail fast instead of hanging. On timeout, the pool is marked unhealthy and closed for re-initialization.
Security configuration for protecting the MCP server and authenticating clients.
| Variable | Description | Default | Required |
|---|---|---|---|
MCP_AUTH_MODE | Authentication mode: none, jwt, oauth, ibmi | none | No |
Required when MCP_AUTH_MODE=jwt.
| Variable | Description | Default | Required |
|---|---|---|---|
MCP_AUTH_SECRET_KEY | Secret key for signing/verifying JWT tokens (min 32 characters) | None | ✅ Yes (for JWT mode) |
Required when MCP_AUTH_MODE=oauth.
| Variable | Description | Default | Required |
|---|---|---|---|
OAUTH_ISSUER_URL | OAuth authorization server issuer URL | None | ✅ Yes (for OAuth mode) |
OAUTH_JWKS_URI | OAuth JWKS endpoint for public key verification | None | No |
OAUTH_AUDIENCE | Expected audience identifier for this MCP server | None | ✅ Yes (for OAuth mode) |
Required when MCP_AUTH_MODE=ibmi. See IBM i HTTP Authentication for detailed setup.
| Variable | Description | Default | Required |
|---|---|---|---|
IBMI_HTTP_AUTH_ENABLED | Enable IBM i authentication endpoints | false | ✅ Yes (for IBM i mode) |
IBMI_AUTH_ALLOW_HTTP | Allow HTTP (non-HTTPS) authentication requests | false | No |
IBMI_AUTH_TOKEN_EXPIRY_SECONDS | Token lifetime in seconds | 3600 (1 hour) | No |
IBMI_AUTH_CLEANUP_INTERVAL_SECONDS | How often to clean up expired tokens (seconds) | 300 (5 minutes) | No |
IBMI_AUTH_MAX_CONCURRENT_SESSIONS | Maximum concurrent authenticated sessions | 100 | No |
IBMI_AUTH_PRIVATE_KEY_PATH | Path to RSA private key for encryption | None | ✅ Yes (for IBM i mode) |
IBMI_AUTH_PUBLIC_KEY_PATH | Path to RSA public key for encryption | None | ✅ Yes (for IBM i mode) |
IBMI_AUTH_KEY_ID | Identifier for the RSA keypair | None | ✅ Yes (for IBM i mode) |
Examples:
# No authentication (development only)
MCP_AUTH_MODE=none
# JWT authentication
MCP_AUTH_MODE=jwt
MCP_AUTH_SECRET_KEY="your-very-secret-key-at-least-32-characters-long"
# OAuth authentication
MCP_AUTH_MODE=oauth
OAUTH_ISSUER_URL=https://auth.example.com
OAUTH_AUDIENCE=https://api.example.com/mcp
OAUTH_JWKS_URI=https://auth.example.com/.well-known/jwks.json
# IBM i authentication (see docs for keypair generation)
MCP_AUTH_MODE=ibmi
IBMI_HTTP_AUTH_ENABLED=true
IBMI_AUTH_KEY_ID=production
IBMI_AUTH_PRIVATE_KEY_PATH=secrets/private.pem
IBMI_AUTH_PUBLIC_KEY_PATH=secrets/public.pem
IBMI_AUTH_ALLOW_HTTP=false # HTTPS only in production
IBMI_AUTH_TOKEN_EXPIRY_SECONDS=7200 # 2 hours
⚠️ Security Notes:
MCP_AUTH_MODE=none in productionIBMI_AUTH_ALLOW_HTTP=false in production (requires HTTPS)Configuration for connecting to IBM i Db2 for i databases via Mapepire.
| Variable | Description | Default | Required |
|---|---|---|---|
DB2i_HOST | IBM i system hostname or IP address | None | ✅ Yes (for SQL tools) |
DB2i_USER | IBM i user profile for database connections | None | ✅ Yes (for SQL tools) |
DB2i_PASS | Password for IBM i user profile | None | ✅ Yes (for SQL tools) |
DB2i_PORT | Mapepire daemon/gateway port | 8076 | No |
DB2i_IGNORE_UNAUTHORIZED | Skip TLS certificate verification (for self-signed certs) | true | No |
Connection Flow:
DB2i_HOST:DB2i_PORTDB2i_USER and DB2i_PASSExamples:
# Development connection with self-signed certs
DB2i_HOST=ibmi-dev.example.com
DB2i_USER=DEVUSER
DB2i_PASS=devpassword
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=true
# Production connection with verified SSL
DB2i_HOST=ibmi-prod.example.com
DB2i_USER=PRODUSER
DB2i_PASS=strongProductionPassword123
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=false # Require valid SSL cert
# Connecting to Mapepire gateway
DB2i_HOST=mapepire-gateway.example.com
DB2i_USER=APIUSER
DB2i_PASS=apiPassword456
DB2i_PORT=443 # Gateway on HTTPS
DB2i_IGNORE_UNAUTHORIZED=false
⚠️ Security Notes:
DB2i_IGNORE_UNAUTHORIZED=false with valid SSL certificates in productionSettings for loading and managing SQL tools defined in YAML configuration files. See Tools Documentation for YAML tool development.
| Variable | Description | Default | Required |
|---|---|---|---|
TOOLS_YAML_PATH | Path to YAML tool configurations (file, directory, or glob) | None | No |
SELECTED_TOOLSETS | Comma-separated list of toolsets to load (filters available tools) | None (load all) | No |
YAML_AUTO_RELOAD | Automatically reload tools when YAML files change | true | No |
When loading multiple YAML files, these settings control merge behavior:
| Variable | Description | Default | Required |
|---|---|---|---|
YAML_MERGE_ARRAYS | Merge arrays from multiple files (true) or replace them (false) | true | No |
YAML_ALLOW_DUPLICATE_TOOLS | Allow duplicate tool names across files | false | No |
YAML_ALLOW_DUPLICATE_SOURCES | Allow duplicate source names across files | false | No |
YAML_VALIDATE_MERGED | Validate merged configuration before loading tools | true | No |
Path Resolution:
TOOLS_YAML_PATH=tools/performance.yamlTOOLS_YAML_PATH=tools/ (loads all .yaml/.yml files)TOOLS_YAML_PATH=tools/**/*.yaml--tools to override at runtimeExamples:
# Load all tools from a directory
TOOLS_YAML_PATH=tools/
YAML_AUTO_RELOAD=true # Hot reload on file changes
# Load specific tools file
TOOLS_YAML_PATH=tools/performance-tools.yaml
SELECTED_TOOLSETS=monitoring,diagnostics
# Advanced merging (multiple config sources)
TOOLS_YAML_PATH=tools/
YAML_MERGE_ARRAYS=true # Combine toolsets from multiple files
YAML_ALLOW_DUPLICATE_TOOLS=false # Enforce unique tool names
YAML_VALIDATE_MERGED=true # Validate after merging
# Production: disable hot reload
TOOLS_YAML_PATH=/opt/mcp-tools/production.yaml
YAML_AUTO_RELOAD=false
CLI Override:
# Override TOOLS_YAML_PATH at runtime
npx ibmi-mcp-server --tools ./my-custom-tools
# Load specific toolsets only
npx ibmi-mcp-server --toolsets performance,security
Settings for controlling built-in MCP tools compiled into the server. These are separate from YAML-defined tools.
The IBM i MCP Server includes built-in tools for schema discovery, query validation, and SQL execution. All built-in tools are disabled by default (except describe_sql_object) and must be explicitly enabled via CLI flags or environment variables.
| Tool | Status | Purpose | CLI Flag | Env Variable |
|---|---|---|---|---|
describe_sql_object | ✅ Always enabled | Generate DDL for database objects | — | — |
list_schemas | Disabled by default | List available schemas/libraries | --builtin-tools | IBMI_ENABLE_DEFAULT_TOOLS |
list_tables_in_schema | Disabled by default | List tables, views, physical files in a schema | --builtin-tools | IBMI_ENABLE_DEFAULT_TOOLS |
get_table_columns | Disabled by default | Get column metadata for a table | --builtin-tools | IBMI_ENABLE_DEFAULT_TOOLS |
get_related_objects | Disabled by default | Find dependent objects for impact analysis | --builtin-tools | IBMI_ENABLE_DEFAULT_TOOLS |
validate_query | Disabled by default | Validate SQL syntax and verify referenced objects | --builtin-tools | IBMI_ENABLE_DEFAULT_TOOLS |
execute_sql | ⚠️ Disabled by default | Execute ad-hoc SQL queries (readonly by default) | --execute-sql | IBMI_ENABLE_EXECUTE_SQL |
Tip: Use
--builtin-tools --execute-sqltogether for the full text-to-SQL workflow. Use--builtin-toolsalone to let agents discover schema while routing queries through curated YAML tools.
The describe_sql_object tool generates SQL DDL (Data Definition Language) statements for IBM i database objects using the QSYS2.GENERATE_SQL procedure. This tool is always enabled and extremely useful for providing AI models with detailed object structure information.
Features:
Supported Object Types: ALIAS, CONSTRAINT, FUNCTION, INDEX, MASK, PERMISSION, PROCEDURE, SCHEMA, SEQUENCE, TABLE, TRIGGER, TYPE, VARIABLE, VIEW, XSR
Use Cases:
Example Usage:
{
"object_name": "CUSTOMER",
"object_library": "SALES",
"object_type": "TABLE"
}
Returns:
CREATE TABLE SALES.CUSTOMER (
CUSTID INTEGER NOT NULL,
CUSTNAME VARCHAR(100),
EMAIL VARCHAR(255),
CREATED_DATE TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (CUSTID)
);
Note: This tool has no configuration - it's always available as a safe, read-only operation.
The execute_sql tool allows MCP clients to run ad-hoc SQL queries against your IBM i Db2 database. This tool is disabled by default for security reasons.
Enable via CLI flag --execute-sql or environment variables:
| Variable | Description | Type | Default | Required |
|---|---|---|---|---|
IBMI_ENABLE_EXECUTE_SQL | Enable the built-in execute_sql tool | boolean | false | No |
IBMI_EXECUTE_SQL_READONLY | Control readonly mode (only SELECT queries) | boolean | true | No |
Security Features: The execute_sql tool includes multiple layers of protection:
IBMI_EXECUTE_SQL_READONLY=true (default), only SELECT/QUERY statements are allowedQSYS2.PARSE_STATEMENT) to validate query syntax and statement typesIBMI_EXECUTE_SQL_READONLY=false to explicitly enable INSERT, UPDATE, DELETE, and other write operationsWhen to Enable:
IBMI_EXECUTE_SQL_READONLY=true for rapid prototyping and debugging with SELECT queriesIBMI_EXECUTE_SQL_READONLY=false only when you explicitly need INSERT/UPDATE/DELETE operationsIBMI_EXECUTE_SQL_READONLY=false) in production without strict authentication and authorizationExamples:
# Via CLI flags (recommended for development)
npx -y @ibm/ibmi-mcp-server@latest --execute-sql --transport http
npx -y @ibm/ibmi-mcp-server@latest --builtin-tools --execute-sql --transport http
# Via environment variables
IBMI_ENABLE_EXECUTE_SQL=true
IBMI_EXECUTE_SQL_READONLY=true # Default - only SELECT queries allowed
DB2i_HOST=ibmi-dev.local
DB2i_USER=DEVUSER
DB2i_PASS=devpass
# Enable write operations (INSERT/UPDATE/DELETE)
IBMI_ENABLE_EXECUTE_SQL=true
IBMI_EXECUTE_SQL_READONLY=false # Allow write operations
# Production: Use YAML tools instead (more controlled)
npx -y @ibm/ibmi-mcp-server@latest --tools /opt/mcp-tools/production.yaml
⚠️ Security Recommendation: Keep
IBMI_EXECUTE_SQL_READONLY=true(default) unless you explicitly need write operations. For production use cases requiring write access, consider using YAML-defined tools with parameterized queries instead of ad-hoc SQL.
| Feature | Built-in Tools | YAML SQL Tools |
|---|---|---|
| Definition | Compiled into server (TypeScript) | Defined in YAML files |
| Queries | Ad-hoc (client provides SQL) or fixed logic | Pre-defined (curated by admin) |
| Control | Feature flag + readonly mode | Full query + parameter control |
| Security | PARSE_STATEMENT + AST/Regex validation | Explicit whitelist of queries |
| Use Case | Development & exploration | Production & controlled access |
| Configuration | Environment variables | TOOLS_YAML_PATH |
| Examples | list_schemas, get_table_columns, execute_sql, describe_sql_object | Custom performance monitoring, security checks |
Recommendation:
--builtin-tools for schema discovery — safe, read-only catalog queries that help AI understand your database--execute-sql in development for quick ad-hoc query exploration--builtin-tools + YAML tools to let agents discover schema while executing only curated queriesYAML tools allow you to:
See Tools Documentation for creating YAML SQL tools.
Configuration for distributed tracing and metrics using OpenTelemetry.
| Variable | Description | Default | Required |
|---|---|---|---|
OTEL_ENABLED | Enable OpenTelemetry instrumentation | false | No |
OTEL_SERVICE_NAME | Service name for telemetry data | MCP_SERVER_NAME or package name | No |
OTEL_SERVICE_VERSION | Service version for telemetry data | MCP_SERVER_VERSION or package version | No |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | OTLP endpoint for trace export | None (logs to file) | No |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | OTLP endpoint for metrics export | None (not exported) | No |
OTEL_TRACES_SAMPLER_ARG | Trace sampling ratio (0.0 to 1.0, where 1.0 = sample all) | 1.0 (100%) | No |
OTEL_LOG_LEVEL | OTel internal diagnostic log level | INFO | No |
Supported OTEL_LOG_LEVEL values: NONE, ERROR, WARN, INFO, DEBUG, VERBOSE, ALL
Examples:
# Development: local file logging only
OTEL_ENABLED=true
OTEL_SERVICE_NAME=ibmi-mcp-dev
OTEL_LOG_LEVEL=DEBUG
# Traces written to logs/traces/ directory
# Production: export to Jaeger
OTEL_ENABLED=true
OTEL_SERVICE_NAME=ibmi-mcp-prod
OTEL_SERVICE_VERSION=1.9.1
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://jaeger:4318/v1/traces
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://jaeger:4318/v1/metrics
OTEL_TRACES_SAMPLER_ARG=0.1 # Sample 10% of traces
OTEL_LOG_LEVEL=WARN
# Production: export to cloud provider
OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp.example.com/v1/traces
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://otlp.example.com/v1/metrics
OTEL_TRACES_SAMPLER_ARG=1.0 # Sample all traces
Instrumentation Coverage:
Configuration for OAuth proxy endpoints (advanced use cases).
| Variable | Description | Default | Required |
|---|---|---|---|
OAUTH_PROXY_AUTHORIZATION_URL | OAuth authorization endpoint URL | None | No |
OAUTH_PROXY_TOKEN_URL | OAuth token endpoint URL | None | No |
OAUTH_PROXY_REVOCATION_URL | OAuth token revocation endpoint URL | None | No |
OAUTH_PROXY_ISSUER_URL | OAuth issuer URL for proxy | None | No |
OAUTH_PROXY_SERVICE_DOCUMENTATION_URL | Service documentation URL | None | No |
OAUTH_PROXY_DEFAULT_CLIENT_REDIRECT_URIS | Comma-separated default redirect URIs | None | No |
Example:
OAUTH_PROXY_AUTHORIZATION_URL=https://auth.example.com/oauth/authorize
OAUTH_PROXY_TOKEN_URL=https://auth.example.com/oauth/token
OAUTH_PROXY_REVOCATION_URL=https://auth.example.com/oauth/revoke
OAUTH_PROXY_ISSUER_URL=https://auth.example.com
OAUTH_PROXY_SERVICE_DOCUMENTATION_URL=https://docs.example.com/oauth
OAUTH_PROXY_DEFAULT_CLIENT_REDIRECT_URIS=http://localhost:3000/callback,https://app.example.com/callback
Note: OAuth proxy features are for advanced integration scenarios. Most users should use standard OAuth authentication via
MCP_AUTH_MODE=oauth.
Development:
# Recommended development .env
MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010
MCP_SESSION_MODE=auto
MCP_LOG_LEVEL=debug
MCP_AUTH_MODE=none # Or ibmi with allow HTTP
NODE_ENV=development
DB2i_HOST=ibmi-dev.local
DB2i_USER=DEVUSER
DB2i_PASS=devpass
DB2i_IGNORE_UNAUTHORIZED=true
TOOLS_YAML_PATH=tools/
YAML_AUTO_RELOAD=true
OTEL_ENABLED=true
Production:
# Recommended production .env
MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010
MCP_SESSION_MODE=auto
MCP_LOG_LEVEL=warn
MCP_AUTH_MODE=ibmi # Or jwt/oauth
NODE_ENV=production
DB2i_HOST=ibmi-prod.example.com
DB2i_USER=PRODUSER
DB2i_PASS=${SECURE_PASSWORD_FROM_VAULT}
DB2i_IGNORE_UNAUTHORIZED=false # Require valid SSL
TOOLS_YAML_PATH=/opt/mcp-tools/production.yaml
YAML_AUTO_RELOAD=false
YAML_VALIDATE_MERGED=true
IBMI_HTTP_AUTH_ENABLED=true
IBMI_AUTH_ALLOW_HTTP=false # HTTPS only
IBMI_AUTH_PRIVATE_KEY_PATH=/opt/secrets/private.pem
IBMI_AUTH_PUBLIC_KEY_PATH=/opt/secrets/public.pem
OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp.example.com/v1/traces
Security Checklist:
.env files to version controlIBMI_AUTH_ALLOW_HTTP=false)MCP_AUTH_MODE != none)MCP_ALLOWED_ORIGINS to known domainsIBMI_AUTH_MAX_CONCURRENT_SESSIONS limitsThe server supports IBM i HTTP authentication that allows clients to obtain access tokens for authenticated SQL tool execution. This enables per-user connection pooling and secure access to IBM i resources.
To enable IBM i HTTP authentication, we need to set up Encryption keys and configure the server environment. To protect IBM i credentials during transmission, the authentication flow uses RSA and AES encryption. You need to generate an RSA keypair for the server:
mkdir -p secrets
openssl genpkey -algorithm RSA -out secrets/private.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in secrets/private.pem -out secrets/public.pem
Create or update your .env file with the following settings:
# Enable IBM i authentication system
IBMI_HTTP_AUTH_ENABLED=true
MCP_AUTH_MODE=ibmi
# IBM i authentication settings
IBMI_AUTH_KEY_ID=development
IBMI_AUTH_PRIVATE_KEY_PATH=secrets/private.pem
IBMI_AUTH_PUBLIC_KEY_PATH=secrets/public.pem
# Security settings
IBMI_AUTH_ALLOW_HTTP=true # Development only - use HTTPS in production
IBMI_AUTH_TOKEN_EXPIRY_SECONDS=3600 # Token lifetime (1 hour)
# Resource management
IBMI_AUTH_MAX_CONCURRENT_SESSIONS=100
IBMI_AUTH_CLEANUP_INTERVAL_SECONDS=300
# IBM i connection details
DB2i_HOST=your-ibmi-host
DB2i_USER=your-username
DB2i_PASS=your-password
Use the included get-access-token.js script to obtain authentication tokens:
# Using credentials from .env file
node get-access-token.js --verbose
# Using CLI arguments (overrides .env)
node get-access-token.js --user myuser --password mypass --host my-ibmi-host
# Quiet mode for shell evaluation
eval $(node get-access-token.js --quiet)
echo $IBMI_MCP_ACCESS_TOKEN
The script automatically:
.env with CLI fallbackIBMI_MCP_ACCESS_TOKEN environment variablesequenceDiagram
participant CLI as Client CLI
participant Auth as MCP Server (/api/v1/auth)
participant IBM as IBM i
CLI->>Auth: GET /api/v1/auth/public-key
Auth-->>CLI: { keyId, publicKey }
CLI->>CLI: Generate AES-256-GCM session key + IV
CLI->>CLI: Encrypt credentials + request body with session key
CLI->>CLI: Encrypt session key with server public key (RSA-OAEP)
CLI->>Auth: POST /api/v1/auth { keyId, encryptedSessionKey, iv, authTag, ciphertext }
Auth->>Auth: Look up keyId, decrypt session key with private key
Auth->>Auth: Decrypt ciphertext, validate GCM tag, validate payload
Auth->>IBM: Authenticate against IBM i with decrypted credentials
IBM-->>Auth: Success/Failure
Auth->>Auth: Generate access token, provision pool session
Auth-->>CLI: 201 JSON { access_token, expires_in, ... }
Once you have a token, use it in your MCP client to authenticate requests:
import asyncio
import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async def main():
# Get the access token from environment
token = os.environ.get('IBMI_MCP_ACCESS_TOKEN')
if not token:
raise ValueError("IBMI_MCP_ACCESS_TOKEN environment variable not set")
# Set up authentication headers
headers = {"Authorization": f"Bearer {token}"}
# Connect to the IBM i MCP server with authentication
async with streamablehttp_client(
"http://localhost:3010/mcp",
headers=headers
) as (read_stream, write_stream, _):
# Create a session using the authenticated streams
async with ClientSession(read_stream, write_stream) as session:
# Initialize the connection
await session.initialize()
# List available tools (now authenticated with your IBM i credentials)
tools = await session.list_tools()
print(f"Available tools: {[tool.name for tool in tools.tools]}")
# Execute a tool with authenticated IBM i access
result = await session.call_tool("system_status", {})
print(f"System status result: {result}")
if __name__ == "__main__":
asyncio.run(main())
Development Environment:
IBMI_AUTH_ALLOW_HTTP=true allows HTTP for testingProduction Environment:
IBMI_AUTH_ALLOW_HTTP=false enforces HTTPSIBMI_AUTH_MAX_CONCURRENT_SESSIONS for resource usageWhen enabled (IBMI_HTTP_AUTH_ENABLED=true), the server provides these endpoints:
| Endpoint | Method | Description |
|---|---|---|
/api/v1/auth | POST | Authenticate with IBM i credentials and receive Bearer token |
For development and contributions, you can build and run the server from source.
1. Clone and Install:
git clone https://github.com/IBM/ibmi-mcp-server.git
cd ibmi-mcp-server
npm install
2. Build the Project:
# Build TypeScript to JavaScript
npm run build
# Or clean rebuild
npm run rebuild
3. Configure Environment:
# Copy example configuration
cp .env.example .env
# Edit with your IBM i connection details
code .env
4. Run Development Server:
# Start in HTTP mode
npm run start:http
# Start in stdio mode
npm run start:stdio
5. Run Tests:
# Run all tests
npm test
# Run in watch mode
npm run test:watch
# Generate coverage report
npm run test:coverage
# Basic HTTP server
npm run start:http
# HTTP with custom tools path
npm run start:http -- --tools ./my-configs
# HTTP with specific toolsets
npm run start:http -- --toolsets performance,monitoring
# Basic stdio transport
npm run start:stdio
# Stdio with custom tools path
npm run start:stdio -- --tools ./my-custom-tools
Make sure that to use the absolute path for tools
The MCP_SESSION_MODE environment variable controls how the HTTP server handles client sessions:
auto (default): Automatically detects client capabilities and uses the best session modestateful: Maintains persistent sessions with connection statestateless: Each request is independent, no session state maintained# Set session mode via environment variable
MCP_SESSION_MODE=stateful npm run start:http
# Or set in .env file
echo "MCP_SESSION_MODE=stateful" >> .env
npm run start:http
Both transport modes support these command-line options:
Note: CLI arguments override corresponding settings in
.envfile when provided.
| Option | Short | Description | Example |
|---|---|---|---|
--tools <path> | Override YAML tools configuration path (overrides TOOLS_YAML_PATH) | --tools ./custom-configs | |
--toolsets <list> | -ts | Load only specific toolsets (comma-separated) (overrides SELECTED_TOOLSETS) | --toolsets performance,security |
--transport <type> | -t | Force transport type (http or stdio) (overrides MCP_TRANSPORT_TYPE) | --transport http |
--help | -h | Show help information | --help |
--list-toolsets | List available toolsets from YAML configuration | --list-toolsets |
1. Standard Development Server
npm run start:http
# Server: http://localhost:3010/mcp
# Tools: tools/ (from .env)
# Session: auto-detected
2. Custom Tools Path
npm run start:http -- --tools ./my-tools
# Server: http://localhost:3010/mcp (port from .env or default)
# Tools: ./my-tools
3. Specific Toolsets Only
npm run start:http -- --toolsets performance,monitoring
# Only loads tools from 'performance' and 'monitoring' toolsets
YAML_AUTO_RELOAD=true in .env for automatic tool configuration updatesMCP_LOG_LEVEL=debug for detailed operation logsMCP_ALLOWED_ORIGINS for web-based clientsMCP_AUTH_MODE=ibmi with IBM i HTTP auth for token-based accessPort Already in Use
# Configure port in .env file
echo "MCP_HTTP_PORT=3011" >> .env
npm run start:http
Tools Not Loading
# Check tools path
npm run start:http -- --tools ./tools
# List available toolsets first
npm run start:http -- --list-toolsets --tools ./tools
# Get help
npm run start:http -- --help
The MCP Inspector is a tool for exploring and debugging the MCP server's capabilities. It provides a user-friendly interface for interacting with the server, viewing available tools, and testing queries.
Here are the steps to run the MCP Inspector:
Make sure to build the server
cd ibmi-mcp-server/
npm run build
Create an mcp.json file:
cp template_mcp.json mcp.json
Fill out the connection details in mcp.json with your IBM i system information. You should use the same credentials as in your .env file:
{
"mcpServers": {
"default-server": {
"command": "node",
"args": ["dist/index.js", "--transport", "stdio", "--tools", "tools"],
"env": {
"NODE_OPTIONS": "--no-deprecation",
"DB2i_HOST": "<DB2i_HOST>",
"DB2i_USER": "<DB2i_USER>",
"DB2i_PASS": "<DB2i_PASS>",
"DB2i_PORT": "<DB2i_PORT>"
}
}
}
}
Start the MCP Inspector
npm run mcp-inspector
Click on the URL displayed in the terminal to open the MCP Inspector in your web browser.
Starting MCP inspector...
⚙️ Proxy server listening on 127.0.0.1:6277
🔑 Session token: EXAMPLE_TOKEN
Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth
🔗 Open inspector with token pre-filled:
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=EXAMPLE_TOKEN
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀
For production deployments with Docker, Podman, or OpenShift, see the Deployment Guide.
This server was built using the MCP TypeScript Template, a production-ready foundation for building Model Context Protocol servers.
The template provided essential infrastructure that accelerated development:
BaseErrorCode and centralized ErrorHandlerThe MCP TypeScript Template provided a solid architectural foundation that allowed us to focus on IBM i-specific functionality rather than building MCP infrastructure from scratch. Key benefits:
While the template provided the foundation, we added IBM i-specific capabilities:
If you're building your own MCP server, check out the template:
# Use the template to create your own MCP server
npx degit cyanheads/mcp-ts-template my-mcp-server
cd my-mcp-server
npm install
npm run build
FAQs
A production-grade MCP server for IBM i
We found that @ibm/ibmi-mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 21 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A malicious NuGet package impersonating Sicoob exfiltrated client IDs, PFX passwords, and banking certificates through Sentry telemetry.
Security News
Feross Aboukhadijeh joins TBPN to discuss Socket's $60M Series C, 500%+ ARR growth, AI's impact on open source, and the rise in supply chain attacks.
Security News
OSV withdrew 157 OSV malware reports after automated false positives incorrectly flagged trusted npm and PyPI packages, sending bad records into tools that rely on OSV data.