IBM i Authentication

IBM i HTTP authentication enables secure, token-based access to the MCP server with per-user connection pooling. Clients authenticate with IBM i credentials to obtain Bearer tokens for subsequent API requests.

When to use IBM i authentication:

Multi-user environments: Each user gets their own connection pool with their credentials
Production deployments: Token-based auth with automatic expiry and session management
Enhanced security: Credentials encrypted during transmission using RSA/AES
Audit trails: Per-user tracking of database operations

When to use simpler auth:

Development: Use shared DB2i_USER/DB2i_PASS credentials (no token auth needed)
Single-user scenarios: JWT or OAuth may be sufficient

How It Works

Authentication Flow

Key Features:

End-to-end encryption: Credentials never transmitted in plain text
Per-user pools: Each token gets its own dedicated DB2 connection pool
Token lifecycle: Automatic expiry and cleanup of stale sessions
Key rotation: Support for multiple keypairs for zero-downtime rotation

Configuration

Environment Variables

Variable	Description	Default	Required
`MCP_AUTH_MODE`	Must be set to `ibmi`	`none`	✅ Yes
`IBMI_HTTP_AUTH_ENABLED`	Enable auth endpoints	`false`	✅ Yes
`IBMI_AUTH_KEY_ID`	Identifier for RSA keypair	(none)	✅ Yes
`IBMI_AUTH_PRIVATE_KEY_PATH`	Path to RSA private key	(none)	✅ Yes
`IBMI_AUTH_PUBLIC_KEY_PATH`	Path to RSA public key	(none)	✅ Yes
`IBMI_AUTH_ALLOW_HTTP`	Allow HTTP (dev only)	`false`	No
`IBMI_AUTH_TOKEN_EXPIRY_SECONDS`	Token lifetime	`3600` (1hr)	No
`IBMI_AUTH_CLEANUP_INTERVAL_SECONDS`	Cleanup interval	`300` (5min)	No
`IBMI_AUTH_MAX_CONCURRENT_SESSIONS`	Max sessions	`100`	No

Complete Reference: See the IBM i Authentication Settings section in the Configuration Reference for all available environment variables and their defaults.

Db2i Credentials: Important Notes

Common Pitfall: When using IBM i HTTP authentication, you may encounter validation errors about DB2i_USER and DB2i_PASS even though the Bearer token provides authentication.Solution: Either omit these variables entirely from your .env file, or set them to placeholder values like TOKEN_AUTH.Why this happens: The validation schema requires these fields to be either undefined or have non-empty values. Empty strings (DB2i_USER="") fail validation. When using token authentication, the Bearer token supplies user credentials, so DB2i_USER and DB2i_PASS are not used.

Option 1: Omit Variables (Recommended)
Option 2: Placeholder Values

# .env for IBM i HTTP Authentication

# Authentication Mode
MCP_AUTH_MODE=ibmi
IBMI_HTTP_AUTH_ENABLED=true

# Encryption Keys
IBMI_AUTH_KEY_ID=production
IBMI_AUTH_PRIVATE_KEY_PATH=secrets/private.pem
IBMI_AUTH_PUBLIC_KEY_PATH=secrets/public.pem

# IBM i Connection (host only, no credentials)
DB2i_HOST=ibmi-prod.company.com
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=false

# DO NOT INCLUDE DB2i_USER or DB2i_PASS
# Token authentication provides user credentials

This is the cleanest approach: Variables are completely absent from the configuration.

# .env for IBM i HTTP Authentication

# Authentication Mode
MCP_AUTH_MODE=ibmi
IBMI_HTTP_AUTH_ENABLED=true

# Encryption Keys
IBMI_AUTH_KEY_ID=production
IBMI_AUTH_PRIVATE_KEY_PATH=secrets/private.pem
IBMI_AUTH_PUBLIC_KEY_PATH=secrets/public.pem

# IBM i Connection
DB2i_HOST=ibmi-prod.company.com
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=false

# Placeholders (not used during token auth)
DB2i_USER=TOKEN_AUTH
DB2i_PASS=TOKEN_AUTH

Why this works: Validation passes because values are non-empty, but they’re never used since token auth provides real credentials.

Reference: See GitHub Issue #77 for the original discussion of this validation behavior.

Setup: RSA Encryption Keys

IBM i authentication requires RSA keypairs to protect credentials during transmission. The authentication flow uses RSA and AES encryption to securely exchange IBM i credentials between clients and the server.

Create Secrets Directory

Create a dedicated directory for storing encryption keys:

mkdir -p secrets

Store the secrets/ directory outside of version control. Add it to your .gitignore file.

Generate RSA Private Key

Generate a 2048-bit RSA private key:

openssl genpkey -algorithm RSA \
  -out secrets/private.pem \
  -pkeyopt rsa_keygen_bits:2048

What this does:

Creates a new RSA private key with 2048-bit encryption strength
Saves it to secrets/private.pem
This key will be used by the server to decrypt credentials sent by clients

Extract Public Key

Extract the corresponding public key from the private key:

openssl rsa -pubout \
  -in secrets/private.pem \
  -out secrets/public.pem

What this does:

Derives the public key from your private key
Saves it to secrets/public.pem
Clients use this public key to encrypt credentials before sending them to the server

Set Secure File Permissions

Restrict access to your private key:

# Make private key readable only by owner
chmod 600 secrets/private.pem

# Public key can be more permissive
chmod 644 secrets/public.pem

Critical Security Step: The private key (private.pem) must be protected. Anyone with access to this file can decrypt client credentials.

Configure Environment Variables

Add the keypair paths to your .env file:

# IBM i Authentication Keys
IBMI_AUTH_KEY_ID=production
IBMI_AUTH_PRIVATE_KEY_PATH=secrets/private.pem
IBMI_AUTH_PUBLIC_KEY_PATH=secrets/public.pem

Key Configuration:

IBMI_AUTH_KEY_ID: Identifier for this keypair (used for key rotation)
IBMI_AUTH_PRIVATE_KEY_PATH: Path to your private key file
IBMI_AUTH_PUBLIC_KEY_PATH: Path to your public key file

How the Encryption Works:

Client requests public key from server (/api/v1/auth/public-key)
Client generates a random AES-256-GCM session key
Client encrypts IBM i credentials with the session key
Client encrypts the session key with the server’s RSA public key
Server decrypts the session key using its RSA private key
Server decrypts the credentials using the session key
Server authenticates against IBM i and issues an access token

Key Rotation: To rotate keys, generate a new keypair with a different IBMI_AUTH_KEY_ID. The server can support multiple keypairs simultaneously, allowing gradual migration without service interruption.

Start the Server

After configuring IBM i authentication and generating your RSA keys, start the MCP server with authentication enabled. Complete Configuration Example:

# .env file with IBM i HTTP Authentication
MCP_AUTH_MODE=ibmi
IBMI_HTTP_AUTH_ENABLED=true

# Encryption Keys
IBMI_AUTH_KEY_ID=production
IBMI_AUTH_PRIVATE_KEY_PATH=secrets/private.pem
IBMI_AUTH_PUBLIC_KEY_PATH=secrets/public.pem

# IBM i Connection (host only - no DB2i_USER/DB2i_PASS needed)
DB2i_HOST=ibmi-prod.company.com
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=false

# Server Settings
MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010
MCP_LOG_LEVEL=info

# Security (production)
IBMI_AUTH_ALLOW_HTTP=false
IBMI_AUTH_TOKEN_EXPIRY_SECONDS=3600

Start the Server:

NPM Package
Build from Source

# Set configuration file path
export MCP_SERVER_CONFIG=.env

# Start the server
npx -y @ibm/ibmi-mcp-server@latest --transport http --tools ./tools

You should see:

✓ IBM i HTTP authentication enabled
✓ Public key loaded from secrets/public.pem
✓ Private key loaded from secrets/private.pem
✓ Server ready!
  Transport: http
  Host: 127.0.0.1:3010
  Endpoint: http://127.0.0.1:3010/mcp
  Auth: IBM i HTTP (key_id: production)

# From the repository root
export MCP_SERVER_CONFIG=.env
cd server
npm run start:http -- --tools ../tools

You should see:

✓ IBM i HTTP authentication enabled
✓ Public key loaded from secrets/public.pem
✓ Private key loaded from secrets/private.pem
✓ Server ready!
  Transport: http
  Host: 127.0.0.1:3010
  Endpoint: http://127.0.0.1:3010/mcp
  Auth: IBM i HTTP (key_id: production)

Production HTTPS: In production, ensure IBMI_AUTH_ALLOW_HTTP=false and use HTTPS. The server will reject HTTP authentication requests for security.

Usage Examples

Getting an Access Token

The repository includes a helper script to obtain authentication tokens: get-access-token.js

Script Location: The get-access-token.js script is included in the root of the GitHub repository. Clone the repository or download this file to use the token helper.What it does: This script authenticates with your IBM i credentials and generates a Bearer token, then outputs a command to set the IBMI_MCP_ACCESS_TOKEN environment variable.

# Clone the repository if you haven't already
git clone https://github.com/IBM/ibmi-mcp-server.git
cd ibmi-mcp-server

# ONE-LINER: Generate token and set IBMI_MCP_ACCESS_TOKEN automatically
eval $(node get-access-token.js --quiet)

# Verify the token was set
echo $IBMI_MCP_ACCESS_TOKEN

# Alternative: View token details with verbose output
node get-access-token.js --verbose

# Alternative: Specify credentials explicitly
node get-access-token.js \
  --user myuser \
  --password mypass \
  --host my-ibmi-host \
  --quiet

Quick Setup: The one-liner eval $(node get-access-token.js --quiet) does everything:

Reads your IBM i credentials from .env
Encrypts and sends them to the MCP server
Receives the Bearer token
Automatically sets export IBMI_MCP_ACCESS_TOKEN=your-token
Token is now available in your shell session

Use this token with any MCP client by including the header: Authorization: Bearer $IBMI_MCP_ACCESS_TOKEN

Example Output:

$ eval $(node get-access-token.js --quiet)
$ echo $IBMI_MCP_ACCESS_TOKEN
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiTVlVU0VSIiwiaG9zdCI6...

# Token is now set and ready to use with MCP clients

Common Options:

Option	Short	Description	Default
`--user`	`-u`	IBM i username	`DB2i_USER` from .env
`--password`	`-p`	IBM i password	`DB2i_PASS` from .env
`--host`	`-h`	IBM i host address	`DB2i_HOST` from .env
`--server`		MCP server address	`localhost`
`--port`		MCP server port	`3010`
`--https`		Use HTTPS instead of HTTP	HTTP
`--verbose`	`-v`	Enable verbose output with metadata	(quiet mode)
`--quiet`	`-q`	Output only export command for shell eval	(normal mode)

Advanced Options

For advanced use cases, the script supports additional configuration:

Option	Description
`--duration`	Token duration in seconds
`--pool-start`	Initial connection pool size
`--pool-max`	Maximum connection pool size
`--public-key-path`	Path to PEM-encoded server public key (skips HTTP fetch)
`--key-id`	Key identifier when using `--public-key-path`

Example with advanced options:

node get-access-token.js \
  --server prod-mcp.company.com \
  --port 443 \
  --https \
  --duration 7200 \
  --quiet

The script automatically:

Loads IBM i credentials from .env with CLI fallback
Fetches the server’s public key (or uses local file with --public-key-path)
Encrypts credentials client-side using RSA/AES
Requests an access token from the MCP server
Outputs the token (or export command in quiet mode)

View Source: See the full implementation at get-access-token.js

Using the Token with MCP Clients

Once you have a token, configure your MCP client:

Python (Agno)
Python (MCP SDK)
Claude Desktop
VSCode

import asyncio
import os
from agno.agent import Agent
from agno.tools.mcp import MCPTools, StreamableHTTPClientParams

# Get access token from environment
token = os.environ.get('IBMI_MCP_ACCESS_TOKEN')
if not token:
    raise ValueError("IBMI_MCP_ACCESS_TOKEN not set")

url = "http://localhost:3010/mcp"
server_params = StreamableHTTPClientParams(
    url=url,
    headers={"Authorization": f"Bearer {token}"}
)

async def main():
    async with MCPTools(
        url=url,
        server_params=server_params,
        transport="streamable-http"
    ) as tools:
        agent = Agent(
            model="openai:gpt-4o",
            tools=[tools],
            name="ibmi-agent",
            show_tool_calls=True
        )
        await agent.aprint_response("What is the system status?")

if __name__ == "__main__":
    asyncio.run(main())

import asyncio
import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    token = os.environ.get('IBMI_MCP_ACCESS_TOKEN')
    if not token:
        raise ValueError("IBMI_MCP_ACCESS_TOKEN not set")

    headers = {"Authorization": f"Bearer {token}"}

    async with streamablehttp_client(
        "http://localhost:3010/mcp",
        headers=headers
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()

            # List tools
            tools = await session.list_tools()
            print(f"Tools: {[t.name for t in tools.tools]}")

            # Execute a tool
            result = await session.call_tool("system_status", {})
            print(result)

if __name__ == "__main__":
    asyncio.run(main())

{
  "mcpServers": {
    "ibmi-mcp": {
      "url": "http://localhost:3010/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
      }
    }
  }
}

{
  "servers": {
    "ibmiMcp": {
      "type": "http",
      "url": "http://localhost:3010/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
      }
    }
  }
}

Security Best Practices

Production Deployment

Always use HTTPS: Set IBMI_AUTH_ALLOW_HTTP=false
Rotate keys regularly: Generate new keypairs every 90-180 days
Use strong key sizes: 2048-bit minimum, 4096-bit recommended for high-security environments
Monitor key access: Enable file auditing on the secrets/ directory
Backup keys securely: Store encrypted backups in a secrets management system

File Permissions

Private key: chmod 600 secrets/private.pem (owner read/write only)
Public key: chmod 644 secrets/public.pem (world-readable is safe)
Secrets directory: chmod 700 secrets/ (owner access only)
Owner: Ensure files are owned by the service account running the MCP server

Version Control

Never commit keys: Add secrets/ to .gitignore
Never commit .env: Environment files often contain paths to secrets
Use environment-specific keys: Different keypairs for dev/staging/production
Document setup process: Include key generation in deployment documentation

Secrets Management

For production environments, consider using a secrets management system:

AWS Secrets Manager: Store keys in encrypted AWS vault
HashiCorp Vault: Centralized secrets management with audit logs
Azure Key Vault: Microsoft’s cloud-based secrets storage
Kubernetes Secrets: For containerized deployments

Update IBMI_AUTH_PRIVATE_KEY_PATH to reference the mounted secret location.

Network Security

HTTPS Only: Never allow IBMI_AUTH_ALLOW_HTTP=true in production
Firewall Rules: Restrict access to auth endpoints
Rate Limiting: Configure rate limits on authentication endpoints
IP Whitelisting: Restrict auth access to known client IPs when possible

Troubleshooting

Validation Error: DB2i_USER and DB2i_PASS Required

Symptom: Server fails to start with error requiring DB2i_USER and DB2i_PASS even though you’re using token authentication.Solution: Either completely omit these variables from your .env file, or set them to placeholder values like TOKEN_AUTH. Do not use empty strings (DB2i_USER="").See the Configuration section above for detailed examples.Why: Validation requires these fields to be either undefined or have non-empty values. When using token auth, credentials come from the Bearer token, not environment variables.

401 Unauthorized When Using Token

Possible causes:

Token has expired (check IBMI_AUTH_TOKEN_EXPIRY_SECONDS)
Token was obtained from a different server instance
Authorization header missing or malformed

Check:

# Verify header format
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3010/mcp

# Get a fresh token
node get-access-token.js --verbose

Encryption Key Errors

Symptom: Server fails to start or auth requests fail with encryption errors.Solutions:

Verify file paths in .env are correct
Check file permissions: ls -la secrets/
Ensure private key is valid: openssl rsa -in secrets/private.pem -check
Regenerate keypair if corrupted

Connection Pool Exhaustion

Symptom: “Max concurrent sessions reached” errors.Solutions:

Increase IBMI_AUTH_MAX_CONCURRENT_SESSIONS
Reduce IBMI_AUTH_TOKEN_EXPIRY_SECONDS to clean up idle sessions faster
Monitor active sessions and adjust cleanup interval

Authentication Endpoints

When enabled (IBMI_HTTP_AUTH_ENABLED=true), the server provides these endpoints:

Endpoint	Method	Description
`/api/v1/auth/public-key`	GET	Retrieve server’s RSA public key for client-side encryption
`/api/v1/auth`	POST	Authenticate with encrypted IBM i credentials and receive Bearer token
`/healthz`	GET	Health check endpoint (no authentication required)

For detailed API specifications, see the API Reference.

Next Steps

Configuration Reference

Explore all configuration options for the MCP server

Client Integrations

Connect Claude Desktop, VSCode, Cursor, and other MCP clients

SQL Tools

Create custom SQL operations for authenticated users

Production Deployment

Deploy with Docker, HTTPS, and secrets management

Getting Started

Core Concepts

Server Configuration

SQL Tools System

How It Works

Authentication Flow

Configuration

Environment Variables

Db2i Credentials: Important Notes

Setup: RSA Encryption Keys

Start the Server

Usage Examples

Getting an Access Token

Using the Token with MCP Clients

Security Best Practices

Troubleshooting

Authentication Endpoints

Next Steps

Configuration Reference

Client Integrations

SQL Tools

Production Deployment

Getting Started

Core Concepts

Server Configuration

SQL Tools System

​How It Works

​Authentication Flow

​Configuration

​Environment Variables

​Db2i Credentials: Important Notes

​Setup: RSA Encryption Keys

​Start the Server

​Usage Examples

​Getting an Access Token

​Using the Token with MCP Clients

​Security Best Practices

​Troubleshooting

​Authentication Endpoints

​Next Steps

Configuration Reference

Client Integrations

SQL Tools

Production Deployment

How It Works

Authentication Flow

Configuration

Environment Variables

Db2i Credentials: Important Notes

Setup: RSA Encryption Keys

Start the Server

Usage Examples

Getting an Access Token

Using the Token with MCP Clients

Security Best Practices

Troubleshooting

Authentication Endpoints

Next Steps