Apache Doris MCP Server

English | 简体中文

Apache Doris MCP Server exposes read-only Apache Doris capabilities to MCP

Hosts and AI agents over MCP `2026-07-28`. Version 1.0 replaces a large flat

tool surface with eight stable domains and fifty-five progressively disclosed

child capabilities, while keeping runtime availability, authorization, input

schemas, output schemas, and failure behavior explicit.

Release status

The package version is `1.0.0`. MCP `2026-07-28` protocol compatibility on

`master` is Generally Available (GA) on Streamable HTTP and stdio.

This GA statement is scoped to protocol compatibility; the Python package

classifier remains Beta, and the documented deployment limits still apply.

Before upgrading, read the 1.0 release notes,

the 1.0 migration guide, and the generated

8-domain/55-child registry. The detailed release

record is Issue #189.

Architecture at a glance

MCP Host
  -> stdio or Streamable HTTP
  -> transport security and authentication
  -> MCP protocol validation and authorization
  -> stable domain discovery
  -> route-aware Doris capability detection
  -> exact child dispatch and read-only runtime
  -> request-specific Doris route and RBAC
  -> bounded, schema-validated result

The default `hierarchical` mode exposes these domains:

Call a domain with `{}` to discover its authorized children and exact schemas.

Call the same domain again with `child_tool`, `arguments`, and the returned

`manifest_version`. Hosts that cannot use progressive disclosure may set

`MCP_TOOL_EXPOSURE_MODE=flat` before startup; this exposes the same 55 children

under collision-free formal names and does not restore pre-1.0 aliases.

See Architecture,

Request lifecycle, and

Tool domains.

Quick start

Requirements:

• Python 3.12 or later;
• Apache Doris 2.0.0 or later;
• network access to the Doris FE MySQL endpoint, normally port `9030`.

Install the pinned release:

pip install doris-mcp-server==1.0.0

`doris-mcp-server` starts the Server. `doris-mcp-client` is a separate client;

the two commands are not interchangeable.

Configure a Doris route:

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

Start Streamable HTTP on loopback:

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

Endpoints:

• MCP: `POST http://127.0.0.1:3000/mcp`
• legacy MCP (opt-in): `POST http://127.0.0.1:3000/mcp/legacy`
• liveness: `GET http://127.0.0.1:3000/live`
• Doris-backed readiness: `GET http://127.0.0.1:3000/ready`

Hosts limited to handshake-era Streamable HTTP, including Dify 1.16.1 with

MCP `2025-06-18`, must set `ENABLE_LEGACY_HTTP_ADAPTER=true` and connect to

`/mcp/legacy`. The adapter changes only the protocol boundary; it preserves the

same 1.0 tools, authorization, capability gates, and read-only execution.

Or run stdio for a local Host:

doris-mcp-server --transport stdio

See the complete Quick start and

Host integration guide.

Security boundary

• The built-in 1.0 catalog is read-only; `doris_admin` is reserved and not

registered.

• Static tokens, JWT, external OAuth/OIDC, and Doris-backed OAuth are supported

under mutually validated configuration boundaries.

• Domain discovery and child execution use exact authorization identifiers.
• Doris RBAC remains the final authority for visible objects and data.
• SQL shape, identifiers, parameters, timeout, rows, bytes, and result schemas

are bounded before data leaves the Server.

• Secrets and backend errors are redacted from public results and logs.
• Non-loopback HTTP requires authentication unless an explicit dangerous

development override is enabled.

Read the Security and permission model and

the Doris fine-grained access guide.

Reliability boundary

The Server uses deterministic manifests and errors, signed expiring cursors,

route-aware capability snapshots, bounded stale fallback, request-specific

connection routing, multi-FE failover, liveness/readiness separation, output

Schema validation, and sanitized trace propagation. Unsupported or

misconfigured capabilities remain discoverable with `callable=false` and fail

closed when called.

Current limits include process-local Doris-backed OAuth, explicit-only ADBC

that is disabled by default and fail-closed on token-bound routes, optional

read-only Ossie grounding, an optional MetricFlow compiler sidecar whose SQL

must execute through the bounded MCP query runtime, and best-effort native

lineage delivery. See Reliability and limits.

Documentation

The root README is intentionally an entry point. The bilingual documentation

system is indexed at:

• English documentation
• 简体中文文档

Primary guides:

• Architecture
• Request and data flow
• Tool domains
• Capability availability
• Doris version capability matrix
• MetricFlow integration
• MCP 2026-07-28 contract
• Security model
• Deployment
• Reliability and limits
• Troubleshooting
• Configuration reference
• Host integrations
• Custom tool providers
• Contributing

Development

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

Generated artifacts must remain synchronized:

uv run python generate_tool_catalog.py --check
uv lock --check

See Contributing and verification.

License

Apache License 2.0. See LICENSE.txt and NOTICE.