Skip to main content
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 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:
You now have mapepire.crt in the current folder.
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:
.env
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:
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:
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.

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:
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:
.env
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.

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 runs npx -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 them https://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.