doris-mcp-server

Purpose

Apache Doris MCP Server is an MCP Server used to expose the read-only capabilities of Apache Doris (an MPP-based real-time data warehouse) to MCP Hosts and AI agents through the MCP 2026-07-28 protocol. The package version is 1.0.0.

Main capabilities

• Version 1.0 replaces the original large flat tool surface with eight stable domains and fifty-four (stated in parallel in the documentation as fifty-five) progressively disclosed sub-capabilities.
• In the default layered mode, calling a domain with empty parameters {} discovers the authorized sub-capabilities under that domain and their exact schemas; then, carrying child_tool、arguments and the returned manifest_version , call the same domain again.
• Hosts that cannot use progressive disclosure can set MCP_TOOL_EXPOSURE_MODE=flatbefore startup to expose the same sub-capabilities under conflict-free formal names, and will not restore pre-1.0 aliases.
• Supports both Streamable HTTP and stdio transports; MCP 2026-07-28 protocol compatibility on the master branch is GA on Streamable HTTP and stdio (this GA statement applies only to protocol compatibility).

Usage

Environment requirements: Python 3.12 or later; Apache Doris 2.0.0 or later; network access to the Doris FE MySQL endpoint (usually port 9030).

After installing the pinned release version,doris-mcp-server starts the server,doris-mcp-client is a standalone client, and the two are not interchangeable.

After starting Streamable HTTP on the loopback address:

• MCP: POST http://127.0.0.1:3000/mcp
• legacy MCP (must be explicitly enabled): POST http://127.0.0.1:3000/mcp/legacy
• liveness: GET http://127.0.0.1:3000/live
• Doris-backed ready check: GET http://127.0.0.1:3000/ready

Hosts that only support Streamable HTTP during the handshake period (including Dify 1.16.1 using MCP 2025-06-18) must set ENABLE_LEGACY_HTTP_ADAPTER=true and connect to /mcp/legacy. This adapter only changes the protocol boundary and keeps the same 1.0 tools, authorization, capability gating, and read-only execution.

stdio can also be run for local Hosts.

Security boundaries

• The built-in 1.0 catalog is read-only;doris_admin is reserved and not registered.
• Supports static tokens, JWT, external OAuth/OIDC, and Doris-backed OAuth, provided that the configuration boundaries are mutually validated.
• Domain discovery and sub-capability execution use exact authorization identifiers.
• Doris RBAC remains the final authority for visible objects and data.
• Before data leaves the Server, boundary limits are imposed on SQL shape, identifiers, parameters, timeouts, row counts, byte counts, and result schemas.
• Secrets and backend errors are redacted in public results and logs.
• Non-loopback HTTP requires authentication unless an explicit dangerous development override is enabled.

Applicable scenarios

Suitable for integration and query scenarios that require an MCP Host or AI agent to access an Apache Doris data warehouse in a read-only manner, including Hosts that support progressive disclosure and Hosts that can only use Streamable HTTP during the handshake period.

Reliability boundaries and known limitations

The Server uses deterministic manifests and errors, signed expiration cursors, route-aware capability snapshots, bounded stale fallback, per-request connection routing, multi-FE failover, liveness/readiness separation, output schema validation, and redacted trace propagation. Unsupported or misconfigured capabilities can still be discovered, but their callable=false, and fails closed when invoked.

Current limits include: process-local Doris-backed OAuth; explicit-only ADBC, disabled by default and failing closed on token-bound routes; optional read-only Ossie grounding; an optional MetricFlow compiler sidecar whose SQL must be executed through the bounded MCP query runtime; and best-effort native lineage delivery.

License

Apache License 2.0, see LICENSE.txt and NOTICE.