> ## Documentation Index
> Fetch the complete documentation index at: https://ibm-d95bab6e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start Guide

> Get your IBM i MCP Server running in under 15 minutes with step-by-step setup instructions.

Get your IBM i MCP Server up and running in under 15 minutes. This guide walks you through installation, configuration, and your first successful tool execution.

***

## Before You Begin

Complete these prerequisites before starting the installation:

<Steps>
  <Step title="Verify Node.js Installation">
    Ensure Node.js 18 or higher is installed on your development machine:

    ```bash theme={null}
    node --version
    # Should show v18.0.0 or higher
    ```

    **Don't have Node.js?** Download from [nodejs.org](https://nodejs.org/)
  </Step>

  <Step title="Install Mapepire on IBM i">
    Mapepire must be running on your IBM i system before proceeding.

    **Not installed yet?** Follow the [Setup Mapepire guide](/setup-mapepire) (takes \~10 minutes)

    **Already installed?** Verify it's running:

    ```bash theme={null}
    # On IBM i
    sc check mapepire
    # Should show "running"
    ```

    **Note the port**: Default is 8076—you'll need this for configuration.
  </Step>

  <Step title="Gather IBM i Credentials">
    You'll need:

    * IBM i hostname or IP address
    * User profile with database authorities
    * User password
    * Access to QSYS2 system services (verify with your system administrator)
  </Step>

  <Step title="Set Aside Time">
    Plan for 15-20 minutes of uninterrupted setup time.
  </Step>
</Steps>

<Success>
  ✓ **Ready to proceed?** All prerequisites met? Continue to installation.
</Success>

***

## Step 1: Installation

Choose your installation method based on your needs:

<Tabs>
  <Tab title="NPM Package (Recommended)">
    **Best for:** Production use, quick setup, always-updated package

    The official npm package provides instant installation without building from source.

    ```bash theme={null}
    # No installation needed - npx downloads and runs automatically
    npx -y @ibm/ibmi-mcp-server@latest --help
    ```

    **Benefits:**

    * ✅ Always up-to-date with latest stable release
    * ✅ No build step required
    * ✅ Instant setup in seconds
    * ✅ Automatic dependency management
    * ✅ Perfect for CI/CD pipelines

    <Note>
      The `-y` flag automatically accepts the npm package installation prompt. You can omit it if you want to confirm before installation.
    </Note>

    <Success>
      ✓ **Verify the package works:**

      ```bash theme={null}
      npx -y @ibm/ibmi-mcp-server@latest --help
      ```

      You should see the help output with available options.
    </Success>

    **Next:** Skip to [Step 2: Configuration](#step-2-configuration)
  </Tab>

  <Tab title="Build from Source">
    **Best for:** Development, customization, contributing, latest features

    <Note>
      **Repository Structure**: The IBM i MCP Server follows a modular architecture:

      * `server/` - MCP server implementation (main package)
      * `tools/` - SQL tool YAML configurations
      * `agents/` - Agent implementations and examples
      * `deployment/` - Deployment configurations (Docker, Gateway, OpenShift)
    </Note>

    Clone the repository and install dependencies:

    ```bash theme={null}
    git clone https://github.com/IBM/ibmi-mcp-server.git
    cd ibmi-mcp-server
    npm install
    ```

    Build the project:

    ```bash theme={null}
    npm run build
    ```

    <Tip>
      Use `npm run rebuild` for a clean install if you encounter any issues.
    </Tip>

    <Success>
      ✓ **Verify the build succeeded:**

      * No error messages in the output
      * `dist/` directory was created
      * `dist/index.js` exists

      **Build failed?** Check that Node.js 18+ is installed and all dependencies downloaded successfully.
    </Success>

    **Benefits:**

    * ✅ Access to latest development features
    * ✅ Ability to modify and customize code
    * ✅ Contribute back to the project
    * ✅ Debug and troubleshoot at source level
  </Tab>
</Tabs>

***

## Step 2: Configuration

Create your environment configuration file:

<Tabs>
  <Tab title="NPM Package">
    Create a `.env` file in your current directory:

    ```bash theme={null}
    cat > .env << 'EOF'
    # IBM i DB2 for i Connection Settings
    DB2i_HOST=your-ibmi-host
    DB2i_USER=your-username
    DB2i_PASS=your-password
    DB2i_PORT=8076
    DB2i_IGNORE_UNAUTHORIZED=true

    # Server Configuration
    MCP_TRANSPORT_TYPE=http
    MCP_HTTP_PORT=3010
    EOF
    ```

    Edit the file and replace the placeholder values with your actual IBM i credentials.
  </Tab>

  <Tab title="Build from Source">
    Copy the example configuration and edit it:

    ```bash theme={null}
    # From ibmi-mcp-server directory
    cp .env.example .env
    ```

    Edit the `.env` file with your IBM i connection details:

    ```bash theme={null}
    # IBM i DB2 for i Connection Settings
    DB2i_HOST=your-ibmi-host
    DB2i_USER=your-username
    DB2i_PASS=your-password
    DB2i_PORT=8076
    DB2i_IGNORE_UNAUTHORIZED=true

    # Server Configuration
    MCP_TRANSPORT_TYPE=http
    MCP_HTTP_PORT=3010
    ```
  </Tab>
</Tabs>

<Warning>
  Replace the connection values with your actual IBM i system credentials. The user profile must have appropriate authorities for database operations.
</Warning>

<Warning>
  **Mapepire is Required**: Before proceeding, you must have Mapepire running on your IBM i system. Mapepire is a modern database server for IBM i that provides SQL query execution over WebSocket connections, optimized for AI agent workloads. If you haven't installed it yet, follow our [Setup Mapepire guide](/setup-mapepire) to install and configure it. Default port: **8076**.
</Warning>

<Success>
  ✓ **Verify your configuration:**

  * `.env` file exists in the root directory
  * `DB2i_HOST` is set to your IBM i hostname (not `127.0.0.1` if running in Docker)
  * `DB2i_USER` and `DB2i_PASS` are valid IBM i credentials
  * `DB2i_PORT` matches your Mapepire port (default: 8076)

  **Having connection issues?** See the [troubleshooting section](#troubleshooting) below.
</Success>

<Card title="Explore All Configuration Options →" icon="gear" href="/configuration">
  The Configuration guide covers authentication modes (JWT, OAuth, IBM i), HTTP/HTTPS settings, OpenTelemetry observability, and all environment variables with examples for development and production.
</Card>

***

## Step 3: Create Your First SQL Tool

SQL tools are YAML-based configurations that define SQL queries the MCP server can execute. Each tool specifies a data source, parameters, and the SQL statement to run.

### Create Tools Directory

First, create a directory to store your tool configurations:

```bash theme={null}
mkdir -p tools
```

### Create a Simple Tool Configuration

Create a file named `tools/quickstart.yaml` with the following content:

```yaml theme={null}
sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 8076
    ignore-unauthorized: true

tools:
  system_activity:
    source: ibmi-system
    description: "Current system activity information including active jobs and resource utilization"
    parameters: []
    statement: |
      SELECT * FROM TABLE(QSYS2.SYSTEM_ACTIVITY_INFO())

toolsets:
  performance:
    tools:
      - system_activity
```

### Understanding the YAML Structure

The YAML configuration has three main sections:

<Steps>
  <Step title="Sources">
    Defines the IBM i data sources your tools will connect to. The environment variables (`${DB2i_HOST}`, etc.) are automatically replaced with values from your `.env` file.

    ```yaml theme={null}
    sources:
      ibmi-system:
        host: ${DB2i_HOST}
        user: ${DB2i_USER}
        password: ${DB2i_PASS}
    ```
  </Step>

  <Step title="Tools">
    Defines the SQL operations available to AI agents. Each tool specifies:

    * `source`: Which data source to use
    * `description`: What the tool does (helps AI understand when to use it)
    * `parameters`: Input parameters (empty array `[]` means no parameters required)
    * `statement`: The SQL query to execute

    ```yaml theme={null}
    tools:
      system_activity:
        source: ibmi-system
        description: "Current system activity information including active jobs and resource utilization"
        parameters: []
        statement: |
          SELECT * FROM TABLE(QSYS2.SYSTEM_ACTIVITY_INFO())
    ```
  </Step>

  <Step title="Toolsets">
    Groups related tools together for easier management. You can load specific toolsets when starting the server using `--toolsets performance`.

    ```yaml theme={null}
    toolsets:
      performance:
        tools:
          - system_activity
    ```
  </Step>
</Steps>

<Success>
  ✓ **Verify your tool configuration:**

  * `tools/quickstart.yaml` file exists
  * YAML syntax is valid (no tabs, proper indentation with spaces)
  * Environment variables are wrapped in `${}` syntax
  * SQL statement uses the pipe `|` character for multi-line strings
</Success>

<CardGroup cols={2}>
  <Card title="Use Pre-Built Tools" icon="box" href="/sql-tools/using-default-tools">
    **Start with ready-made tools!** Learn how to run the server with pre-built SQL tools for performance monitoring, security analysis, and system administration.
  </Card>

  <Card title="Build Custom Tools" icon="hammer" href="/sql-tools/overview">
    **Ready to build more tools?** The SQL Tools documentation covers parameters, validation, multiple data sources, complex queries, and the full YAML configuration reference.
  </Card>
</CardGroup>

***

## Step 4: Start the Server

Start the server in HTTP mode with your new SQL tool:

<Tabs>
  <Tab title="NPM Package (Recommended)">
    ```bash theme={null}
    export MCP_SERVER_CONFIG=.env
    npx -y @ibm/ibmi-mcp-server@latest --transport http --tools ./tools/quickstart.yaml
    ```

    **Session Modes**:

    * `auto` (default): Automatically detects client capabilities ← **Start with this**
    * `stateful`: Maintains persistent sessions with connection state
    * `stateless`: Each request is independent, no session state

    Set via environment: `MCP_SESSION_MODE=stateful npx -y @ibm/ibmi-mcp-server@latest --transport http`
  </Tab>

  <Tab title="Build from Source">
    ```bash theme={null}
    # From server/ directory
    npm run start:http -- --tools ../tools/quickstart.yaml
    ```

    **Session Modes**:

    * `auto` (default): Automatically detects client capabilities ← **Start with this**
    * `stateful`: Maintains persistent sessions with connection state
    * `stateless`: Each request is independent, no session state

    Set via environment: `MCP_SESSION_MODE=stateful npm run start:http`
  </Tab>
</Tabs>

<Note>
  **Alternative: Stdio Transport** - For MCP Inspector or CLI tools, use `--transport stdio` (NPM package) or `npm run start:stdio` (build from source). However, HTTP transport is recommended for most use cases.
</Note>

**Available CLI Options**:

| Option               | Description                 | Example                           |
| -------------------- | --------------------------- | --------------------------------- |
| `--tools <path>`     | Override YAML tools path    | `--tools ./my-configs`            |
| `--toolsets <list>`  | Load specific toolsets only | `--toolsets performance,security` |
| `--transport <type>` | Force transport type        | `--transport http`                |
| `--help`             | Show help information       | `--help`                          |
| `--list-toolsets`    | List available toolsets     | `--list-toolsets`                 |

You should see output similar to:

```
✓ Server ready!
  Transport: http
  Host: 127.0.0.1:3010
  Endpoint: http://127.0.0.1:3010/mcp
  Tools loaded: 1
```

<Success>
  ✓ **Verify the server started successfully:**

  * See "Server ready!" message
  * HTTP endpoint is displayed (or "Stdio ready" for stdio mode)
  * Number of tools loaded shown (should be > 0)
  * No error messages about Mapepire connection
  * Server process remains running (doesn't exit immediately)

  **Server not starting?** Check:

  1. Mapepire is running on IBM i: `sc check mapepire`
  2. Firewall allows connection to port 8076
  3. IBM i credentials are correct in `.env`
  4. No other process is using port 3010 (HTTP mode)
</Success>

***

## Step 5: Test with Sample MCP Client

Now that your server is running, test it with the example Python client from the [GitHub repository](https://github.com/IBM/ibmi-mcp-server/tree/main/client) to verify connectivity and tool execution.

<Note>
  **Example Client Location**: The sample client scripts are available in the [`client/`](https://github.com/IBM/ibmi-mcp-server/tree/main/client) directory of the GitHub repository. Clone the repository or download the files to follow along.
</Note>

### Install uv (Python Package Manager)

If you don't have `uv` installed:

```bash theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
```

<Note>
  **Why uv?** [uv](https://github.com/astral-sh/uv) is a fast Python package manager that handles virtual environments and dependencies automatically. It's the recommended way to run the client examples.
</Note>

### Run the MCP Client Script

In a **new terminal window** (keep the server running in the first terminal):

```bash theme={null}
# Clone the repository if you haven't already
git clone https://github.com/IBM/ibmi-mcp-server.git
cd ibmi-mcp-server/client

# Install dependencies and run the test client
uv run mcp_client.py
```

<Tip>
  **Already have the repo cloned?** Just navigate to the `client/` directory and run `uv run mcp_client.py`
</Tip>

You should see output like this:

```
================================================================================
AVAILABLE TOOLS
================================================================================
 1. system_activity
    └─ Get real-time IBM i system activity metrics

================================================================================
SYSTEM ACTIVITY RESULT
================================================================================

✓ Query executed successfully in 145ms
  SQL: SELECT * FROM QSYS2.SYSTEM_ACTIVITY_INFO

  Results (1 row(s)):
  ----------------------------------------------------------------------------
  SYSTEM_NAME                   : YOURSYSTEM
  CURRENT_TIMESTAMP             : 2024-12-10-15:30:45.123456
  CPU_UTILIZATION               : 15.2
  MEMORY_USED_MB                : 8192
  ACTIVE_JOBS                   : 542
  ----------------------------------------------------------------------------
```

<Success>
  ✓ **Verify your connection works:**

  * List of available tools displayed
  * `system_activity` tool executed successfully
  * Real data from your IBM i system returned
  * No connection errors or timeouts

  **Not seeing data?** Check:

  1. MCP server is still running (check first terminal)
  2. Server started on port 3010 (matches script's `localhost:3010`)
  3. No firewall blocking local connections
  4. Server logs show the incoming request
</Success>

<Accordion title="What does this script do?">
  The `mcp_client.py` script:

  1. Connects to your running MCP server at `http://localhost:3010/mcp`
  2. Lists all available tools (SQL tools loaded from your YAML configs)
  3. Executes the `system_activity` tool (a pre-built IBM i monitoring query)
  4. Formats and displays the results

  **View Source**: See the implementation at [`client/mcp_client.py`](https://github.com/IBM/ibmi-mcp-server/blob/main/client/mcp_client.py) to understand how to use the MCP client SDK.
</Accordion>

***

## Step 6: Run an AI Agent (Optional)

Now that you've verified the MCP server works, try the example AI agent from the [GitHub repository](https://github.com/IBM/ibmi-mcp-server/tree/main/client) that can answer natural language questions about your IBM i system.

<Note>
  **Agent Script Location**: The `agent.py` script is in the [`client/`](https://github.com/IBM/ibmi-mcp-server/tree/main/client) directory of the GitHub repository. If you haven't cloned the repo yet (from Step 5), you'll need to do so first.
</Note>

### Configure API Key

The agent uses an LLM to understand your questions and call the appropriate MCP tools. You'll need an API key:

<Tabs>
  <Tab title="OpenAI (Recommended)">
    Create a `.env` file in the `client/` directory:

    ```bash theme={null}
    # From the client directory
    echo "OPENAI_API_KEY=your-openai-api-key-here" > .env
    ```

    **Get your API key**: Visit [OpenAI API Keys](https://platform.openai.com/api-keys)
  </Tab>

  <Tab title="Ollama (Local)">
    Install and run Ollama locally:

    ```bash theme={null}
    # Install Ollama (macOS)
    brew install ollama

    # Start Ollama and pull a model
    ollama run qwen2.5
    ```

    No API key needed—Ollama runs locally.
  </Tab>
</Tabs>

### Run the Agent

From the `client/` directory (where you ran the previous step), ask natural language questions about your IBM i system:

<Tabs>
  <Tab title="OpenAI">
    ```bash theme={null}
    # If you skipped Step 5, clone the repo first:
    # git clone https://github.com/IBM/ibmi-mcp-server.git
    # cd ibmi-mcp-server/client

    # Run the agent with OpenAI
    uv run agent.py -p "What is my system performing?" --model-id "openai:gpt-4o"

    # Or use the default prompt
    uv run agent.py --model-id "openai:gpt-4o"
    ```
  </Tab>

  <Tab title="Ollama (Local)">
    ```bash theme={null}
    # If you skipped Step 5, clone the repo first:
    # git clone https://github.com/IBM/ibmi-mcp-server.git
    # cd ibmi-mcp-server/client

    # Run the agent with local Ollama
    uv run agent.py -p "What is my system performing?" --model-id "ollama:qwen2.5"

    # Or use the default prompt
    uv run agent.py --model-id "ollama:qwen2.5"
    ```
  </Tab>
</Tabs>

**Example interaction**:

```
You: What is my system status?

Agent: Your IBM i system "YOURSYSTEM" is running normally with:
- CPU utilization at 15.2%
- 8GB of memory in use
- 542 active jobs
- System is responsive and healthy
```

<Tip>
  The agent automatically:

  1. Analyzes your natural language question
  2. Selects the appropriate MCP tool(s) to call
  3. Executes the tool(s) on your IBM i system
  4. Synthesizes the results into a natural language response

  **View Source**: See [`client/agent.py`](https://github.com/IBM/ibmi-mcp-server/blob/main/client/agent.py) for the implementation details.
</Tip>

<Card title="Build Production Agents" icon="rocket" href="/agents/overview">
  **Ready for more?** Explore our **Agent Integrations** documentation to build production-ready agents with Agno, Google ADK, or LangChain. Learn about FilteredMCPTools, specialized agent patterns, persistent memory, and multi-agent architectures.
</Card>

***

## 🎉 Congratulations!

You've successfully set up the IBM i MCP Server! Here's what you accomplished:

<Steps>
  <Step title="✅ Server Installed">
    Built and configured the MCP server with IBM i connection
  </Step>

  <Step title="✅ Connection Verified">
    Connected to Mapepire and your IBM i database
  </Step>

  <Step title="✅ Tools Tested">
    Listed and executed SQL tools via the MCP client
  </Step>

  <Step title="✅ Agent Ready (Optional)">
    Ran an AI agent that understands natural language queries
  </Step>
</Steps>

Your MCP server is now ready for:

* **Connecting AI clients** (Claude Desktop, VSCode, Cursor)
* **Creating custom SQL tools** for your specific use cases
* **Building specialized agents** for IBM i administration and monitoring

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Client Integration" icon="plug" href="/clients/overview">
    Connect the server to Claude Desktop, VSCode, Cursor, and 10+ other MCP clients
  </Card>

  <Card title="SQL Tools" icon="database" href="/sql-tools/overview">
    Learn how to create custom SQL operations using YAML configurations
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration">
    Explore all configuration options and environment variables
  </Card>

  <Card title="Agent Development" icon="robot" href="/agents/building-agents">
    Build sophisticated AI agents that understand IBM i concepts
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Refused" icon="">
    * Verify your IBM i host is reachable: `ping your-ibmi-host`
    * Check that the Mapepire daemon is running on port 8076
    * Ensure your user profile has database authorities
  </Accordion>

  <Accordion title="Authentication Failed" icon="">
    * Verify your IBM i username and password are correct
    * Check that your user profile is not disabled or expired
    * Ensure you have appropriate authorities for QSYS2 services
  </Accordion>

  <Accordion title="Port Already in Use" icon="">
    Change the port in your `.env` file:

    ```bash theme={null}
    MCP_HTTP_PORT=3011
    ```

    Then restart the server.
  </Accordion>

  <Accordion title="Tools Not Loading" icon="">
    * Check that `prebuiltconfigs/` directory exists
    * Verify your YAML tool configurations are valid
    * Use `--list-toolsets` to see available tools:

    ```bash theme={null}
    npm run start:http -- --list-toolsets
    ```
  </Accordion>

  <Accordion title="Client Script Fails (mcp_client.py)" icon="">
    **Connection refused or timeout:**

    * Ensure MCP server is running: check for "Server ready!" message
    * Verify server is on port 3010 (or update script if using different port)
    * Server must use HTTP transport (not stdio)

    **uv command not found:**

    ```bash theme={null}
    # Install uv
    curl -LsSf https://astral.sh/uv/install.sh | sh

    # Restart terminal or reload shell
    source ~/.bashrc  # or ~/.zshrc
    ```

    **Python version error:**

    * Client requires Python 3.13+ (check pyproject.toml)
    * Install Python 3.13: `brew install python@3.13` (macOS)
    * Or use `uv python install 3.13`

    **Dependencies fail to install:**

    ```bash theme={null}
    # Clear uv cache and retry
    cd client
    rm -rf .venv
    uv sync
    ```
  </Accordion>
</AccordionGroup>

<Info>
  **Completion Time**: This quickstart should take 20-30 minutes including the optional agent setup. Most time is spent waiting for installations and builds. If you encounter issues, check the [configuration guide](/configuration) or review the troubleshooting section above.
</Info>