Standalone MCP Host (@bdkinc/ibmi-mcp)

This package contains the standalone Model Context Protocol (MCP) host used for external harnesses, AI agents, and IDE validation.

Prerequisites

To connect using the MCP host, ensure the following requirements are met on both the client PC and the IBM i host:

1. IBM i Access ODBC Driver The local machine running the MCP server must have the ODBC driver installed.

   • ODBC Installation Instructions

2. SSH Service The SSH server must be running on the IBM i host.

   • Start the service using: STRTCPSVR *SSHD

3. SSH-Compatible Credentials Connections require credentials with an enabled shell. Profiles without passwords or user profiles like QSECOFR that are typically restricted from SSH access shouldn't be used directly unless appropriately configured. The user must also conform to PASE password constraints.

   • Configuring IBM i SSH, SFTP, and SCP clients to use public key authentication%20LEVEL(*SYS))

4. Required Packages The IBM i host must have itoolkit-utils installed for running tools securely via SSH. (e.g., yum install itoolkit-utils)

Dedicated Service Profile (Recommended)

For production or shared-team use, connect with a dedicated IBM i service profile rather than a personal user account. A service profile isolates audit trails, limits authority to only what the MCP host needs, and prevents accidental use of personal credentials.

Suggested profile setup:

CRTUSRPRF USRPRF(MCPSVC) TEXT('IBM i AI MCP service account')
           USRCLS(*USER) PWDEXPITV(*NOMAX) STATUS(*ENABLED)
           LMTCPB(*NO) JOBD(QBATCH)

Adjust JOBD, authority (GRPPRF, SUPGRPPRF), and object permissions to match your site's security policy. The profile must have PASE shell access for SSH-based itoolkit calls.

Do not commit passwords. Set IBMI_PASSWORD_SECRET from your environment, a secrets manager, or a VS Code input prompt. Never hardcode credentials in mcp.json or .env files that are checked into version control.

Usage

You can run the server directly via npx without needing to clone the repository:

npx -y @bdkinc/ibmi-mcp --transport stdio

During prerelease testing, use the next dist-tag explicitly:

npx -y @bdkinc/ibmi-mcp@next --transport stdio

When running via npx, provide your IBM i connection configuration using environment variables:

IBMI_HOST=my-ibmi IBMI_USERNAME=myuser IBMI_PASSWORD_SECRET=mysecret IBMI_CURRENT_SCHEMA=MYLIB npx -y @bdkinc/ibmi-mcp --transport stdio

The CLI also supports a few basic flags that are useful when validating external installs:

npx -y @bdkinc/ibmi-mcp --help
npx -y @bdkinc/ibmi-mcp --version

Application Integration Examples

VS Code (e.g., Roo Code / GitHub Copilot)

For VS Code extensions that support MCP clients, you can configure the server using a mcp.json settings file:

{
  "mcpServers": {
    "ibmi-ai": {
      "command": "npx",
      "args": ["-y", "@bdkinc/ibmi-mcp@next", "--transport", "stdio"],
      "env": {
        "IBMI_PROFILE_LABEL": "Local IBM i",
        "IBMI_HOST": "your-ibmi-host",
        "IBMI_USERNAME": "your-user",
        "IBMI_PASSWORD_SECRET": "${input:ibmi-password}",
        "IBMI_CURRENT_SCHEMA": "MYLIB",
        "MCP_ALLOWED_COMMAND_NAMES": "CRTUSRPRF,CHGUSRPRF,ENDJOB,HLDJOB,RLSJOB,DLTSPLF,HLDSPLF,CHGSPLF,STRTCPSVR,ENDTCPSVR"
      }
    }
  },
  "inputs": [
    {
      "id": "ibmi-password",
      "type": "promptString",
      "description": "IBM i password",
      "password": true
    }
  ]
}

Clients that support secret variables can also set IBMI_PASSWORD_SECRET to a client-managed secret reference instead of a prompt input.

When moving from prerelease testing to the normal published package, remove @next from the package name in the args array.

Claude Desktop

To use the IBM i tools from the Claude Desktop app, edit your Claude config file (%APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Note: Claude Desktop does not support ${input:...} variable syntax. Set IBMI_PASSWORD_SECRET using a system environment variable, a secrets manager, or a wrapper script — do not hardcode it in this file.

{
  "mcpServers": {
    "ibmi-ai": {
      "command": "npx",
      "args": ["-y", "@bdkinc/ibmi-mcp@next", "--transport", "stdio"],
      "env": {
        "IBMI_HOST": "your-ibmi-host",
        "IBMI_USERNAME": "your-user",
        "IBMI_CURRENT_SCHEMA": "MYLIB",
        "MCP_ALLOWED_COMMAND_NAMES": "CRTUSRPRF,CHGUSRPRF,ENDJOB,HLDJOB,RLSJOB,DLTSPLF,HLDSPLF,CHGSPLF,STRTCPSVR,ENDTCPSVR"
      }
    }
  }
}

Set IBMI_PASSWORD_SECRET as a system environment variable before launching Claude Desktop, or use a secrets manager to inject it into the process environment.

CL Command Execution

Command execution is disabled by default. When enabled, you can restrict which CL commands are allowed:

• Default deny — MCP_COMMAND_EXECUTION_ENABLED defaults to false. No commands execute unless you opt in.
• Allow-list — Set MCP_ALLOWED_COMMAND_NAMES to a comma-separated list of command names (e.g., CRTUSRPRF,ENDJOB). Only those commands are permitted.
• Freeform mode — Setting MCP_FREEFORM_COMMAND_EXECUTION_ENABLED=true bypasses the allow-list and permits any CL command. Do not use in production. The server logs a startup warning when freeform is enabled.

Audit Log

Every tool invocation is recorded to a JSONL audit log at <cwd>/logs/audit.jsonl (configurable via MCP_AUDIT_LOG_DIR). Each line is a JSON object:

{
  "ts": "2025-01-15T10:23:45.123Z",
  "tool": "list_ibmi_jobs",
  "callerId": "MCPSVC",
  "sessionId": "abc123",
  "args": {},
  "durationMs": 142,
  "ok": true
}

Fields with names matching password, secret, or token (case-insensitive) are replaced with "<redacted>" before writing. The log file rotates at 50 MB to audit-<timestamp>.jsonl.

The logs/ directory is gitignored. The log directory is created automatically if it does not exist.

Health Endpoints

The HTTP transport exposes two health endpoints:

• GET /health — Deep check; connects to IBM i and verifies prerequisites. Use for startup readiness.
• GET /healthz — Shallow in-process check; returns session count, capacity, and uptime without touching IBM i. Use for liveness probes.

Local Development & Environment Configuration

If you are developing locally inside the source repository, you can set the environment variables via .env files in this directory (e.g. .env, .env.example, .env.local.example).

Typical variables include:

• MCP_TRANSPORT
• MCP_PROFILE
• MCP_HTTP_*
• IBMI_HOST, IBMI_PORT, IBMI_DATABASE, IBMI_CURRENT_SCHEMA, IBMI_USERNAME, IBMI_PASSWORD_SECRET, IBMI_LIBRARY_LIST, IBMI_TLS
• standalone runtime MCP_* tuning for sessions and command execution

Legacy MCP_* IBM i connection names still work for one release cycle, but they are deprecated and lose to the equivalent IBMI_* variables when both are set.

Common scripts for local monorepo development:

• npm run dev --workspace @bdkinc/ibmi-mcp
• npm run build --workspace @bdkinc/ibmi-mcp
• npm run start --workspace @bdkinc/ibmi-mcp
• npm run test:live-smoke --workspace @bdkinc/ibmi-mcp

Live smoke test requirements:

• Export the same IBM i connection variables used by the standalone host, for example IBMI_HOST, IBMI_USERNAME, and IBMI_PASSWORD_SECRET.
• If you want the smoke test to exercise approval-backed command execution, also provide MCP_COMMAND_EXECUTION_ENABLED=true and MCP_FREEFORM_COMMAND_EXECUTION_ENABLED=true.
• The script sets RUN_IBM_I_LIVE_SMOKE=1 automatically and runs tests/live-smoke.test.ts in a subprocess so it can load the standalone itoolkit runtime correctly under Node.

Behavior Notes

• This standalone host exposes observe, recommend, and act tools.
• Command-backed tools execute as the configured IBM i profile.
• The standalone itoolkit path is fixed by the host implementation; there is no standalone MCP_ITOOLKIT_TRANSPORT override.
• plan_run_ibmi_command, approve_ibmi_command_request, and run_ibmi_command use local in-memory approval state for the standalone process.
• Restarting the standalone process clears those local approval records.
• MCP_ALLOWED_COMMAND_NAMES is optional. If provided, it strictly gates which CL commands can be executed via run_ibmi_command. If you wish to allow everything without a whitelist, set MCP_FREEFORM_COMMAND_EXECUTION_ENABLED=true.