Doris MCP Server

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:

Domain	Children	Responsibility
doris_catalog	5	catalogs, databases, tables, table context, size
doris_query	7	query, explain, profile, diagnosis, slow queries, explicit ADBC
doris_cluster	11	nodes, tasks, metrics, memory, cache, compaction, workloads
doris_pipeline	5	ingestion, materialized views, freshness, dependencies
doris_search	4	text/vector/hybrid search, analyzers, indexes, diagnosis
doris_governance	8	quality, storage, lineage, audit, UDFs, auth mapping
doris_lakehouse	3	external catalogs, lakehouse tables, Variant
doris_semantic	12	optional Apache Ossie grounding and MetricFlow consumption

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.