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 (Preferred) The SSH server should be running on the IBM i host for the best experience (itoolkit-based tools and secure command execution).

   • Start the service using: STRTCPSVR *SSHD
   • If SSH is unavailable, the server falls back to plain SQL/ODBC for observability and recommendation tools. Act tools (CL command execution) require SSH.

3. SSH-Compatible Credentials (Preferred) For full functionality, use credentials with an enabled shell. Profiles without passwords or user profiles like QSECOFR that are typically restricted from SSH access should not 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 should have itoolkit-utils installed for running tools securely via SSH. (e.g., yum install itoolkit-utils)

   • This is only required when SSH connectivity is available. Pure SQL/ODBC fallback does not need 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. If you only need SQL/ODBC fallback access, shell access is not required, but many act tools will be unavailable.

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

Human-only command approvals

Command approval decisions are not exposed as extra public MCP tools (the facade stays at 31 tools). Operators approve or reject pending requests with human-only CLI subcommands that do not start the host:

# List pending requests (shared durable store with the running host)
ibmi-mcp approvals list --status pending

# Approve with an explicit human identity and ticket/reference
ibmi-mcp approvals approve <request-id> --approver alice --ticket CHG-1001

# Reject
ibmi-mcp approvals reject <request-id> --approver alice --comment "Not authorized"

Store location precedence:

1. --store PATH on the approvals CLI
2. MCP_APPROVAL_STORE_PATH environment variable
3. approvalStorePath in the MCP JSON config file (--config)
4. User-data default (for example %APPDATA%\ibmi-mcp\approvals.json on Windows, ~/Library/Application Support/ibmi-mcp/approvals.json on macOS, or $XDG_DATA_HOME/ibmi-mcp/approvals.json on Linux)

Requestors cannot approve or reject their own requests. The store is a durable JSON file with atomic writes; it is never under .tmp.

Recovering a stuck approval-store lock

The approval store is guarded by a cross-process exclusive lock implemented as a directory created atomically beside the store file (<store>.lock). While a host or CLI process holds it, other processes wait and back off. Under normal operation the lock is created and released automatically and requires no attention.

A lock can be left behind only if a process is killed at the wrong instant, or if the store lives on a network/shared filesystem where the lock cannot be safely auto-reclaimed. In those cases acquisition fails closed (it times out with a clear Timed out ... waiting for approval store lock error) rather than risk two writers double-executing a command. This is deliberate. Recover manually and carefully:

1. Identify the lock artifacts. Next to your approval store JSON (see the store location precedence above), look for:
   • <store>.lock — the active lock directory. It contains an owner.json recording the owner token, pid, hostname, and acquiredAt.
   • <store>.reclaim — a short-lived guard directory used while a stale owner is being inspected. A leftover one indicates a reclaim that did not finish.
2. Confirm there is no live local owner. Read owner.json. If its hostname matches the machine you are on, check whether the recorded pid is still running. If that process is alive, stop — the lock is in use. Only proceed when the owner process is confirmed gone (or the owner.json is missing entirely). If hostname is a different host, you cannot verify liveness locally; coordinate with that host before touching anything.
3. Wait past the stale threshold. The lock is only considered stale after the owner's acquiredAt is older than the stale window (default 30 seconds). Wait until you are safely past it so a briefly-paused owner is not interrupted.
4. Back up the approval JSON first. Copy the approval store file (for example approvals.json) to a safe location before removing anything, so approval history is preserved if something is inconsistent.
5. Remove only orphan lock directories. After the checks above pass, delete the <store>.lock directory (and any leftover <store>.reclaim or <store>.stale-* / <store>.release-* directories). Remove only these lock/guard directories — never the approval store JSON itself.

Never remove a live lock. If any owner process is still running, or you cannot prove the owner is gone (different host, permission errors, shared/network filesystem), do not delete the lock directory. Forcing a live lock open can allow two processes to execute the same approved command. When in doubt, leave it locked and let acquisition fail closed. For shared deployments, prefer a local-filesystem path for the approval store to avoid routine fail-closed timeouts.

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 and run_ibmi_command use a durable JSON-file approval store shared with the ibmi-mcp approvals CLI.
• Human operators list/approve/reject via CLI only; those lifecycle commands are not public MCP tools.
• Approval records survive host restarts. IDs are UUIDs (collision-free across restarts). Requestors cannot self-approve.
• Configure the store with MCP_APPROVAL_STORE_PATH or config approvalStorePath; otherwise the user-data default is used.
• 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.