- Run it on your own machine and sign in yourself.
- Open it to your team.
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 running on the IBM i, reachable from that machine on port
8076. - An IBM i user profile that doesn’t start with
Qand doesn’t have*ALLOBJor*SECADMspecial authority. Those are refused by default. The profile must be able to read its own row inQSYS2.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 on127.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:mapepire.crt in the current folder.
Configure the server
Create.env in the same folder:
.env
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: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:/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.
Check it works
Ask the assistant: “List the schemas on the IBM i.” It answers with the schemasANA can see.
The health endpoint confirms the sign-in:
"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’smcp.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 formcp.example.com, issued by your company’s CA or by Let’s Encrypt:
.env
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.
Set the public URL
This is the URL your colleagues add to their assistant:.env
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: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. 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:.env
Keep it running
Run the server as a service, so it starts with the machine and restarts if it stops: a systemd unit that runsnpx -y @ibm/ibmi-mcp-server@latest in this folder, or a Docker container. Run one instance only.
Lock it down
Work through the hardening checklist before your colleagues sign in.Invite your colleagues
Send themhttps://mcp.example.com:3010/mcp and the client guide 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:
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. - Not supported: multi-factor sign-on, unattended agents (use your identity provider for those), and more than one IBM i per server.
Next steps
Security
What is protected, and the hardening checklist.
Troubleshooting
Startup errors and sign-in problems.