How authentication works
Authentication happens at three points:
The IBM i checks the password. The MCP server makes the sign-on attempt to the IBM i on the person’s behalf. If the IBM i refuses it, so does the server.
The assistant holds tokens, not the password. A short-lived access token goes with every request, and a refresh token gets new ones without asking the person again. Both are only usable against this server.
Every statement runs as the person. Each signed-in person has their own IBM i connection under their own profile. Object authority, job logs and auditing work exactly as they do for any other sign-on.
Passwords
The MCP server keeps a person’s password only while they’re signed in, encrypted, in memory, so it can reconnect to the IBM i after an idle period without asking them again. It’s never written to disk, and it’s erased when the sign-in ends or the server restarts.Sessions
Restarting the server signs everyone out.
Who can sign in
- Any profile not starting with
Q, unless you list the allowed profiles inOAUTH_ALLOWED_PROFILES. - Not profiles with
*ALLOBJor*SECADM, unless you allow them withOAUTH_ALLOW_PRIVILEGED_PROFILES. - Only from the networks you allow in
OAUTH_SIGNON_ALLOWED_CIDRS(private networks by default). - Not after two wrong passwords in a row. The server stops trying that profile before the IBM i’s own
QMAXSIGNlimit is reached, until you unblock it.
What the IBM i sees
Each person’s work runs in a database server job under their own profile. The job’s client application name isibmi-mcp/<grantId>, and the same id appears in the MCP server’s log, so you can match an IBM i job to a sign-in.
Hardening checklist
The MCP server and Mapepire both handle passwords during sign-on, so protect them as you would any system that signs people on:- Serve the sign-in page over HTTPS only. The server refuses to start otherwise, unless it listens on
127.0.0.1. - Verify Mapepire’s certificate with
DB2i_SERVER_CERT_FILEorDB2i_CA_FILE. UseDB2i_IGNORE_UNAUTHORIZED=trueon test systems only. - Run Mapepire under its own profile, keep its keystore private, and limit who can dump its job.
- Run the MCP server under its own OS user, with core dumps turned off, as a single instance.
- Behind a proxy, list it in
MCP_TRUSTED_PROXIESand have it setX-Forwarded-For.
Signing someone out
From the server’s folder, withOAUTH_ADMIN_SOCKET set: