Skip to main content

Startup

A variable failed validation. Fix the ones printed on stderr. A missing or non-https MCP_RESOURCE_URL is reported this way too.
Usually an .env copied from a service-account setup. For IBM i sign-on: remove DB2i_USER and DB2i_PASS, remove DB2i_IGNORE_UNAUTHORIZED when a certificate file is set, and either set the TLS files or keep MCP_HTTP_HOST=127.0.0.1.
A public MCP_RESOURCE_URL is served from 127.0.0.1, so a proxy on the same machine must be in front. Set MCP_TRUSTED_PROXIES=127.0.0.1 and have the proxy set X-Forwarded-For. For local testing without a proxy, use MCP_RESOURCE_URL=http://127.0.0.1:3010/mcp.
With IBM i sign-on, tool files may only use ${DB2i_HOST} and ${DB2i_PORT}. Write the value into the file instead.
OAUTH_ISSUER_URL isn’t set, or the server can’t see it. Without it, the server uses IBM i sign-on.
The server couldn’t fetch your provider’s metadata. Check that OAUTH_ISSUER_URL is exact and reachable from the server, or set OAUTH_JWKS_URI.

Signing in (IBM i sign-on)

The server couldn’t reach Mapepire at DB2i_HOST:DB2i_PORT, or Mapepire’s certificate didn’t pass the check (expired, or not the pinned one). The log shows signon_unavailable. Nothing was sent to the IBM i.
DB2i_IGNORE_UNAUTHORIZED=true is set, often from .env.example. Remove it and set DB2i_SERVER_CERT_FILE or DB2i_CA_FILE.
The server couldn’t read the profile in QSYS2.USER_INFO_BASIC and treats that as privileged. Check that people can query that view for their own profile.
The address is outside OAUTH_SIGNON_ALLOWED_CIDRS. The signon_refused log line shows the address the server saw. If it’s your proxy’s address, add the proxy to MCP_TRUSTED_PROXIES.
A request carried forwarding headers but didn’t come from a listed proxy, or came from one without X-Forwarded-For. Add the proxy’s address and make it set X-Forwarded-For.
MCP_RESOURCE_URL doesn’t match the address in the browser, or a proxy rewrites the Origin header. Set MCP_RESOURCE_URL to the URL people see.
Too many wrong passwords. Sign on at a 5250 session once to reset the IBM i count, then run ibmi-mcp-server --admin "unblock MYUSER". That needs OAUTH_ADMIN_SOCKET; without it, restart the server.
The client exchanged its code from a different address than the browser (a remote client, or IPv4 and IPv6 mixed). Look for signon_source_mismatch in the log. OAUTH_CODE_ADDRESS_BINDING=audit allows it.
The client doesn’t reconnect after an idle close. Raise OAUTH_IDLE_CLOSE_MINUTES.
A restart signs everyone out. The client should start a new sign-in. If it keeps retrying old tokens, clear its stored sign-in for the server and connect again.

Tokens (identity provider)

Find Access token rejected. in the log; reason says why. Common causes: aud isn’t the resource URL (set OAUTH_AUDIENCE), iss differs by a trailing slash, the token isn’t a JWT, or it’s signed with HS256.
The token is valid but lacks a scope in OAUTH_REQUIRED_SCOPES. Grant the scope to the person in your provider.

Either mode

Add the public host name to MCP_ALLOWED_HOSTS.