Skip to main content

IBM i sign-on settings

Used when MCP_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 on 127.0.0.1 without its own certificate:
.env
The proxy must:
  • set the X-Forwarded-For header itself (overwrite or append the client address);
  • forward /mcp, /oauth/* and /.well-known/* unchanged;
  • leave the Origin request header, and the sign-in page’s Content-Security-Policy and Referrer-Policy response headers, alone;
  • not buffer responses, because MCP streams them (proxy_buffering off in nginx).
A proxy on another machine must connect to the server over HTTPS: give the server its own certificate as well, and list the proxy’s address in MCP_TRUSTED_PROXIES. See Docker and OpenShift for examples.

Identity provider settings

Used when MCP_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_URL is missing or not https (outside loopback).
  • The transport is stdio.
  • MCP_HTTP_HOST is not loopback and no TLS certificate is set, or only one of the two TLS files is set.
  • A public MCP_RESOURCE_URL is served from a loopback MCP_HTTP_HOST and MCP_TRUSTED_PROXIES has no loopback entry.
  • DB2i_HOST is missing, or DB2i_PASS or DB2i_SSH_KEY is set.
  • Certificate settings conflict: both files set, or a file plus DB2i_IGNORE_UNAUTHORIZED=true, or a file that holds no certificate.
  • DB2i_JDBC_OPTIONS has a key outside the allowed list.
  • OAUTH_JWKS_URI, OAUTH_AUDIENCE or IBMI_HTTP_AUTH_ENABLED=true is set.
  • Node.js runs with --inspect.
  • A list setting has a malformed entry.
  • OAUTH_ADMIN_SOCKET can’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 user and password are ignored.
  • A source’s host must be ${DB2i_HOST}. Its port and ignore-unauthorized aren’t used.
  • A source can’t set jdbc-options. Use DB2i_JDBC_OPTIONS.
  • Only ${DB2i_HOST} and ${DB2i_PORT} may appear in a tool file (outside user and password).
  • execute_sql stays 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’s QMAXSIGN. 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 same OAUTH_ADMIN_SOCKET applies. With npx, put npx -y @ibm/ibmi-mcp-server@latest in place of ibmi-mcp-server.
A grant is one sign-in. Its 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 to MCP_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 an event 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.