# How to Configure the MCP CLI Integration for Chat2DB: A Complete Setup Guide

> Learn how to configure the MCP CLI integration for Chat2DB. This guide covers setting up the community server, CLI binary, and config file for seamless integration.

- Repository: [OtterMind/Chat2DB](https://github.com/OtterMind/Chat2DB)
- Tags: how-to-guide
- Published: 2026-07-28

---

**Configure the Chat2DB MCP CLI by starting the community server on port 10825, installing the Chat2DB-CLI binary, and creating a `~/.chat2db/config.yaml` file that points to `http://127.0.0.1:10825/api/mcp` with a valid JWT authentication token generated through the server's authentication layer.**

The OtterMind/Chat2DB repository provides an open-source database management platform that exposes a Multi-Client Protocol (MCP) endpoint for programmatic access. Configuring the MCP CLI integration allows you to execute SQL queries, import data, and manage dashboards directly from the terminal using the separate Chat2DB-CLI binary. This guide covers the exact configuration steps, source file references from `chat2db-community-server`, and the authentication flow implemented in [`AuthController.java`](https://github.com/OtterMind/Chat2DB/blob/main/AuthController.java).

## Architecture Overview

The MCP CLI integration relies on four coordinated components that bridge the terminal and the Chat2DB backend:

- **Chat2DB Community Server**: Hosts the MCP HTTP endpoint and translates CLI calls into internal domain services. The entry point is defined in [`spec/code/server/java-web-controller-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-web-controller-contracts.md) and implemented in [`chat2db-community-server/chat2db-community-web/src/main/java/com/chat2db/web/controller/McpController.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-web/src/main/java/com/chat2db/web/controller/McpController.java).
- **MCP Adapter**: Implements the protocol routes under `/api/mcp/**` within the `chat2db-community-web` module, bridging HTTP requests to the internal service layer.
- **Chat2DB-CLI**: A standalone binary (Go/Node) distributed via the Chat2DB-CLI repository that sends MCP-formatted JSON payloads to the backend.
- **Authorization Layer**: Generates and validates tokens via [`chat2db-community-server/chat2db-community-web/src/main/java/com/chat2db/web/controller/AuthController.java`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/chat2db-community-web/src/main/java/com/chat2db/web/controller/AuthController.java), which the CLI stores in its local configuration.

## Prerequisites

Before configuring the CLI, ensure the backend is running and the binary is installed:

1. **Start the Chat2DB Community Server** with MCP mode enabled. The server exposes the endpoint at `http://127.0.0.1:10825/api/mcp/` by default:

   ```bash
   java -Dchat2db.runtime.mode=community \
        -Dchat2db.network.status=OFFLINE \
        -Dserver.port=10825 \
        -jar chat2db-community-server/chat2db-community-start/target/chat2db-community.jar
   ```

2. **Install the Chat2DB-CLI** binary from the Chat2DB-CLI repository. For macOS users:

   ```bash
   brew install chat2db-cli
   ```

   Alternatively, download the appropriate binary from the releases page for Linux or Windows.

## Step-by-Step MCP CLI Configuration

### 1. Create the CLI Configuration File

The Chat2DB-CLI reads connection settings from `~/.chat2db/config.yaml`. Create this file if it does not exist:

```yaml

# ~/.chat2db/config.yaml

endpoint: "http://127.0.0.1:10825/api/mcp"
auth:
  token: ""   # populated in the next step

```

Set the `endpoint` value to match the host and port of your running Chat2DB instance. If running locally with the default configuration, use `http://127.0.0.1:10825/api/mcp`.

### 2. Authenticate and Generate Tokens

The backend validates every MCP request against tokens generated by [`AuthController.java`](https://github.com/OtterMind/Chat2DB/blob/main/AuthController.java). Run the CLI's login command to obtain a JWT:

```bash
chat2db auth login --username admin --password secret

```

Copy the printed JWT string into the `auth.token` field of your [`config.yaml`](https://github.com/OtterMind/Chat2DB/blob/main/config.yaml). According to the source code in [`AuthController.java`](https://github.com/OtterMind/Chat2DB/blob/main/AuthController.java), the backend validates these tokens on each request to the MCP endpoints.

### 3. Verify MCP Connectivity

Test the configuration with a simple query to confirm the CLI can communicate with the MCP adapter:

```bash
chat2db query "SELECT version();" --format json

```

A successful response containing your database version confirms that the CLI is correctly parsing `~/.chat2db/config.yaml` and reaching the [`McpController.java`](https://github.com/OtterMind/Chat2DB/blob/main/McpController.java) endpoints.

## Common MCP CLI Operations

Once configured, use the CLI to script database operations through the MCP layer:

- **Import SQL Files**: `chat2db import /path/to/file.sql` sends file contents via MCP to the server's import service.
- **Export Query Results**: `chat2db export "SELECT * FROM users" --output users.csv` retrieves result sets through MCP and writes CSV files.
- **Manage Dashboards**: `chat2db dashboard create --name "Sales Overview"` calls the MCP dashboard-management API.
- **List Plugins**: `chat2db plugin list` queries the MCP endpoint for installed SPI plugins registered in the backend.

## Troubleshooting MCP Connection Issues

| Symptom | Root Cause | Solution |
|---------|------------|----------|
| `Connection refused` | The Community Server is not running or the port is incorrect. | Verify the server start command uses `-Dserver.port=10825` and ensure the `endpoint` URL in [`config.yaml`](https://github.com/OtterMind/Chat2DB/blob/main/config.yaml) matches the running instance. |
| `401 Unauthorized` | The JWT token is missing or expired. | Run `chat2db auth login` again to generate a new token via [`AuthController.java`](https://github.com/OtterMind/Chat2DB/blob/main/AuthController.java) and update [`config.yaml`](https://github.com/OtterMind/Chat2DB/blob/main/config.yaml). |
| `Invalid MCP payload` | Version mismatch between CLI and server. | Ensure both the CLI binary and the Chat2DB server JAR are from compatible releases as documented in the CLI repository. |

## Summary

- The **MCP CLI integration** requires a running Chat2DB Community Server exposing `/api/mcp/**` endpoints handled by [`McpController.java`](https://github.com/OtterMind/Chat2DB/blob/main/McpController.java).
- Configuration resides in **`~/.chat2db/config.yaml`** and must specify the correct `endpoint` and `auth.token`.
- **Authentication** relies on JWT tokens generated through [`AuthController.java`](https://github.com/OtterMind/Chat2DB/blob/main/AuthController.java) and stored locally by the CLI.
- Verify setup by executing **`chat2db query`** against your database to confirm JSON payload processing through the MCP adapter.

## Frequently Asked Questions

### What is the default MCP endpoint URL for Chat2DB?

The default MCP endpoint is `http://127.0.0.1:10825/api/mcp/`. This path is registered in [`McpController.java`](https://github.com/OtterMind/Chat2DB/blob/main/McpController.java) within the `chat2db-community-web` module and documented in [`java-web-controller-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/java-web-controller-contracts.md). When starting the server with `-Dserver.port=10825`, the CLI should point to this exact base URL.

### Where does the Chat2DB-CLI store its configuration file?

The CLI stores its configuration at **`~/.chat2db/config.yaml`** (in your home directory). This YAML file contains the `endpoint` address and the `auth.token` required for MCP communication. You must create this file manually if the directory does not exist after installing the binary.

### How do I refresh an expired MCP authentication token?

Run the **`chat2db auth login --username <user> --password <pass>`** command to generate a new JWT through the backend's [`AuthController.java`](https://github.com/OtterMind/Chat2DB/blob/main/AuthController.java). Copy the returned token into the `auth.token` field of your `~/.chat2db/config.yaml`. The server validates token expiration on each MCP request, so refresh immediately upon receiving 401 errors.

### Can I use the MCP CLI with a remote Chat2DB server?

Yes, provided the remote server has the MCP endpoint exposed and accessible. Update the **`endpoint`** value in `~/.chat2db/config.yaml` from `127.0.0.1` to the remote host's IP or domain (e.g., `http://192.168.1.100:10825/api/mcp`). Ensure firewalls allow HTTP traffic to port 10825 and that you generate the token against the remote instance's [`AuthController.java`](https://github.com/OtterMind/Chat2DB/blob/main/AuthController.java) endpoint.