Client Integration Overview

Connect the IBM i MCP Server to Claude Desktop, VSCode, Cursor, and 10+ other MCP-compatible clients

Client Integration Overview

The IBM i MCP Server can be integrated into any MCP-compatible client using either local (stdio) or remote (HTTP) connections. This guide provides an overview of supported clients and helps you choose the right integration approach.

Prerequisites: Before integrating with clients, ensure you have:

• IBM i MCP Server installed and built (npm install && npm run build)
• Mapepire running on your IBM i system (see Setup Mapepire)
• Your IBM i connection details (host, user, password, port)

Supported MCP Clients

The IBM i MCP Server works with popular MCP-compatible clients across different platforms:

Claude Desktop

Official desktop app for macOS and Windows

Claude Code

CLI tool with server management commands

IBM Bob

IBM’s AI-powered development assistant

VSCode

GitHub Copilot Chat integration

Cursor

AI-first code editor

Gemini CLI

Google AI command-line integration

Cline

VSCode extension for AI development

Transport Modes

The IBM i MCP Server supports two transport protocols:

Stdio (Local)

Standard Input/Output - Direct process communication

Characteristics:

• Runs locally on your machine
• Lower latency
• No network configuration needed
• Each client spawns its own server process

Best for:

• Desktop applications (Claude Desktop, Cursor)
• CLI tools (Claude Code)
• Development and testing
• Single-user scenarios

Requirements:

• Server must be installed locally
• Absolute path to tools directory
• Environment variables in client config

HTTP (Remote)

HTTP/WebSocket - Network-based communication

Characteristics:

• Runs on a remote server
• Shared server instance
• Requires authentication (recommended)
• Network accessible

Best for:

• Team collaboration
• Production deployments
• Cloud environments
• Multiple users sharing resources

Requirements:

• Server running with HTTP transport
• Network accessibility
• Authentication tokens (IBM i auth recommended)
• HTTPS for production

Client Comparison

Client	Platform	Stdio	HTTP	Authentication	Notes
Claude Desktop	macOS, Windows	✅	❌	N/A	Official desktop app (stdio only)
Claude Code	CLI	✅	✅	Bearer Token	CLI server management
IBM Bob	IDE	✅	✅	Bearer Token	IBM’s AI assistant (6,000+ users)
VSCode	Editor	✅	✅	Bearer Token	Via Copilot Chat
Cursor	Editor	✅	✅	Bearer Token	AI-first code editor
Gemini CLI	CLI	✅	✅	Bearer Token	Google AI integration
Cline	VSCode Ext	✅	✅	Bearer Token	streamableHttp support

Setup Prerequisites

For Local (Stdio) Setup

NPM Package (Recommended)

The easiest way to get started - no installation needed!

1. Verify npx is available:

   npx --version
   

2. Test the package:

   npx -y @ibm/ibmi-mcp-server@latest --help
   

3. Note your tools path:

   • Must be an absolute path
   • Example: /Users/yourname/myproject/tools
   • Or use --tools $(pwd)/tools for relative paths

Benefits:

• ✅ Always up-to-date with latest stable release
• ✅ No build step required
• ✅ Works across all clients (Claude Desktop, VSCode, Cursor)
• ✅ Automatic dependency management

Build from Source

For development or custom modifications:

1. Install the server globally:

   cd ibmi-mcp-server
   npm install
   npm run build
   npm link -w @ibm/ibmi-mcp-server
   

2. Verify installation:

   which ibmi-mcp-server
   

3. Note your tools path:

   • Must be an absolute path
   • Example: /Users/yourname/ibmi-mcp-server/tools

Benefits:

• Access to latest development features
• Ability to modify and customize
• Debug at source level

For Remote (HTTP) Setup

1. Configure server for HTTP with authentication:

   # In your .env file
   MCP_TRANSPORT_TYPE=http
   MCP_AUTH_MODE=ibmi
   IBMI_HTTP_AUTH_ENABLED=true
   IBMI_AUTH_ALLOW_HTTP=true  # Development only
   

2. Generate RSA keypair (for IBM i auth):

   mkdir -p secrets
   openssl genpkey -algorithm RSA -out secrets/private.pem -pkeyopt rsa_keygen_bits:2048
   openssl rsa -pubout -in secrets/private.pem -out secrets/public.pem
   

3. Start the server:

   npm run start:http
   

4. Obtain access token:

   node get-access-token.js --verbose
   export IBMI_MCP_ACCESS_TOKEN="your-token-here"
   

Authentication Methods

No Authentication (Development Only)

MCP_AUTH_MODE=none

Use for: Local development, testing, trusted networks

⚠️ Warning: Never use in production

IBM i HTTP Authentication (Recommended)

MCP_AUTH_MODE=ibmi
IBMI_HTTP_AUTH_ENABLED=true
IBMI_AUTH_KEY_ID=production
IBMI_AUTH_PRIVATE_KEY_PATH=secrets/private.pem
IBMI_AUTH_PUBLIC_KEY_PATH=secrets/public.pem

Use for: Per-user credentials, connection pooling, production

Features:

• Secure RSA+AES encryption
• Per-user connection pools
• Token-based access
• IBM i credential validation

JWT Authentication

MCP_AUTH_MODE=jwt
MCP_AUTH_SECRET_KEY=your-secret-key-min-32-chars

Use for: Custom authentication systems, token-based auth

OAuth Authentication

MCP_AUTH_MODE=oauth
OAUTH_ISSUER_URL=https://your-auth-server.com
OAUTH_AUDIENCE=ibmi-mcp-server

Use for: Enterprise SSO, external identity providers

Common Configuration Patterns

Claude Desktop (Local)

{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": ["@ibm/ibmi-mcp-server@latest", "-y", "--tools", "/absolute/path/to/tools"],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

Next Steps

1. Choose your client from the list above
2. Follow the specific setup guide for your chosen client
3. Configure authentication if using remote (HTTP) mode
4. Test the connection by listing available tools
5. Start building with SQL tools and agents

For detailed setup instructions, click on any client card above or navigate using the sidebar. Each client has unique configuration requirements and capabilities.

Troubleshooting

Connection Refused

• Verify server is running: ps aux | grep ibmi-mcp-server
• Check npm link worked: which ibmi-mcp-server
• Ensure TOOLS_YAML_PATH is an absolute path
• Verify IBM i credentials are correct

Authentication Failed (Remote)

• Confirm server is running with IBMI_HTTP_AUTH_ENABLED=true
• Verify token is valid: echo $IBMI_MCP_ACCESS_TOKEN
• Check server logs for authentication errors
• Ensure HTTPS is used in production

Tools Not Loading

• Validate YAML configuration: npm run validate -- --config tools
• Check file permissions on tools directory
• Use --list-toolsets to see available tools
• Review server startup logs for parsing errors

npx Command Not Found

Use direct node path instead:

{
  "command": "node",
  "args": [
    "/absolute/path/to/ibmi-mcp-server/dist/index.js",
    "--tools",
    "/absolute/path/to/tools"
  ]
}

Additional Resources

• Configuration Reference - All environment variables
• IBM i Authentication - Secure token setup
• Quick Start Guide - Basic server setup
• SQL Tools - Creating custom tools