IBM i MCP Server

When an RPG application slows down, an IBM i developer often starts with familiar views: active jobs, system status, memory pools, and the HTTP server if the application has a web front end. IBM's IBM i MCP Server can expose selected IBM i SQL services as tools that an AI client calls on demand. The client can summarize the returned rows and help you decide what to inspect next.

This walkthrough focuses on the repository's performance tool file. It gives us a concrete monitoring exercise for RPG teams and a clear view of what these tools actually return.

What the performance tools provide

An MCP tool has a name, a description, and an input schema. In this repository, most tools are defined in YAML with a fixed SQL statement. An MCP client discovers them, calls one with parameters, and receives the result. The server runs the SQL through Mapepire against Db2 for i.

Tool in performance.yaml	What it queries
system_status	QSYS2.SYSTEM_STATUS for system and storage status.
system_activity	QSYS2.SYSTEM_ACTIVITY_INFO for a one-row CPU activity sample.
active_job_info	QSYS2.ACTIVE_JOB_INFO for jobs in QUSRWRK and QSYSWRK, ordered by total CPU_TIME; default limit is 10.
memory_pools	QSYS2.MEMORY_POOL for pool sizes and thread information.
temp_storage_buckets and unnamed_temp_storage	QSYS2.SYSTMPSTG for temporary storage buckets.
http_server	QSYS2.HTTP_SERVER_INFO for IBM HTTP Server for i (Apache) request and connection metrics.
remote_connections	A count of established, non-loopback connections from QSYS2.NETSTAT_INFO.
system_values and collection_services	Selected performance-related system values and Collection Services configuration.

These are questions you ask when you need a snapshot. They do not create continuous alerts or prove the cause of a slowdown. In particular, active_job_info sorts by total CPU time used by each job, not current CPU percentage, and it does not search every subsystem. The system_activity tool returns CPU activity for the system; despite its YAML description, it does not list active jobs. IBM says that service requires *JOBCTL authority, so ask your administrator which tools your monitoring profile may use. See IBM's ACTIVE_JOB_INFO and SYSTEM_ACTIVITY_INFO documentation.

A first question for an RPG support shift

Suppose users report that an RPG-backed application is slow. Start with a question the loaded tools can answer:

Use active_job_info with a limit of 5. Show the returned jobs from QUSRWRK and QSYSWRK, including job name, status, subsystem, and total CPU time. Then tell me which job you would investigate first and why. Do not treat total CPU time as a live CPU percentage.

The client can call the tool and explain the rows it receives. Follow up with system_status for system status, memory_pools for pool sizes, or http_server if the workload is served by IBM HTTP Server. Compare the output with WRKACTJOB, WRKSYSSTS, and your normal operational checks. A high cumulative CPU time may simply reflect a long-running job; it is a lead for investigation, not a diagnosis.

Set up a focused monitoring toolset

You need Mapepire running on IBM i (its default port is 8076), Node.js 18 or newer where the MCP server runs, and an IBM i profile authorized for the services you intend to call. Use a development partition first. The server quickstart and Mapepire guide cover installation and connection details.

1. Clone the repository and copy the performance file so you can review it without changing the original:

git clone https://github.com/IBM/ibmi-mcp-server.git
cd ibmi-mcp-server
cp tools/performance/performance.yaml tools/monitoring-demo.yaml

1. Open tools/monitoring-demo.yaml. The supplied file uses ignore-unauthorized: true for its Mapepire source; set it to false when you have a trusted TLS certificate. Also inspect system_status and memory_pools: both shipped statements use RESET_STATISTICS=>'YES'. For a first observational exercise, change those two values to 'NO'. IBM documents that YES resets the elapsed-statistics baseline for later calls in that connection. A statement beginning with SELECT can still have this measurement effect. Read IBM's SYSTEM_STATUS and MEMORY_POOL descriptions before using these tools in a shared environment.

2. Create a local .env containing your development connection details, and keep it out of Git:

DB2i_HOST=ibmi.example.com
DB2i_USER=MONITORUSER
DB2i_PASS=replace-with-your-password
DB2i_PORT=8076
MCP_HTTP_PORT=3010

1. Start the server with only your reviewed monitoring file:

export MCP_SERVER_CONFIG="$PWD/.env"
npx -y @ibm/ibmi-mcp-server@latest --transport http --tools "$PWD/tools/monitoring-demo.yaml"

In another terminal, curl http://localhost:3010/healthz checks that the HTTP process is up. The MCP endpoint is http://localhost:3010/mcp. A health check does not prove that an IBM i tool call succeeds; use the MCP Inspector or an AI client to list and invoke a tool. Avoid loading the whole tools/ directory for this exercise: other tool files expose capabilities outside monitoring.

Connect the tools to an AI agent in VS Code

These steps use GitHub Copilot Chat in VS Code. The MCP server provides the IBM i tools; the AI model used by VS Code is configured separately. Open your RPG workspace and create .vscode/mcp.json. VS Code expects a top-level servers object. Choose one connection below.

Connect to the HTTP process you just started:

{
  "servers": {
    "ibmi-monitor": {
      "type": "http",
      "url": "http://localhost:3010/mcp"
    }
  }
}

This URL is for a local development setup where VS Code can reach that process. For a shared server, configure authentication and HTTPS as described in the IBM server guide.

Or let VS Code start a local stdio server: replace both paths with absolute paths on the machine where VS Code starts MCP processes. This option uses the same .env and reviewed YAML file; you do not need the separate HTTP process running.

{
  "servers": {
    "ibmi-monitor": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ibm/ibmi-mcp-server@latest",
        "--transport",
        "stdio",
        "--tools",
        "/absolute/path/to/ibmi-mcp-server/tools/monitoring-demo.yaml"
      ],
      "env": {
        "MCP_SERVER_CONFIG": "/absolute/path/to/ibmi-mcp-server/.env"
      }
    }
  }
}

Save mcp.json, run MCP: List Servers from the Command Palette, and start ibmi-monitor if needed. Open VS Code Chat and select Agent. In Configure Tools or the agent's Tools customization, check that active_job_info, system_status, and the other intended tools appear and are enabled. Type # in the chat input if you want to select a specific tool, then try the support-shift question above. Review the actual tool call and its result. If the server or tools do not appear, use MCP: List Servers → Show Output and check the paths, Node/npx availability, Mapepire connection, and IBM i authority. See VS Code's MCP guide and agent tool guide.

Other AI extensions in VS Code may keep their own MCP settings. For example, configuring Copilot's .vscode/mcp.json does not guarantee that Cline or Roo Code will use it; check each extension's client configuration. The IBM repository includes examples for several MCP clients.

How the tools become visible

The YAML contains sources (connection details), tools (SQL statements and parameters), and toolsets (groups). When the server starts, it parses the chosen file and registers its enabled definitions as MCP tools. The client discovers their names and descriptions through tools/list and sends arguments when it calls one. That is why pointing --tools at monitoring-demo.yaml matters: it determines which SQL-backed capabilities your agent can see. The tool configuration guide shows how to add a narrowly scoped tool later.

What to check before trusting an answer

An MCP tool returns data from the SQL statement it was given. The model may summarize that data, but the toolset shown here does not fetch a specific job log, trace every job across every subsystem, end a job, or alert you automatically. The remote_connections result counts established connection rows, not unique users. collection_services reports configuration, not a historical performance chart. Tool availability also depends on IBM i release, installed PTFs, and the profile's authority.

Keep the initial tool file small, use a profile with only the required authority, and compare early results with IBM i screens you already trust. If your team needs a QBATCH job view or a specific job's log, define and review another focused tool for that question. The useful outcome is a repeatable route from a support question to verifiable IBM i data—without assuming the model knows more than the tools returned.

Resources: IBM i MCP Server · Performance YAML · Server setup · VS Code MCP setup · IBM i SQL Services