Migrating to 1.0.0

August 1, 2026 · View on GitHub

Version 1.0 intentionally removes the pre-1.0 direct tool surface. There is no alias window. Plan the Server upgrade together with Host schema cache, authorization scopes, protocol revision, and deployment configuration.

The compatibility path docs/migration-1.0.0.md remains packaged with the sdist. This topic guide is the expanded operational version.

Preflight inventory

Record before the upgrade:

current package and MCP protocol revisions;
transport and endpoint;
every old tool name used by prompts/agents/code;
Host support for progressive disclosure;
static/JWT/OAuth/Doris OAuth mode and scopes;
Doris route/account/patch and required FE/BE HTTP access;
ADBC, lineage, Ossie, MetricFlow, or custom provider dependencies;
result/time/concurrency limits;
rollback package and configuration.

Do not upgrade the Server while leaving a Host with cached pre-1.0 schemas.

Breaking contract changes

Pre-1.0 top-level tools are not registered or callable.
Default exposure becomes eight hierarchical domains.
Flat fallback uses formal names such as doris_query_execute_query.
Exact child discovery and execution scopes replace old/wildcard scopes.
Runtime availability and manifest_version enter the call contract.
Five table metadata calls become sections of get_table_context.
ADBC moves into doris_query.
ADBC becomes default-off and requires explicit user intent plus explicit_adbc=true; ordinary SQL stays on execute_query.
Semantic model-specific calls require exact model_ref.
doris_semantic adds eight MetricFlow consumer children while keeping MetricFlow compilation separate from MCP-governed Doris execution.
Modern HTTP uses stateless MCP 2026-07-28 at /mcp.
/mcp/legacy is default-off and does not restore tool names.
doris_admin remains unavailable.

Choose exposure mode

Preferred:

export MCP_TOOL_EXPOSURE_MODE=hierarchical

The Host registers:

doris_catalog
doris_query
doris_cluster
doris_pipeline
doris_search
doris_governance
doris_lakehouse
doris_semantic

It calls a selected domain with {}, then calls the same tool with exact child_tool, arguments, and current manifest_version.

If the Host cannot perform this two-step flow:

export MCP_TOOL_EXPOSURE_MODE=flat

Restart the Server and reconnect the Host. Flat mode carries a larger context surface and still requires formal 1.0 names.

Common tool mappings

Pre-1.0	Hierarchical 1.0	Flat 1.0
`exec_query`	`doris_query.execute_query`	`doris_query_execute_query`
`get_db_list`	`doris_catalog.list_databases`	`doris_catalog_list_databases`
`get_db_table_list`	`doris_catalog.list_tables`	`doris_catalog_list_tables`
`get_catalog_list`	`doris_catalog.list_catalogs`	`doris_catalog_list_catalogs`
`get_sql_explain`	`doris_query.explain_query`	`doris_query_explain_query`
`get_sql_profile`	`doris_query.get_query_profile`	`doris_query_get_query_profile`
`exec_adbc_query`	`doris_query.execute_adbc_query`	`doris_query_execute_adbc_query`
`get_adbc_connection_info`	`doris_query.get_adbc_connection_info`	`doris_query_get_adbc_connection_info`
`analyze_data_flow_dependencies`	`doris_pipeline.analyze_data_dependencies`	`doris_pipeline_analyze_data_dependencies`

Use the generated tool registry for the full 25-entry migration input map. The map documents handler reuse; it does not create aliases.

Table context consolidation

Old call	`get_table_context` section
`get_table_basic_info`	`basic`
`get_table_schema`	`schema`
`get_table_comment`	`comments.table`
`get_table_column_comments`	`comments.columns`
`get_table_indexes`	`indexes`

schema is required. Optional sections return independent status/source/ warnings, so update consumers that previously expected one unqualified success object.

Host changes

Remove cached tool definitions and old prompt-injected signatures.
Restart/reconnect after selecting exposure mode.
Call tools/list and register only the returned contract.
In hierarchical mode, implement empty-object discovery.
Use exact returned child schemas; do not construct arguments from memory.
Preserve and send manifest_version when supported.
Rediscover on CHILD_MANIFEST_STALE.
Treat callable=false and reason code as an operator state.
Preserve structured result metadata, warnings, and truncation.
Stop parsing raw backend error strings.

Authorization migration

Replace legacy tool scopes with exact domain and child scope identifiers.
Separate discovery from execution grants.
Enable optional semantic/Doris OAuth channels explicitly.
Use exact domain.child allowlists for Doris OAuth.
Retest negative scopes and Doris RBAC with the actual request identity.
Do not grant a broad Doris service account to compensate for missing MCP scopes.

OAuth manifests can differ per user. A manifest/cursor discovered by one principal cannot be reused by another.

Protocol migration

For HTTP 2026-07-28:

send one self-contained JSON-RPC request per POST /mcp;
include protocol version, client capabilities, and client identity in _meta;
include required MCP-Protocol-Version, Mcp-Method, and named-call Mcp-Name headers;
remove initialize, notifications/initialized, Mcp-Session-Id, sticky sessions, HTTP GET stream, Last-Event-ID, and resumable SSE assumptions;
accept modern structured content and typed errors.

For a bounded legacy HTTP migration, enable the adapter and point only the old client to /mcp/legacy. The regression-tested HTTP profiles are 2025-06-18 (including Dify 1.16.1) and 2025-11-25. Do not point legacy traffic at /mcp; the adapter preserves the 1.0 tool and security contracts and is not a pre-1.0 compatibility alias.

Doris version and capability migration

Minimum supported Doris version is 2.0.0.
Capability decisions use only normalized major.minor.patch.
RC/GA suffixes, commit hashes, and deployment hints are diagnostic only.
Runtime probes/providers/permissions remain required even when a version range matches.
Doris 4.0.6+ native lineage requires a healthy queryable provider/store; audit inference remains primary before 4.0.6 and degraded fallback after.
Certification and runtime support are separate; do not hard-code target_uncertified as unusable.
ADBC is unavailable on 2.0, version-eligible on 2.1+, and degraded on 2.1.0-2.1.4 before provider and live endpoint probes are considered.
Variant inspection starts at 2.1; ANN/vector/hybrid search starts at 4.0; newer facets remain independently gated.

Configuration migration

Use MCP_TOOL_EXPOSURE_MODE; do not configure old tool buckets.
Keep ENABLE_LEGACY_HTTP_ADAPTER=false after client migration.
Configure one shared MCP_STATE_HANDLE_SECRET for independent replicas.
Keep MCP_ADMIN_DOMAIN_ENABLED=false.
Validate non-loopback authentication and Host/Origin policy.
Doris OAuth requires HTTP, WORKERS=1, and no external OAuth.
Use explicit optional-provider paths and bounds.
Review row, byte, timeout, concurrency, and query-security limits.

Staged rollout

Deploy 1.0 in an isolated environment with the target Doris account.
Verify /live and /ready.
Run Host server/discover, tools/list, all domain discovery, and a formal read-only Query child.
Verify catalog-to-cluster intent switching in one conversation.
Run negative write, scope, Doris permission, stale-manifest, cursor, timeout, row, and byte tests.
Validate optional providers and degraded paths.
Migrate one Host profile and monitor typed errors.
Remove legacy endpoint use, then disable the adapter.
Roll out remaining Hosts and delete old schema caches/config.

Rollback

Roll back Server package/image and matching configuration together.
Restart and rediscover every Host.
Do not reuse 1.0 manifests/cursors against a pre-1.0 process.
Restore old prompts/scopes only if the old Server is actually restored.
Capture why the gate failed; do not permanently run mixed old/new tool names.