[RELEASE] Apache Doris MCP Server 1.0.0 Release

[FreeOnePlus]

Apache Doris MCP Server 1.0.0

Release date: 2026-08-01
Release manager: @FreeOnePlus (Yijia Su)
Release tag: 1.0.0
Protocol baseline: MCP 2026-07-28
Minimum Doris version: 2.0.0

Executive summary

Apache Doris MCP Server 1.0.0 establishes the project's first versioned public
contract for exposing Apache Doris capabilities to MCP Hosts and AI agents.
The release replaces the pre-1.0 collection of unrelated top-level tools with
one capability-aware, read-only architecture built around:

• eight stable top-level Doris domains;
• fifty-five exact child capabilities;
• progressive discovery with bounded manifests;
• runtime Doris version, feature, provider, and permission evidence;
• deterministic schemas, authorization identifiers, and error envelopes;
• MCP 2026-07-28 over Streamable HTTP and stdio;
• fail-closed query, transport, authentication, and capability boundaries.

The MCP protocol contract is generally available. The Python package retains
its Beta deployment classifier because Doris-backed OAuth state is currently
process-local and several distributed deployment shapes remain deliberately
constrained.

Why 1.0 changes the architecture

Earlier releases exposed many independent tools directly to the Host. That
model becomes increasingly expensive and unstable as Doris adds catalog,
query, observability, ingestion, search, governance, lakehouse, and semantic
capabilities. A large flat tools/list consumes model context, makes tool
selection harder, and cannot accurately represent differences between Doris
versions, deployment modes, providers, or user permissions.

Version 1.0 therefore defines a stable two-level contract:

1. The Host registers a small, deterministic set of domain tools.
2. Calling a domain with an empty object progressively discloses its currently
   authorized child capabilities, exact schemas, and runtime availability.
3. The Host calls the same domain with the selected child_tool, exact
   arguments, and optional manifest_version.
4. The Server revalidates authorization, availability, manifest generation,
   arguments, and output before returning a bounded result.

Tool selection remains deterministic: the Server does not use probabilistic
intent classification to hide or guess tools. The model sees the complete
domain map at the top level and receives the complete authorized child map for
the chosen domain on discovery.

Product and component architecture

flowchart LR
    H["MCP Host / AI Agent"]
    T["stdio or Streamable HTTP"]
    S["Transport security and authentication"]
    P["MCP 2026-07-28 protocol layer"]
    D["Domain manifest and dispatcher"]
    C["Route-aware capability detector"]
    R["Read-only domain runtimes"]
    A["Authorization and query guard"]
    M["Connection and route manager"]
    DB["Apache Doris FE / BE / metadata APIs"]
    O["Optional providers: Ossie, MetricFlow, lineage, ADBC"]

    H --> T --> S --> P --> D
    D --> C
    D --> A --> R --> M --> DB
    C --> M
    O --> C
    O --> R

Loading

The implementation keeps the following responsibilities separate:

• Host: registers the public tools, chooses a domain, consumes the child
  manifest, submits exact arguments, and rediscoveries after a stale-manifest
  response.
• Transport and protocol: normalize stdio and Streamable HTTP onto the same
  low-level MCP SDK v2 server, enforce MCP schemas, paginate list operations,
  and sanitize protocol errors.
• Security: establish the request identity, validate tokens or OAuth
  credentials, map exact scopes, enforce Host/Origin/proxy rules, and preserve
  Doris as the final data authorization boundary.
• Domain control plane: expose the stable top-level catalog, filter child
  discovery and execution by exact authorization, resolve availability, and
  dispatch one exact child.
• Capability plane: probe the connected Doris route, normalize its
  three-part version, inspect runtime features/providers, and create a bounded
  capability snapshot.
• Execution plane: validate identifiers and read-only SQL, execute bounded
  metadata/query/HTTP calls, normalize results, mask configured data, and
  classify failures.
• Apache Doris: remains the system of record for metadata, query execution,
  audit evidence, workload state, storage state, and row/column/data access
  permissions.

End-to-end request and data flow

1. Server initialization

1. Configuration is parsed and validated before the Server accepts traffic.
2. The security manager, connection manager, resources, tools, and prompts are
   initialized.
3. The same MCP server contract is bound to stdio or Streamable HTTP.
4. The tool exposure mode is fixed for the process lifetime. Changing it
   requires a Server restart and Host reconnect.

2. Top-level discovery

1. The Host sends tools/list.
2. The protocol layer authorizes the list operation and validates the complete
   tool catalog against bounded JSON Schema rules.
3. In the default hierarchical mode, the Server returns eight stable domain
   tools. Their short descriptions explain the domain coverage without
   repeating all child schemas.
4. List responses use signed, expiring cursors when pagination is required.

3. Domain discovery

1. The Host calls a domain with {}.
2. Exact discovery scopes filter the domain's children. An unauthorized child
   is not disclosed.
3. The capability detector resolves the current request route and probes only
   the necessary bounded evidence.
4. Doris version detection parses real values such as
   Doris version doris-3.0.3-rc03-43f06a5e26 (Cloud Mode) and reduces the
   capability key to 3.0.3; RC/GA labels, commit hashes, and deployment hints
   remain diagnostic evidence only.
5. Version ranges, SQL/HTTP probes, configured providers, deployment mode, and
   permission evidence are combined into an authoritative Availability
   object for each child.
6. The manifest returns the exact child name, description, input/output
   schemas, availability, reason code, and a deterministic
   manifest_version.
7. Discoverable but unavailable children remain visible with
   callable=false, so the Host can explain why an operation cannot currently
   run.

4. Child execution

1. The Host calls the same domain with child_tool, arguments, and the
   discovered manifest_version.
2. The dispatcher rechecks exact discovery and execution authorization.
3. A changed capability/provider/route generation produces
   CHILD_MANIFEST_STALE and directs the Host to rediscover.
4. A non-callable child produces CHILD_CAPABILITY_UNAVAILABLE with a stable
   reason code; the Server never attempts a speculative backend call.
5. Child arguments are validated against the disclosed schema.
6. The selected read-only runtime validates identifiers, SQL shape, parameter
   shape, row/byte/time limits, and provider requirements.
7. Doris executes with the request-specific route and credentials. Doris RBAC
   remains the final authorization decision for visible catalogs, objects,
   rows, columns, and functions.
8. Results are normalized into a deterministic envelope with request ID,
   duration, source, truncation state, warnings, and structured data.
9. Output Schema is validated before the response crosses the MCP boundary.

Public tool contract

Exposure modes

• hierarchical (default): exposes the eight stable domain tools below.
  Empty-object discovery returns the authorized child manifest.
• flat (compatibility fallback): exposes the same fifty-five children
  as collision-free names such as doris_query_execute_query. Flat mode is
  for Hosts that cannot perform progressive disclosure; it does not restore
  pre-1.0 names.

Both modes use the same catalog, availability rules, authorization policies,
schemas, dispatcher, runtimes, and result envelopes.

doris_catalog — 5 children

• list_catalogs — list internal and external catalogs.
• list_databases — list databases in an exact catalog.
• list_tables — list tables and views with bounded filtering/pagination.
• get_table_context — return composable basic, schema, comments, and
  indexes sections; the schema section is mandatory and optional sections
  report partial availability explicitly.
• get_table_size — inspect bounded partition/table size evidence.

doris_query — 7 children

• execute_query — run one bounded read-only SQL statement.
• explain_query — inspect a read-only query plan.
• get_query_profile — retrieve bounded query profile evidence.
• diagnose_query_performance — return deterministic performance findings.
• list_slow_queries — inspect bounded audit-backed slow-query evidence.
• get_adbc_connection_info — inspect ADBC/Flight SQL readiness without
  exposing secrets; requires explicit end-user ADBC intent.
• execute_adbc_query — run a bounded read-only query through the optional
  ADBC provider; requires explicit_adbc=true and never replaces ordinary
  execute_query.

doris_cluster — 11 children

• get_cluster_overview
• list_cluster_nodes
• list_active_tasks
• get_monitoring_metrics
• get_memory_stats
• get_cache_status
• get_compaction_status
• get_workload_group_status
• get_compute_group_status
• analyze_resource_growth
• get_runtime_capabilities

This domain unifies version-aware FE/BE metadata, system tables, HTTP evidence,
task views, workload groups, compute groups, cache, compaction, and the current
capability snapshot.

doris_pipeline — 5 children

• get_ingestion_status — inspect batch, stream, routine, and insert jobs.
• diagnose_ingestion — produce deterministic ingestion diagnostics.
• get_materialized_view_status — inspect MV jobs, tasks, and compute context.
• monitor_data_freshness — return bounded freshness evidence.
• analyze_data_dependencies — infer bounded runtime dependencies from audit
  evidence.

doris_search — 4 children

• search_data — execute bounded inverted, vector, or hybrid search when the
  connected Doris route supports it.
• preview_text_analysis — preview tokenizer/analyzer behavior.
• inspect_search_indexes — inspect inverted and ANN index metadata.
• diagnose_search_query — explain and diagnose a search query.

doris_governance — 8 children

• analyze_columns
• analyze_table_storage
• get_lineage_capability_status
• trace_column_lineage
• analyze_data_access_patterns
• get_recent_audit_logs
• list_udfs
• get_auth_mapping_status

Doris 4.0.6 and later may use a queryable native-lineage companion provider.
Before 4.0.6, bounded audit SQL inference is the primary lineage path. On
4.0.6 and later it becomes an explicit degraded fallback when the native
provider is absent or unavailable. Native delivery is asynchronous and best
effort, and every response reports the active evidence path.

doris_lakehouse — 3 children

• inspect_external_catalog
• inspect_lakehouse_table
• inspect_variant_column

The domain covers external catalog metadata, lakehouse lifecycle evidence, and
version-aware Variant inspection without pretending that every feature exists
on every Doris patch.

doris_semantic — 12 children

• list_semantic_models
• get_semantic_model_summary
• get_semantic_context
• get_semantic_mapping_status
• list_metricflow_models
• get_metricflow_status
• list_metricflow_metrics
• get_metricflow_group_bys
• list_metricflow_saved_queries
• get_metricflow_dimension_values
• compile_metricflow_query
• execute_metricflow_query

This optional, default-off domain is a read-only Apache Ossie consumer. It
requires explicit provider configuration and exact model_ref selection. The
Server does not infer a semantic model from the prompt and does not compile or
execute semantic expressions. Doris MCP Server remains an MCP execution and
grounding layer, not a semantic modeling repository.

MetricFlow remains the metric-semantic and compilation engine. The optional
sidecar loads exact model_ref values and compiles Doris SQL only. The Server
then applies its read-only SQL guard and executes through the request-specific
DorisQueryRuntime, preserving Doris routing, RBAC, limits, audit, redaction,
and result schemas. No native Doris MetricFlow/dbt adapter is bundled.

Capability detection and availability

Capability discovery combines independent evidence rather than relying on a
version string alone:

• normalized Doris major.minor.patch version and cluster version vector;
• deployment mode and mixed-version state;
• route-specific SQL metadata probes;
• bounded FE/BE HTTP probes;
• optional provider readiness and provider generation;
• exact request identity and Doris privilege visibility;
• configured feature flags and safety policy.

Snapshots are private to the resolved Doris route and are cached for a bounded
TTL. A bounded stale snapshot may be used only under the configured stale
policy; otherwise detection fails closed. Route or provider changes alter the
manifest generation so a Host cannot unknowingly execute against an obsolete
capability description.

Availability is structured and authoritative. Human-readable descriptions may
include a dynamic status prefix, but callers must rely on fields such as
status, callable, reason_code, version evidence, and provider evidence.

MCP protocol and transport contract

• MCP 2026-07-28 is the modern protocol baseline.
• Streamable HTTP and stdio share one low-level SDK v2 Server contract.
• Streamable HTTP uses stateless request handling.
• The isolated 2025-11-25 HTTP migration adapter is default-off at
  /mcp/legacy and never restores pre-1.0 tool names.
• Resources, tools, and prompts list operations are bounded and paginated.
• Pagination and explicit state handles are signed, scoped, and expiring.
• Tool input and structured output schemas are compiled and validated.
• Trace context is propagated only after sanitization and remains bounded.
• Subscription/change-event capabilities are not advertised without a real
  change-event source.
• Product name and version identity are deterministic across transports.

Security and permission model

Authentication modes

The Server supports separately configured boundaries for:

• static bearer tokens;
• JWT validation;
• external OAuth 2.0/OIDC access-token validation;
• Doris-backed OAuth for request-specific Doris user credentials;
• unauthenticated local development only when explicitly configured.

External OAuth and Doris-backed OAuth cannot be enabled together. Doris-backed
OAuth requires HTTP transport and a single worker in 1.0 because authorization
codes, access tokens, and user connection state are process-local.

Layered authorization

1. Transport access: bind-address, Host, Origin, proxy, and TLS policy.
2. MCP operation scope: exact authorization for list/read/call operations.
3. Domain discovery scope: exact domain and child discovery grants.
4. Child execution scope: exact child:call:<domain>:<child> grants.
5. Provider allowlist: Doris OAuth and custom providers expose only
   reviewed capabilities.
6. Doris RBAC: the selected Doris identity remains the final data plane
   authority.

Discovery permission never implies execution permission. Unauthorized child
names are returned as not found rather than leaking the presence of hidden
capabilities.

Query and data safety

• The built-in 1.0 catalog is read-only.
• doris_admin is reserved but is not registered.
• SQL parsing accepts one read-only query shape and rejects write/management
  operations, stacked statements, unsafe identifiers, and invalid parameters.
• Query timeout, row count, result bytes, input lengths, collection sizes, and
  diagnostic depth are bounded.
• Configured sensitive data masking is applied before results leave the
  Server.
• Secrets, credentials, tokens, connection strings, and backend errors are
  redacted from logs and MCP error payloads.
• Custom tool providers are explicit, installed, and allowlisted; they are not
  silently merged into the built-in 8/55 contract.
• ADBC is default-off, requires explicit user intent, and fails closed on
  token-bound routes because the current Flight client is process-global.

Reliability and operational behavior

• Fail-closed initialization: invalid authentication, proxy, secret, or
  provider configuration prevents unsafe startup.
• Route-aware connection management: global, static-token, and Doris OAuth
  user routes have explicit priority and isolated pool lifecycle.
• Multi-FE support: configured FE candidates can fail over while preserving
  request routing evidence.
• Readiness separation: liveness reports process health; readiness reflects
  whether the Server can safely serve Doris-backed operations.
• Deterministic errors: domain errors distinguish invalid arguments,
  unavailable capabilities, stale manifests, timeouts, execution failures, and
  authorization failures, including explicit retryability.
• Bounded fallback: native features may use only documented fallback paths;
  the response reports degraded operation instead of presenting fallback
  evidence as native.
• Result integrity: successful child outputs must satisfy the declared JSON
  Schema before they cross the protocol boundary.
• Auditability: calls carry request IDs, durations, sources, truncation
  state, warnings, and sanitized trace context.
• Stable registration: changing from a catalog question to a cluster
  question requires calling another already registered domain, not dynamically
  re-registering MCP tools.

Doris compatibility and certification

The project minimum is Doris 2.0.0. The 1.0 target patch set is:

• 2.0.15
• 2.1.11
• 3.0.3
• 3.1.4
• 4.0.5
• 4.0.6
• 4.0.7
• 4.1.0
• 4.1.1
• 4.1.2
• 4.1.3

Only normalized three-part versions participate in capability ranges and
certification. RC/GA suffixes do not create separate capability buckets.

Doris 4.0.5 is the first evidence-backed certified target. Other target
patches remain target_uncertified until they pass the same real-cluster gate.
An uncertified target is not automatically unusable: runtime capability
discovery remains authoritative for the connected cluster.

Breaking changes from pre-1.0 releases

• Pre-1.0 direct tool names are removed without an alias window.
• Hierarchical exposure is the default.
• Flat mode uses formal names such as doris_query_execute_query.
• Exact domain/child scope identifiers replace legacy wildcard guesses.
• get_table_context consolidates five pre-1.0 table metadata calls into four
  explicit sections.
• ADBC is part of the query domain rather than a separate top-level domain.
• ADBC requires explicit end-user intent and explicit_adbc=true.
• Semantic calls require an explicit model_ref.
• Semantic includes both Ossie grounding and MetricFlow consumption.
• Hosts must rediscover after CHILD_MANIFEST_STALE.
• The legacy HTTP adapter is isolated, default-off, and does not restore the
  old tool surface.

See the 1.0 migration guide
and the generated 8/55 tool registry.

Verification and release gates

The 1.0 contract is protected by:

• warnings-as-errors unit, security, integration, and deployment tests;
• domain-specific coverage floors;
• Ruff, Mypy, Bandit, and lock-file validation;
• source distribution, wheel build, and clean-wheel installation;
• official MCP 2026-07-28 stateless conformance;
• stdio and Streamable HTTP contract tests;
• hierarchical and flat exposure tests;
• cross-process 8-domain/55-child stability tests;
• real Apache Doris read-only regression tests;
• package and generated-catalog drift checks.

The release tag was prepared in #187.
Post-tag #188 migrated the
real Doris regression suite to the 1.0 hierarchical/flat contract before the
later public 8/55 semantic expansion.

The 2026-08-01 acceptance snapshot for the expanded contract is:

• 1772 passed, 83 skipped with warnings treated as errors and 67.73%
  aggregate coverage;
• Protocol 90.34%, Authentication 81.55%, and Core Managers 87.03%
  domain coverage;
• 26 passed against a live Doris 4.0.5-rc01 cluster over stdio and
  Streamable HTTP, including hierarchical and flat exposure;
• all eight MetricFlow children exercised through a bounded provider-contract
  sidecar, with compiled read-only SQL executed by the standard Query runtime
  against real Doris;
• lock, generated catalog, Ruff, Mypy, Bandit, source distribution, wheel,
  clean-wheel import, CLI, and runtime-dependency checks passing.

The MetricFlow acceptance proves the MCP provider protocol and real Doris
execution boundary. It does not claim that the project bundles a native Doris
MetricFlow/dbt adapter.

Documentation system work

The root README files will become concise, bilingual entry points. Detailed
material will be maintained under docs/ in paired English and Simplified
Chinese documents covering:

• getting started and Host connection;
• architecture and end-to-end data flow;
• tool domains and progressive disclosure;
• MCP protocol behavior;
• authentication, authorization, and query safety;
• deployment, reliability, and troubleshooting;
• configuration reference and integrations;
• migration, release notes, and contributor workflows.

This issue remains the detailed 1.0 release record. The documentation pull
request will be linked here when it is available.

Known limitations

• doris_admin is reserved and unavailable in 1.0.
• Doris-backed OAuth is process-local and supports one worker only.
• ADBC is default-off, explicit-only, and unavailable on token-bound request routes.
• Ossie integration is optional, read-only grounding; it neither authors models
  nor executes semantic expressions.
• MetricFlow requires an operator-supplied Doris-capable compiler provider and
  cannot bypass MCP-governed query execution.
• Native lineage requires a queryable companion provider and is asynchronous,
  best effort.
• Audit-derived lineage is bounded inference, not proof of complete lineage.
• Runtime support and release certification are distinct; only 4.0.5 is
  certified at this release boundary.

Contributors

Thanks to everyone who contributed code, review, testing, issue reports, and
release validation for the 1.0 line, including:

• @FreeOnePlus
• @maktala
• @mortalBibo
• @catpineapple
• @heroyin
• @dependabot

Related implementation pull requests

The 1.0 architecture was delivered incrementally in
#141 through
#188, including bounded
MCP lists and schemas, explicit state handles, OAuth scope hardening, trace
propagation, route-aware connections, version/capability detection, the domain
catalog and dispatcher, all eight domain runtimes, Host budgets, patch
certification, release preparation, and real Doris validation.

[FreeOnePlus]

1.0.0 release candidate published

The final 1.0.0 tag resolves to
953c3b6c5bbabb297f3ca625a42912c93dc06471. The final release gate was merged
in #192 and the source release candidate is now available at:

https://dist.apache.org/repos/dist/dev/doris/doris-mcp/1.0.0/

The PyPI package is available at:

https://pypi.org/project/doris-mcp-server/1.0.0/

Candidate verification from the public dist/dev files completed successfully:

• SHA-512:
  eebdd7cf9b8dfc4708a018e52846120ce22a9f054175e1b95ddc5698ea893711952f8647b395cd678fc4625ba1081913f2dfc3208ed9c26eb6399489c87b9758
• signing fingerprint:
  7FEFE220E7BF139DEE6C25F76ED9EEB123B47037
• full tagged-source suite: 1772 passed, 83 skipped, 67.73% coverage;
• live Doris 4.0.5-rc01 suite: 26 passed over stdio and Streamable HTTP;
• source, wheel, Twine, clean-install, CLI, runtime dependency, Ruff, Mypy,
  Bandit, lock, generated catalog, and Apache license gates passed.

This issue remains open while the Apache vote and formal release process are
in progress. The GitHub Release is intentionally kept as a draft until the
vote succeeds.