IBM i sign-on settings
Used whenMCP_AUTH_MODE=oauth and OAUTH_ISSUER_URL is not set.
OAUTH_JWKS_URI and OAUTH_AUDIENCE stop startup in this mode. OAUTH_REQUIRED_SCOPES has no effect.
Behind a reverse proxy
With a proxy that handles HTTPS on the same machine, the server keeps listening on127.0.0.1 without its own certificate:
.env
- set the
X-Forwarded-Forheader itself (overwrite or append the client address); - forward
/mcp,/oauth/*and/.well-known/*unchanged; - leave the
Originrequest header, and the sign-in page’sContent-Security-PolicyandReferrer-Policyresponse headers, alone; - not buffer responses, because MCP streams them (
proxy_buffering offin nginx).
MCP_TRUSTED_PROXIES. See Docker and OpenShift for examples.
Identity provider settings
Used whenMCP_AUTH_MODE=oauth and OAUTH_ISSUER_URL is set.
Accepted tokens: JWTs signed with
RS256/384/512, PS256/384/512, ES256/384/512 or EdDSA; iss equal to OAUTH_ISSUER_URL; aud equal to the audience (with or without a trailing slash); exp in the future, with no clock skew allowed. The caller is identified by client_id, else azp, else sub. Scopes are read from scope, else scp.
Fixed limits (IBM i sign-on)
What stops startup (IBM i sign-on)
The server exits with a message that names the setting when:MCP_RESOURCE_URLis missing or nothttps(outside loopback).- The transport is stdio.
MCP_HTTP_HOSTis not loopback and no TLS certificate is set, or only one of the two TLS files is set.- A public
MCP_RESOURCE_URLis served from a loopbackMCP_HTTP_HOSTandMCP_TRUSTED_PROXIEShas no loopback entry. DB2i_HOSTis missing, orDB2i_PASSorDB2i_SSH_KEYis set.- Certificate settings conflict: both files set, or a file plus
DB2i_IGNORE_UNAUTHORIZED=true, or a file that holds no certificate. DB2i_JDBC_OPTIONShas a key outside the allowed list.OAUTH_JWKS_URI,OAUTH_AUDIENCEorIBMI_HTTP_AUTH_ENABLED=trueis set.- Node.js runs with
--inspect. - A list setting has a malformed entry.
OAUTH_ADMIN_SOCKETcan’t be created, or another server already listens on it.- A YAML tool file breaks the rules under YAML tools.
YAML tools
With IBM i sign-on, every tool runs on the connection of the person who calls it.- A source’s
userandpasswordare ignored. - A source’s
hostmust be${DB2i_HOST}. Itsportandignore-unauthorizedaren’t used. - A source can’t set
jdbc-options. UseDB2i_JDBC_OPTIONS. - Only
${DB2i_HOST}and${DB2i_PORT}may appear in a tool file (outsideuserandpassword). execute_sqlstays read-only by default, on top of the person’s own IBM i authority.
Sign-on blocking
The server counts failed sign-ons per profile so that it can’t push a profile past the IBM i’sQMAXSIGN.
After
OAUTH_SIGNON_MAX_FAILURES wrong passwords in a row (or twice that many unreadable results), nothing more is sent for that profile until an admin unblocks it or the server restarts. The block doesn’t expire on its own. The IBM i profile itself is not disabled.
Passwords the server refuses to send: ones that contain :, %, ; or ", start with *, end with \, start or end with a space, contain non-ASCII characters, or equal the profile name. Profile names are 1–10 characters (letters, digits, #, $, _) and don’t start with a digit.
Admin commands
Run as the same OS user as the server, from its folder so the sameOAUTH_ADMIN_SOCKET applies. With npx, put npx -y @ibm/ibmi-mcp-server@latest in place of ibmi-mcp-server.
grantId is in the server’s log lines and in the IBM i job’s client application name (ibmi-mcp/<grantId>).
In a container: docker exec <container> node packages/server/dist/index.js --admin "status". revoke ends the sign-in at once and closes its IBM i job. To lock someone out for good, also disable the profile on the IBM i.
Endpoints (IBM i sign-on)
Relative toMCP_RESOURCE_URL without its last path segment:
Refresh tokens rotate on every use.
Log events (IBM i sign-on)
Each event is one log record with anevent field. No record holds a password, token or authorization code.
Most of these are logged at
info. A MCP_LOG_LEVEL of notice or higher hides them.