> ## Documentation Index
> Fetch the complete documentation index at: https://ibm-d95bab6e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up IBM i Sign-On

> People sign in with their IBM i user profile, and every tool runs SQL as them.

Let's set up the MCP server so that people sign in with their own IBM i profile and every tool runs its SQL as them. We'll do it in two parts:

1. Run it on your own machine and sign in yourself.
2. Open it to your team.

In this example the IBM i is `ibmi.example.com` and you sign in as `ANA`. Replace both with your own.

## What you need

* A machine to run the server: Linux, macOS or Windows with Node.js 22.17 or later. Start with your own computer.
* [Mapepire](https://ibm-d95bab6e.mintlify.site/setup-mapepire.md) running on the IBM i, reachable from that machine on port `8076`.
* An IBM i user profile that doesn't start with `Q` and doesn't have `*ALLOBJ` or `*SECADM` special authority. Those are refused by default. The profile must be able to read its own row in `QSYS2.USER_INFO_BASIC`, which is how the server checks.
* An AI assistant that can sign in to MCP servers, such as Claude Code, VS Code or Cursor.

## Part 1: Run it on your machine

The server listens only on `127.0.0.1` by default, so you don't need HTTPS yet.

### Save Mapepire's certificate

The server checks Mapepire's certificate before it sends anyone's password. Save it to a file:

```bash theme={null}
openssl s_client -connect ibmi.example.com:8076 </dev/null 2>/dev/null \
  | openssl x509 > mapepire.crt
```

You now have `mapepire.crt` in the current folder.

> [!TIP]
>
> On a test system whose certificate has expired, skip this step. In the next step, replace the `DB2i_SERVER_CERT_FILE` line with `DB2i_IGNORE_UNAUTHORIZED=true`.

### Configure the server

Create `.env` in the same folder:

```bash .env theme={null}
MCP_TRANSPORT_TYPE=http
MCP_AUTH_MODE=oauth
MCP_RESOURCE_URL=http://127.0.0.1:3010/mcp
DB2i_HOST=ibmi.example.com
DB2i_SERVER_CERT_FILE=/full/path/to/mapepire.crt
```

There is no `DB2i_USER` or `DB2i_PASS`: people bring their own profile. The server refuses to start if `DB2i_PASS` or `DB2i_SSH_KEY` is set.

### Start the server

From the same folder:

```bash theme={null}
npx -y @ibm/ibmi-mcp-server@latest
```

The log shows `Built-in OAuth authorization server enabled.` The server is now running at `http://127.0.0.1:3010/mcp`.

### Connect your assistant

In Claude Code:

```bash theme={null}
claude mcp add -t http ibmi http://127.0.0.1:3010/mcp
```

Run `/mcp`, choose `ibmi` and authenticate. Your browser opens the server's sign-in page. Sign in as `ANA` with your IBM i password. For other assistants, see [MCP Clients](https://ibm-d95bab6e.mintlify.site/clients/overview.md).

### Check it works

Ask the assistant: "List the schemas on the IBM i." It answers with the schemas `ANA` can see.

The health endpoint confirms the sign-in:

```bash theme={null}
curl -s http://127.0.0.1:3010/healthz
```

The answer includes `"signOn":{"grants":1,"openConnections":1,…}`: one person signed in, with one IBM i connection.

## Part 2: Open it to your team

Move the server to a machine your colleagues can reach. In this example, that's `mcp.example.com`. Then make these changes to `.env`.

### Serve over HTTPS

People type their IBM i password into the sign-in page, so the server only accepts it over HTTPS. Give the server a certificate for `mcp.example.com`, issued by your company's CA or by Let's Encrypt:

```bash .env theme={null}
MCP_HTTP_HOST=0.0.0.0
MCP_TLS_CERT_FILE=/etc/ibmi-mcp/server.crt
MCP_TLS_KEY_FILE=/etc/ibmi-mcp/server.key
```

The server now listens with HTTPS on port `3010` on every network interface. Open that port in the machine's firewall.

To put a reverse proxy (nginx, Caddy, …) in front instead, see [Behind a reverse proxy](https://ibm-d95bab6e.mintlify.site/server-config/oauth-reference.md#behind-a-reverse-proxy).

### Set the public URL

This is the URL your colleagues add to their assistant:

```bash .env theme={null}
MCP_RESOURCE_URL=https://mcp.example.com:3010/mcp
MCP_ALLOWED_HOSTS=mcp.example.com
```

`MCP_ALLOWED_HOSTS` takes the host name alone, without the port.

### Pin a certificate exported on the IBM i

The certificate you saved in Part 1 came over the network, so someone in between could have swapped it. On the IBM i, in a PASE shell, export the real one from Mapepire's keystore:

```bash theme={null}
keytool -exportcert -rfc -alias mapepire \
  -keystore /QOpenSys/etc/mapepire/cert/server.jks -file mapepire.crt
```

`keytool` asks for the keystore password (`mapepire`, unless it was changed). Copy `mapepire.crt` to the server and point `DB2i_SERVER_CERT_FILE` at it. If you used `DB2i_IGNORE_UNAUTHORIZED=true`, remove it.

That keystore path is for a [custom Mapepire certificate](https://ibm-d95bab6e.mintlify.site/setup-mapepire.md). If Mapepire uses the self-signed certificate it generated itself, its keystore is in the `.mapepire` directory of the profile Mapepire runs under. If your company's CA issued the certificate, set `DB2i_CA_FILE` to the CA instead of pinning.

### Turn on the admin socket

The admin socket lets you unblock profiles and sign people out. Choose a path in a folder the server can write to:

```bash .env theme={null}
OAUTH_ADMIN_SOCKET=/var/run/ibmi-mcp/admin.sock
```

### Keep it running

Run the server as a service, so it starts with the machine and restarts if it stops: a systemd unit that runs `npx -y @ibm/ibmi-mcp-server@latest` in this folder, or a [Docker container](https://ibm-d95bab6e.mintlify.site/deployment/docker.md#built-in-ibm-i-sign-on). Run one instance only.

### Lock it down

Work through the [hardening checklist](https://ibm-d95bab6e.mintlify.site/server-config/oauth-security.md#hardening-checklist) before your colleagues sign in.

### Invite your colleagues

Send them `https://mcp.example.com:3010/mcp` and the [client guide](https://ibm-d95bab6e.mintlify.site/clients/overview.md) for their assistant. Each of them signs in with their own profile.

## Good to know

* **Sign-ins last up to 12 hours.** Restarting the server signs everyone out.
* **Idle connections close after 10 minutes.** The assistant reconnects on its next request without asking the person to sign in again.
* **Some passwords can't be used**, for example ones that contain `:` or `%` or start with `*`. The sign-in page names the rule, and the person changes the password at a 5250 session.
* **Two wrong passwords block the profile on this server**, not on the IBM i. The person signs on once at a 5250 session, then you unblock the profile from the server's folder:

  ```bash theme={null}
  npx -y @ibm/ibmi-mcp-server@latest --admin "unblock ANA"
  ```

  Without the admin socket, restart the server instead.
* **Your own SQL tool files** (loaded with `--tools`) also run as the signed-in person. See [YAML tools](https://ibm-d95bab6e.mintlify.site/server-config/oauth-reference.md#yaml-tools).
* **Not supported:** multi-factor sign-on, unattended agents ([use your identity provider](https://ibm-d95bab6e.mintlify.site/server-config/oauth-provider.md) for those), and more than one IBM i per server.

## Next steps

> [card] [Security](https://ibm-d95bab6e.mintlify.site/server-config/oauth-security.md)
>
> What is protected, and the hardening checklist.

> [card] [Troubleshooting](https://ibm-d95bab6e.mintlify.site/server-config/oauth-troubleshooting.md)
>
> Startup errors and sign-in problems.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.