Claude Code

Configure IBM i MCP Server with Claude Code CLI tool

Claude Code is the official CLI tool for Claude that provides built-in MCP server management commands. It supports both local (stdio) and remote (HTTP) server connections with a simple command-line interface.

Platform Support: macOS, Linux, Windows Transport Modes: Stdio (local) and HTTP (remote) Authentication: Bearer Token for HTTP mode

Prerequisites

Ensure you have Claude Code installed:

# Check if installed
claude --version

# Install if needed (follow official documentation)

Local (Stdio) Setup

Configure a local server that Claude Code will spawn and manage:

Using CLI Commands

Option 1: Interactive setup

claude mcp add ibmi-mcp \
  -e DB2i_HOST=your-ibmi-host.com \
  -e DB2i_USER=your-username \
  -e DB2i_PASS=your-password \
  -e DB2i_PORT=8076 \
  -e MCP_TRANSPORT_TYPE=stdio \
  -- npx -y @ibm/ibmi-mcp-server@latest --tools /absolute/path/to/tools

Option 2: With environment variable file

# Create .env file with credentials first
claude mcp add ibmi-mcp \
  -- npx -y @ibm/ibmi-mcp-server@latest --tools /absolute/path/to/tools

Using Configuration File

Edit ~/.claude.json:

{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": ["-y", "@ibm/ibmi-mcp-server@latest", "--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",
        "NODE_OPTIONS": "--no-deprecation"
      }
    }
  }
}

Important: The --tools path must be an absolute path, not relative.

Remote (HTTP) Setup

Connect to a remote IBM i MCP Server:

Using CLI Commands

# Add remote HTTP server with authentication
claude mcp add -t http ibmi-mcp \
  http://localhost:3010/mcp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"

Using Configuration File

Edit ~/.claude.json:

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

Getting Access Tokens: Use node get-access-token.js --verbose from the server directory to obtain authentication tokens.

Environment Variable Expansion

Claude Code supports environment variable expansion for secure credential management:

{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": ["@ibm/ibmi-mcp-server@latest", "-y", "--tools", "${IBMI_TOOLS_PATH}"],
      "env": {
        "DB2i_HOST": "${DB2i_HOST}",
        "DB2i_USER": "${DB2i_USER}",
        "DB2i_PASS": "${DB2i_PASS}",
        "DB2i_PORT": "${DB2i_PORT:-8076}",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

Supported syntax:

• ${VAR} - Expands to the value of environment variable VAR
• ${VAR:-default} - Expands to VAR if set, otherwise uses default

Managing Servers

Claude Code provides convenient commands for managing MCP servers:

# List all configured servers
claude mcp list

# Get details about a specific server
claude mcp get ibmi-mcp

# Remove a server
claude mcp remove ibmi-mcp

# Check server status in Claude Code
/mcp

Testing the Connection

After configuration:

# Start Claude Code and check MCP status
claude

# In Claude Code, check MCP servers
/mcp

# List available tools
"What tools do you have available?"

# Test a tool
"Show me the IBM i system status"

CLI Options for Server Command

When adding servers, you can use various CLI options:

# With specific toolsets
claude mcp add ibmi-mcp \
  -- npx -y @ibm/ibmi-mcp-server@latest \
     --tools /path/to/tools \
     --toolsets performance,security

# With explicit stdio transport
claude mcp add -t stdio ibmi-mcp \
  -- npx -y @ibm/ibmi-mcp-server@latest \
     --tools /path/to/tools

# List available toolsets
npx -y @ibm/ibmi-mcp-server@latest --list-toolsets --tools /path/to/tools

Troubleshooting

Server Command Not Found

Symptoms: npx: command not found or ibmi-mcp-server: not found

Solutions:

• Ensure Node.js and npm are installed: node --version
• Install server globally: npm link from server directory
• Use full node path:
  claude mcp add ibmi-mcp \
    -- node /absolute/path/to/ibmi-mcp-server/dist/index.js \
       --tools /absolute/path/to/tools
  

Authentication Failed

Symptoms: 401 Unauthorized for remote connections

Solutions:

• Get fresh token: node get-access-token.js --verbose
• Verify server is running with auth enabled
• Check token hasn’t expired (default: 1 hour)
• Ensure header format is correct: Authorization: Bearer TOKEN

Tools Not Loading

Symptoms: Server starts but no tools available

Solutions:

• Verify tools path is absolute: /full/path/to/tools
• Check YAML files are valid
• Test tools path: npx -y @ibm/ibmi-mcp-server@latest --list-toolsets --tools /path
• Check IBM i connection credentials

Advanced Configuration

Multiple Environments

Configure different servers for dev and production:

{
  "mcpServers": {
    "ibmi-dev": {
      "command": "npx",
      "args": ["@ibm/ibmi-mcp-server@latest", "-y", "--tools", "/path/to/dev-tools"],
      "env": {
        "DB2i_HOST": "dev-ibmi.company.com",
        "DB2i_USER": "DEVUSER",
        "DB2i_PASS": "devpass",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    },
    "ibmi-prod": {
      "url": "https://prod-mcp.company.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${PROD_MCP_TOKEN}"
      }
    }
  }
}

Custom Tool Paths

Switch between different tool configurations:

# Add server with custom tools
claude mcp add ibmi-performance \
  -- npx -y @ibm/ibmi-mcp-server@latest \
     --tools /path/to/performance-tools \
     --toolsets monitoring,diagnostics

# Add server with all tools
claude mcp add ibmi-all \
  -- npx -y @ibm/ibmi-mcp-server@latest \
     --tools /path/to/all-tools

Next Steps

CLI Reference

Learn all CLI options for the server

Configuration

Explore environment variables

SQL Tools

Create custom SQL operations

Other Clients

Explore other MCP clients

Additional Resources

• Claude Code MCP Documentation
• IBM i MCP Quick Start
• Authentication Setup