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

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.

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 and implemented in 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, 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:

   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:

   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:

# ~/.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. Run the CLI's login command to obtain a JWT:

chat2db auth login --username admin --password secret

Copy the printed JWT string into the auth.token field of your config.yaml. According to the source code in 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:

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 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 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 and update 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.
• Configuration resides in ~/.chat2db/config.yaml and must specify the correct endpoint and auth.token.
• Authentication relies on JWT tokens generated through 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 within the chat2db-community-web module and documented in 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. 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 endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}