Quick start

August 1, 2026 · View on GitHub

English | 简体中文

This guide starts a local Apache Doris MCP Server 1.0.0, verifies health, and shows the hierarchical discovery call shape. It intentionally uses loopback addresses and placeholder credentials.

1. Prerequisites

  • Python 3.12 or later.
  • Apache Doris 2.0.0 or later. Later-version features are filtered dynamically.
  • FE MySQL endpoint access, normally port 9030.
  • FE HTTP endpoint access, normally port 8030, for profile and selected operational capabilities.
  • Explicit BE HTTP hosts when BE-level monitoring is required.

Confirm Python:

python3 --version

2. Install

From PyPI:

python3 -m venv .venv
source .venv/bin/activate
pip install doris-mcp-server==1.0.0

From a source checkout:

git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server
uv sync --group dev

The package installs two programs:

  • doris-mcp-server: starts the MCP Server.
  • doris-mcp-client: connects to an existing Server.

They are not interchangeable.

3. Configure the Doris route

export DORIS_HOST=127.0.0.1
export DORIS_PORT=9030
export DORIS_USER=root
export DORIS_PASSWORD='replace-me'
export DORIS_DATABASE=information_schema

For multi-FE routing:

export DORIS_HOSTS='fe-1.example:9030,fe-2.example:9030'
export DORIS_FE_HTTP_HOSTS='fe-1.example:8030,fe-2.example:8030'

Use a dedicated least-privileged Doris account in production. Do not commit passwords, bearer tokens, client secrets, JWT keys, or .env files.

4. Start Streamable HTTP

doris-mcp-server \
  --transport http \
  --host 127.0.0.1 \
  --port 3000

The modern MCP endpoint is:

POST http://127.0.0.1:3000/mcp

For a validated handshake-era Host such as Dify 1.16.1 using MCP 2025-06-18, restart with ENABLE_LEGACY_HTTP_ADAPTER=true and configure the Host URL as http://127.0.0.1:3000/mcp/legacy. Do not send legacy traffic to /mcp.

Health endpoints:

curl --fail http://127.0.0.1:3000/live
curl --fail http://127.0.0.1:3000/ready

/live verifies process and protocol availability. /ready also checks a bounded Doris route operation. A live-but-not-ready Server should be diagnosed before it is restarted.

HTTP binds to loopback by default. A non-loopback bind requires at least one authentication mode unless the operator explicitly enables the dangerous ALLOW_UNAUTHENTICATED_NON_LOOPBACK=true development override.

5. Start stdio

For a Host that launches the Server as a child process:

doris-mcp-server --transport stdio

Do not write ordinary application output to stdout in stdio mode. MCP frames use stdout; diagnostic logs belong on stderr or in configured log files.

6. Discover and call a child

In the default hierarchical mode, tools/list returns eight domain tools. Discover the catalog domain by calling doris_catalog with:

{}

The result contains authorized children, exact schemas, availability, and a manifest_version. A subsequent call uses the same top-level tool:

{
  "child_tool": "list_tables",
  "arguments": {
    "database": "information_schema"
  },
  "manifest_version": "<value returned by discovery>"
}

If the Server reports CHILD_MANIFEST_STALE, call the domain with {} again and use the new manifest. If a child has callable=false, inspect its structured reason_code; do not infer availability from its description.

Hosts without progressive-disclosure support may set:

export MCP_TOOL_EXPOSURE_MODE=flat

Restart the Server and reconnect the Host. Flat mode exposes the same 55 children under formal names such as doris_catalog_list_tables.

7. Verify the installation

doris-mcp-server --version
python -c "import doris_mcp_server; print(doris_mcp_server.__version__)"

From a source checkout:

uv run pytest test/test_release_artifacts.py test/test_product_identity.py
uv run python generate_tool_catalog.py --check

Next steps