Setup Mapepire

Complete guide to installing and configuring Mapepire server on IBM i for MCP database connectivity

Before you can use the IBM i MCP Server, you must install and configure Mapepire on your IBM i system. Mapepire is the database connectivity layer that enables MCP tools and AI agents to communicate with Db2 for i.

Mapepire is Required: The IBM i MCP Server cannot function without Mapepire. Install and configure Mapepire first before proceeding with server setup.

Prerequisites: You need SSH access to your IBM i system and appropriate administrative privileges to install software and configure network services.

What is Mapepire?

Mapepire is a modern, high-performance database server for IBM i that provides SQL query execution capabilities over WebSocket connections. It acts as a gateway between modern application architectures (like MCP servers, AI agents, and REST APIs) and IBM i’s Db2 for i database.

Key Features:

• Modern database server for IBM i
• SQL query execution over WebSocket connections
• Secure, encrypted connections to Db2 for i
• Optimized for AI agent workloads
• Supports modern authentication methods
• Low-latency responses for interactive applications

Why Mapepire Enables AI and MCP Workloads

Traditional IBM i database access methods (ODBC, JDBC) don’t align well with modern AI and MCP architectures that require:

• Fast, lightweight connections: AI agents make frequent, short-lived database queries
• WebSocket support: Enables real-time, bidirectional communication for streaming results
• Modern JSON-based protocols: Simplifies integration with TypeScript/JavaScript ecosystems
• Low-latency responses: Essential for interactive AI conversations and tool executions

Mapepire bridges this gap by providing a modern, WebSocket-based SQL query interface that’s optimized for the request/response patterns of AI agents and MCP tools.

Installation Methods

Option 1: RPM Installation (Recommended)

The easiest way to install Mapepire is using the RPM package manager:

# 1. Install Mapepire using yum
yum install mapepire-server

# 2. Install Service Commander (if not already installed)
yum install service-commander

# 3. Start Mapepire service
sc start mapepire

If you need help getting started with RPMs on IBM i, see the IBM i Open Source RPM Guide.

Full Documentation: For comprehensive setup and configuration instructions, see the Mapepire System Administrator Guide.

Option 2: Manual Installation

If RPM installation isn’t available, you can install manually:

1. Create download directory:

   mkdir -p /opt/download
   

2. Download the distribution:

   cd /opt/download
   wget -O mapepire-server-dist.zip \
     https://github.com/Mapepire-IBMi/mapepire-server/releases/latest/download/mapepire-server-dist.zip
   

3. Extract and set permissions:

   mkdir -p /opt/mapepire
   cd /opt/mapepire
   jar xvf /opt/download/mapepire-server-dist.zip
   chown -R qsys .
   

Starting Mapepire

Service Commander (Recommended for RPM)

If you installed via RPM, use Service Commander for easy management:

# Install Service Commander (if not already installed)
yum install service-commander

# Start the service
sc start mapepire

# Check if it's running
sc check mapepire

# Stop the service (when needed)
sc stop mapepire

Manual Startup

For RPM installation:

nohup /QOpenSys/pkgs/bin/mapepire &

For manual installation:

nohup /opt/mapepire/bin/mapepire &

For manual installation with Service Commander:

cd /opt/mapepire/lib/mapepire
sc start mapepire.yaml

Configuration

Port Configuration

Mapepire uses port 8076 by default. This is the standard port and changing it is not recommended.

Important: You’ll need port 8076 when configuring the DB2i_PORT variable in your .env file. Ensure your IBM i firewall allows inbound connections on this port.

If you need to change the port:

# Set environment variable
export PORT=8077

# Or edit Service Commander configuration
scedit mapepire

TLS/SSL Configuration

Mapepire supports several TLS certificate options:

Option 1: Let’s Encrypt (Recommended)

If you have Let’s Encrypt certificates (e.g., from CertBot), Mapepire will automatically use them:

# Certificates should be located at:
/etc/letsencrypt/live/<hostname>/

Option 2: Custom Certificate

Create a custom certificate store with these specifications:

Setting	Value
File location	/QOpenSys/etc/mapepire/cert/server.jks
Format	JKS
Store password	mapepire
Key password	mapepire
Certificate alias	mapepire

Example using DCM Tools:

dcmexport --password=changeit --dcm-store=system --format=pkcs12 mystore.p12

keytool -importkeystore \
  -srckeystore mystore.p12 \
  -srcstoretype pkcs12 \
  -srcstorepass changeit \
  -srcalias "mydcmalias" \
  -destkeystore /QOpenSys/etc/mapepire/cert/server.jks \
  -deststoretype JKS \
  -deststorepass mapepire \
  -destkeypass mapepire \
  -destalias mapepire

Option 3: Self-Signed Certificate

If no certificate is configured, Mapepire will automatically generate a self-signed certificate. This is suitable for development but not recommended for production.

Security Configuration

Exit Points

Mapepire uses the same exit points as standard JDBC applications. For more information, see the IBM Support page on JDBC exit points.

Due to Mapepire’s architecture, all client connections appear to come from 127.0.0.1. IP-based exit point rules will need to inspect the CLIENT_WRKSTNNAME client special register to get the actual client IP address.

Connection Rules

Configure user and IP-based access restrictions in:

/QOpenSys/etc/mapepire/iprules.conf

Rule format:

• allow <username>@<ip-address>
• deny <username>@<ip-address>
• Use * as wildcard
• Last matching rule takes precedence
• Comments start with #

Example - Disable Q user profiles:*

# Allow connections from all hosts
allow *@*

# Deny logins from users starting with Q
deny q*@*

Example - Restrict to specific users and IP range:

# Deny by default
deny *@*

# Allow only specific users from 192.168.x.x
allow appusr1@192.168.*
allow appusr2@192.168.*

Testing the Installation

Verify Mapepire is Running

1. Check the process:

   ps aux | grep mapepire
   

2. Test connectivity:

   netstat -an | grep 8076
   

3. Test with Service Commander:

   sc check mapepire
   

Configure IBM i MCP Server

Once Mapepire is running, configure your IBM i MCP Server .env file:

# IBM i connection settings
DB2i_HOST=your-ibmi-hostname
DB2i_USER=your-username
DB2i_PASS=your-password
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=true

Set DB2i_IGNORE_UNAUTHORIZED=true if using self-signed certificates. For production with proper certificates, set this to false.

Troubleshooting

Common Issues

Port already in use:

# Check what's using the port
netstat -an | grep 8076

# Kill existing process if needed
pkill mapepire

Permission denied:

# Ensure proper ownership
chown -R qsys /opt/mapepire

Certificate issues:

# Check certificate location and permissions
ls -la /QOpenSys/etc/mapepire/cert/

Log Files

Check Mapepire logs for detailed error information:

# Service Commander logs
sc logs mapepire

# Manual startup logs (if using nohup)
tail -f nohup.out

Next Steps

After setting up Mapepire:

1. Configure your IBM i MCP Server
2. Test the connection
3. Set up SQL tools
4. Build your first agent

Additional Resources

• Mapepire GitHub Repository
• Mapepire Documentation
• IBM i Open Source Documentation
• DCM Tools for Certificate Management