DATAFOCUS · OT FLASH · R56

OT Flash Agent and MCP Integration Manual

Protocol, Authorization, Tool Contracts, and the Complete Call Flow

Build traceable data and knowledge applications with the public Remote MCP of OT Flash r56. This manual covers OAuth, protocol messages, parameter references for all declared tools, evidence rules, conditional capabilities, and recovery procedures, and provides runnable client examples and synthetic data samples.

Agent developers, integration engineers, and administrators

The accompanying samples keep their Chinese display field names. Translating the interface language and explanatory text does not change actual table names, column names, enum values, tool names, or protocol fields.

Chapter 1

Agent integration scope and completion criteria

Choose an authorization entry point and complete queries, evidence retrieval, or controlled writes based on server receipts.

OT Flash r56 provides external Agents with data and knowledge capabilities within ontology scope through Remote MCP, plus an independent Business Workspace entry point. An Agent should determine executable work based on the actual tools/list, inputSchema, OAuth scope, and current resource permissions, and must not infer from this static manual that a deployment has enabled all optional features.

Figure A1: External Agents use native query, knowledge, and business capabilities through OAuth and MCP. Interface relationship diagram.
EntryPurposeBoundary
/mcpOntologies, data tables, document knowledge, native Search, and conditionally available analysis and modelingIntersection of the current user's permissions and the resources covered by this authorization
/mcp/businessBusiness system discovery, queries, action plans, status, and executionSeparate business system authorization and published contracts
Embedded ontology agent pageOntology chat in the human user interfaceRequires a real logged-in session; it is not a login-free MCP token exchange entry point

Capability categories

  • Basic reads: ontology and resources, graph location, knowledge retrieval with full source text, authorized table details, and Doris SQL.
  • Separate delegation: dfc_search requires search:operate and remains bound by the original user's permissions and the model permissions.
  • Conditionally available: analysis, persistent reports, artifact drafts and their application, ontology model queries, and delegated Agent tasks.
  • Unavailable capabilities: Flash's dfc_etl only reports capabilities and does not run Heavy ETL. AutoML and internal FocusCode workspace entry points are not part of the public Flash API in this manual.

Completion criteria

A factual read must obtain an actually usable query receipt or full source-text receipt; a generated candidate must be reported as not yet applied; a publish must have a real APPLIED receipt; a cancellation must distinguish between requested and confirmed. Answer text, an HTTP 200, a tool's acknowledgment of receipt, or a model saying “completed” cannot by itself prove that a business operation succeeded.

The accompanying reference/mcp-tool-catalog.json is an offline declaration reference for r56. It includes conditionally enabled definitions and is not any user's live tools/list. The full catalog contains 28 ontology core tools, 4 conditional controller extensions, and 8 business-side tools; this does not mean they are all enabled by default.

Chapter 2

Quick connection and capability discovery

Start with the instance's official domain and discover actually available tools with least privilege.

  1. Get the official HTTPS root address from your administrator, along with the ontology or business system you need to access. Do not use the example domains in this documentation to call real business systems.
  2. Configure the MCP server address as https://flash.example.com/mcp; the Business Workspace uses /mcp/business on the same domain.
  3. Trigger OAuth login and authorization as supported by the client and verify resources and scope; do not submit usernames and passwords to MCP.
  4. Use protocol discovery or initialization appropriate to the protocol era, then read tools/list and resource descriptions.
  5. First make a small read-only request to verify structured results and error handling, then execute the user's goal.

Client configuration snippet

json
{
  "mcpServers": {
    "ot-flash": {
      "url": "https://flash.example.com/mcp"
    }
  }
}

This snippet illustrates the intent of the server address configuration; the actual configuration file structure and OAuth support depend on the client. Do not put real access_token or refresh_token values, cookies, or administrator passwords in public files.

Modern protocol discovery

http
POST /mcp HTTP/1.1
Host: flash.example.com
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: server/discover

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "server/discover",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {"name": "flash-client", "version": "1.0.0"},
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

Pre-integration checks

  • The resource root address, OAuth issuer, and reverse proxy external address are consistent.
  • The client supports the corresponding protocol era instead of always sending initialize to a new-protocol endpoint.
  • The current authorization is bound to the required ontology or business system.
  • The token is valid, and new optional scopes have been explicitly granted.
Chapter 3

OAuth discovery, registration, and authorization

Use the authorization code flow with PKCE; do not expose product login credentials to the Agent.

Figure A2: OAuth authorization code and PKCE flow. Sequence diagram.
EndpointMethodPurpose
/.well-known/oauth-protected-resourceGETOntology MCP resource discovery
/.well-known/oauth-protected-resource/mcpGETOntology resource path compatibility discovery
/.well-known/oauth-protected-resource/mcp/businessGETBusiness MCP resource discovery
/.well-known/oauth-authorization-serverGETAuthorization server metadata
/oauth/registerPOST JSONDynamic registration of a public client
/oauth/authorizeGET or POST formLog in, select resources, and confirm authorization
/oauth/tokenPOST formAuthorization code exchange and refresh rotation
/oauth/revokePOST formToken revocation
/oauth/grantsGETView authorized connections (logged-in users)
/oauth/grants/revokePOST formRevoke a connection through the original page flow

Authorization sequence

  1. Read the protected resource metadata and authorization server metadata. A request without a token returns 401, and its WWW-Authenticate header points to the resource discovery address.
  2. Register or use a client identity. In r56, a dynamically registered public client uses token_endpoint_auth_method=none; a client secret cannot substitute for PKCE.
  3. Generate a random state and code_verifier, and compute the S256 code_challenge.
  4. Open the authorize address indicated by the metadata, passing response_type=code, client_id, the exact redirect_uri, scope, resource, state, code_challenge, and code_challenge_method=S256.
  5. The user logs in to DataFocus and selects the ontology or business system. The client cannot pre-select resources the user is not authorized to access.
  6. Receive the callback and verify state and issuer, then exchange the authorization code using the original code_verifier.
  7. Use the access_token only for MCP Bearer authentication. Refresh using the original OAuth flow and securely store the rotated refresh_token.

Registration example

json
{
  "client_name": "OT Flash Knowledge Client",
  "redirect_uris": ["http://127.0.0.1:8765/callback"],
  "application_type": "native",
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}

Web client callbacks use HTTPS; native clients may use supported loopback addresses. Both authorization and token exchange require an exact match with the registered callback. One Grant targets one protected resource; do not mix ontology scopes and Business Workspace scopes in the same connection.

Token lifecycle

By default, the r56 server issues access tokens valid for 3600 seconds, refresh tokens for 2592000 seconds, and authorization codes for 300 seconds; deployments may override these values. Clients must rely on expires_in in the token response and on actual errors, and must not hard-code the defaults. Update tokens after a refresh; revoking a role, a resource permission, or the Grant causes subsequent calls to be rejected.

Chapter 4

Scope, resource boundaries, and real-time permissions

Authorization scopes delegate existing permissions; they do not elevate roles or share business state across Grants.

ScopeTypical capabilitiesImportant constraints
ontology.metadata:readOntologies, resources, and table structuresOntologies and tables must be within the authorized and currently readable scope
ontology.graph:readGraph search and neighborsReturns locator information, not factual evidence
ontology.knowledge:readKnowledge location and full source textOriginal knowledge base and document permissions still apply
ontology.table:queryOntology table SQL and published model queriesTable queries also require the metadata scope; actual source and column permissions remain in effect
search:operateNative keyword models and sessionsSeparate, explicit delegation; runs under the original model and the user's table and column permissions
etl:operateFlash ETL capabilitiesHeavy ETL is not exposed
authoring.contract:readConditionally available modeling contractsAlso requires the feature switch and the related resources
authoring.artifact:readReads of candidates, plans, and similar items under the current authorizationBound to the original principal, Grant, and resources
authoring.artifact:draftCandidate submission, preview, etc.Does not authorize execution or publication
authoring.artifact:applyControlled plans and applyStill requires the original business role, policy, and approval
execution.script:draftSpecific script draftsDoes not authorize actual script execution
datasource.http:read / draft / test / importConditionally available HTTP data source artifact capabilitiesEach has its own switch; original permissions still apply
Figure A3: User permissions, Grants, selected resources, and feature configuration jointly determine available capabilities. Diagram.

Scope combinations for reads

dfc_table detail requires ontology.metadata:read; query additionally requires ontology.table:query. dfc_ontology_query requires both the graph and knowledge read scopes. dfc_knowledge_search/detail requires knowledge. published_model/published_query uses table:query; candidate_query additionally requires authoring.artifact:read. Analysis tools also check the allowed evidence scopes; persistent reports require metadata and table query.

Do not hard-code the default authorization

The ontology default scope set for r56 includes table query; Search and ETL require explicit delegation. The discovery metadata, the authorization page, the actual token scope, and tools/list remain authoritative. Statements in older documents such as “the ontology default never includes SQL” or “only six tools” must not be relied on for the current implementation.

State isolation

Sessions, reports, candidates, and action plans each have their own owner and scope. Refreshing an access token does not transfer one Grant's work to another Grant. Do not merge sessionId, reportId, planId, approval tokens, or source tokens returned by another connection into the current connection.

Chapter 5

HTTP and modern MCP messages

Correctly send per-request metadata and matching route headers, and handle HTTP and tool results separately.

Itemr56 behavior
TransportStateless Streamable HTTP, POST JSON-RPC
Supported version identifiers2026-07-28, plus 2025-11-25, 2025-06-18, and 2025-03-26
Modern methodsserver/discover, tools/list, tools/call, resources/list, resources/read, enabled according to actual capabilities
Session headerNo Mcp-Session-Id is assigned
GET and DELETE/mcp and /mcp/business return 405
Server SSE notificationsNot provided on these two public MCP entry points
Catalog cacheModern discovery and list responses return ttlMs=60000 and cacheScope=private
Normal resultsModern results include resultType=complete and service identity metadata

Content that must match

  • MCP-Protocol-Version matches io.modelcontextprotocol/protocolVersion in params._meta.
  • Mcp-Method matches the JSON-RPC method.
  • For tools/call, Mcp-Name matches params.name; for resources/read, the name header matches the URI.
  • Every modern request carries the io.modelcontextprotocol/clientCapabilities object and also provides the standard clientInfo to identify the client.

Call examples

json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "dfc_ontologies",
    "arguments": {"page": 1, "pageSize": 20},
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {"name": "flash-client", "version": "1.0.0"},
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

The corresponding HTTP headers are Mcp-Method: tools/call and Mcp-Name: dfc_ontologies. In all examples, ACCESS_TOKEN is a placeholder. Do not put the bearer token in URLs, JSON parameters, or cache keys.

Reading results

Process the HTTP status first, then check the JSON-RPC error; when a result is present, also check isError. Successful tool results usually provide structuredContent along with text content containing the same business JSON; read the structured channel first and do not count text and structuredContent as two independent facts. An HTTP 200 response may still carry a tool failure.

Public resources and UI

The built-in instructions resource does not depend on MCP Apps. This does not give the Business Workspace entry point the ontology instructions resources. Clients that support visualization should discover the corresponding UI through actual capabilities and tool _meta, and must not guess resource URIs that were not returned.

Chapter 6

Legacy protocol client compatibility

Keep a consistent protocol era in clients that still use the initialization handshake.

json
{
  "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "flash-legacy-client", "version": "1.0.0"}
  }
}
  1. Send initialize and read the protocol version and capabilities negotiated by the server.
  2. Send the initialization-complete notification required by the client's protocol; a notification has no normal tool result.
  3. Use tools/list to read the currently authorized tools, then send tools/call.
  4. Keep headers and payloads consistent with the current request era; do not send legacy initialize or ping flows in 2026-07-28 payloads.

The legacy protocol still uses the same Bearer/OAuth, permissions, and tool contracts. This does not mean the server necessarily offers long-lived legacy SSE connections or Mcp-Session-Id; r56's public services remain stateless.

Protocol errors

SituationTypical resultResolution
Inconsistent modern headers and payloadHTTP 400 JSON-RPC -32020Correct the headers, metadata, and tool name
Unsupported version-32022 with a list of supported versionsChoose a protocol version that is actually supported
Unknown methodJSON-RPC -32601; modern requests may get HTTP 404Check the protocol era and method
Missing or invalid parametersJSON-RPC parameter error or tool isErrorCorrect according to the actual inputSchema
Chapter 7

Choosing the right tool and evidence channel

Route by the business question that is still unresolved; do not repeat evidence gathering through a fixed call chain.

Figure A4: Choosing table SQL, knowledge evidence, Search, analysis, or business actions by task. Routing diagram.
TaskPreferred toolEvidence required for completion
Discover authorized subjects and resourcesdfc_ontologies dfc_ontology_resourcesActual resource ID types and current visibility scope
Table statistics and TopNdfc_table querySuccessful execution receipt and the full evidenceRows
Look up policies, contracts, or reportsdfc_ontology_query or knowledge search/detailComplete, authorized source text that can be used as facts
Locate graph objectsdfc_ontology_graph search/neighborsLocate the actual source first, then obtain the corresponding facts
Native keyword interactiondfc_manual then dfc_searchActual results in the original model and business frames
Federated analysis and reportsdfc_analysis_* or dfc_report_*Actual status of each structured branch and of the document evidence
Modify presentation or the ontology modeldfc_authoring_* and artifact toolsVerify candidates, plans, approvals, and applied changes separately
Execute business commandsdfb_* on /mcp/businessPublished contracts and the original ActionPlan receipt

Avoiding unnecessary calls

When you already have a current, complete, authorized table structure, there is no need to call detail again for every query; when you already have trusted locators and evidence, do not repeat the same retrieval. When a missing dimension is needed, perform a bounded supplementary lookup. When a failure is clearly not retryable, resolve the gap first; do not substitute “try again” for judgment.

Exclusions in Flash

dfc_etl capabilities may return available=false and ETL_NOT_INCLUDED_IN_OT_FLASH. The static description of the built-in ETL function is for cross-product reference; it does not prove that Flash has ETL installed, nor does it allow the Agent to automatically switch to Heavy or another tenant for execution.

Chapter 8

Ontology resources and ID types

Obtain the actual resource coordinates first to prevent conflating storage names, document IDs, and knowledge base IDs.

  1. Call dfc_ontologies and page through the ontologies covered by this authorization that are still readable, using page and pageSize.
  2. Call dfc_ontology_resources with the real ontologyId; select tables, answers, pinboards, documents, and knowledgeBindings as needed.
  3. Handle pagination separately for each resource type. pageSize has a maximum of 100; do not infer the full resource scope from the first page.
  4. Save the type and original ID declared by the resource and use them verbatim in subsequent calls.
json
{"name":"dfc_ontology_resources","arguments":{
  "ontologyId":"<ONTOLOGY_ID>",
  "resourceTypes":["tables","documents","knowledgeBindings"],
  "page":1,"pageSize":100
}}
CoordinateSourceCannot be replaced by
ontologyIdAuthorized ontology list or current valid contextAnother ontology's ID
Table resource idtables list or trusted contextphysicalName or displayed table name
tblDisplayName colDisplayNameCurrent table and column metadataA guessed physical SQL identifier
knowledgeIdknowledgeBindings or an actual knowledge retrieval receiptDocument resource id
assetId documentId chunkId evidenceIdThe same actual locator receiptFields stitched together from different locator results
rid revisionId releaseIdPublished model or server-side candidate contextAn ID you generate yourself, or latest

Precision conventions

Prefer decimal strings for all 64-bit resource identifiers, and do not convert them with Number in JavaScript. Some business schemas accept either string or integer, but that does not mean integer precision may be lost. Opaque locators, UUIDs, hashes, and one-time tokens must also be saved as-is.

Chapter 9

Doris table query and structure contract

Execute read-only SQL on authorized tables while preserving output semantics, exact values, and completeness.

Reading the table structure

json
{"name":"dfc_table","arguments":{
  "action":"detail","ontologyId":"<ONTOLOGY_ID>","id":"<TABLE_RESOURCE_ID>"
}}

Use the real table resource ID for detail. Verify schemaComplete, tblDisplayName, the colDisplayName in columns and the authoritative sqlDataType, as well as the returned queryContract. dataType is only a compatibility mapping; the physical storage name is not the table name to submit in SQL.

Executing queries

json
{
  "name": "dfc_table",
  "arguments": {
    "action": "query",
    "ontologyId": "<ONTOLOGY_ID>",
    "sql": "SELECT \"区域\", SUM(\"销售金额\") AS \"销售金额合计\" FROM \"电商销售数据\" WHERE \"订单状态\" = '已完成' GROUP BY \"区域\" ORDER BY \"销售金额合计\" DESC",
    "maxRows": 100
  }
}

SQL constraints

  • Use the display names of tables and columns, and quote identifiers with double quotes. The request is a single read-only Doris query within the ontology scope.
  • List output columns explicitly. SELECT * and table.* are forbidden, so they cannot be used to bypass registered column permissions through physical columns.
  • Joins must use an explicit JOIN ... ON; NATURAL JOIN and JOIN USING will be rejected.
  • Valid multidimensional aggregation, CTEs, window functions, CASE, COUNT(DISTINCT ...), and other read-only expressions are allowed; if semantic validation does not cover an expression, that does not mean the expression is blocked from running.
  • Complete aggregation, sorting, and ranking in SQL first, then apply the result limit. maxRows defaults to 100, with a maximum of 200.

Dates and time zones

Type or targetFormNote
DATECAST('2026-09-01' AS DATE) and CURRENT_DATEDo not use a bare text literal and assume it is a date
DATETIMECAST('2026-09-01 00:00:00' AS DATETIME) and CURRENT_TIMESTAMPVerify the source time zone and the session time zone
Relative timeDATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR)Use the corresponding current function for dates and timestamps
Time groupingYEAR(column) or DATE_TRUNC(column, 'month')Use a unique alias for each output; follow queryContract

SQLite's DATE('now', ...) is not the Doris date contract for this entry point. Do not carry the SQLite-based offline checks from the documentation samples into live SQL.

Read the v8 query receipt

evidenceRows is the Agent's only channel to row data; raw data is not exposed to the Agent. SQL numbers are encoded as exact decimal JSON strings; determine their numeric and business types via resultColumnContracts, and do not interpret them as VARCHAR merely because the JSON value is a string. Read executionReceipt, completeness, and truncation information, and preserve source information such as evidenceRowsSha256.

Query outputs with a citable execution receipt may be quoted as-is; only server-verified semantics may authorize subsequent deterministic secondary computation. Do not guess “cumulative balance,” “period-end value,” or “currency” from field names, or add units on your own. Zero-row results, failures, or truncation must not be described as complete statistics.

Chapter 10

Multidimensional Top 3 and truncation handling

Answer rankings with server-side aggregation and window functions; do not perform secondary computation on incomplete results.

The accompanying examples/top3.sql uses the sample table: it first aggregates by 区域, 类别, and 产品, then runs ROW_NUMBER within each 区域 and 类别, using the 产品 name as a stable tiebreaker when amounts are tied. Requesting maxRows=100 is enough for the sample's 36 rows; for other business data, size the request by the actual number of groups.

  1. Obtain the real structure and the current business definition, and clarify currency, period, 订单状态, and tie-breaking rules.
  2. Submit server-side aggregation and ranking SQL. Do not query only the 区域 totals and then present them as the 产品 ranking within each 类别.
  3. Check the output column contract against the actual evidenceRows, and confirm that the returned data covers all required groups.
  4. When truncation is found, perform bounded partitioned queries using server-supported boundaries, for example retrieving the complete Top 3 separately by 区域; keep the same business definition each time.
  5. If the source changes in the meantime, re-query and state the new version explicitly; do not mix different data versions or stale cursors.
Figure A5: The sequence of detail filtering, grouped aggregation, in-group ranking, and final return. Diagram.

Error recovery

TABLE_SCHEMA_INCOMPLETE requires correcting the request or obtaining the complete structure; handle failures such as ONTOLOGY_SQL_FAILURE_CONTRACT_INVALID according to the returned errorCode, retryable, and remediation fields. Do not claim that “all multidimensional GROUP BY or window functions are forbidden,” and do not fabricate rankings when there are no query results.

Chapter 11

Knowledge retrieval: full source text and evidence eligibility

Separate locating, reading, and fact citation, and preserve provenance and completeness.

Two common paths

PathPurposeKey points
dfc_ontology_querySearch within ontology-bound knowledge, optionally combined with graph routingCheck the complete canonical answerContextItems and evidence eligibility
dfc_knowledge_search → dfc_knowledge_detail chunkLocate via explicit search, then read the selected chunkSearch previews are not facts; read the full source text for the same locator
json
{"name":"dfc_knowledge_search","arguments":{
  "ontologyId":"<ONTOLOGY_ID>","query":"销售金额是否排除退货", "topK":5
}}

{"name":"dfc_knowledge_detail","arguments":{
  "action":"chunk","ontologyId":"<ONTOLOGY_ID>",
  "evidenceId":"<EVIDENCE_ID_FROM_THE_SAME_SEARCH_RESULT>"
}}

Conditions for using content as facts

  • Check the current ACL, content completeness, and the server's canonicalFactEligible, citationEligible, or the corresponding execution contract.
  • The complete content is bound to contentSha256. Truncated, budget-omitted, or low-quality content must be handled according to the actual fields.
  • Document metadata, page_context, graph locators, retrieval summaries, and previews cannot substitute for the canonical source text.
  • Prefer copying evidenceId; when chunkId and documentId are needed, they must come from the same locator result; do not stitch together or fabricate them.

Graph routing

search/neighbors results are locator information. Only pass the routeLocator object fully returned by the server to the ontology query, including binding, version, and proof fields. Do not wrap an assetId or knowledgeId yourself as a server-issued locator, and do not send back provenance proofs asserted by the model.

Structured document recovery

dfc_ontology_query's structuredPlan is a restricted recovery and deterministic verification mechanism designed specifically for irregular document tables. Use the server-declared plan only after it returns the current executionContractSha256, tableIndex, columns, and the complete table. Regular business tables that have already been imported should be queried with dfc_table SQL; do not treat Markdown table recovery as a channel to bypass table query authorization.

Figure A6: The evidence chain from locator results to citable source text. Diagram.

Retrieval strategy

knowledgeIds is usually omitted so that all currently enabled bindings are covered; if you pass it, use only real knowledge base IDs from knowledgeBindings. Do not treat a document resource ID as a knowledge base ID. Run new, bounded searches for questions that remain unresolved, and avoid exact repeat searches that add no new evidence.

Chapter 13

Language and region conventions

Maintain the boundaries between UI locale, query dictionaries, return language, and original field names.

The order of precedence is the explicitly requested language, then the application system language, then the locale of the node that actually executes the request. An omitted value, null, an empty string, or whitespace does not force a fallback to Chinese. The region values in languageRegistry must be kept exact; en-GB, fr-CA, pt-BR, es-US, or ar-AE must not be arbitrarily collapsed into another locale.

Language or regionQuery localeNotes
Simplified Chinese and Traditional Chinesezh-CN zh-HantThe original Chinese rules differ from the Traditional Chinese catalog
US, UK, Australian, and Canadian Englishen-US en-GB en-AU en-CAUI/keyword packages may be shared; regional metadata is preserved
German, Italian, Russiande-DE it-IT ru-RUUse the current session's suggestions
Spanish (Spain and Latin America)es-ES es-USThe product region ID is es-US
French (France and Canada)fr-FR fr-CARegion IDs are not merged
Portuguese (Portugal and Brazil)pt-PT pt-BRCatalogs and regional conventions are kept separate
Dutch, Danish, Norwegian, Finnish, and Swedishnl-NL da-DK nb-NO fi-FI sv-SENorwegian is Bokmål
Japanese and Koreanja-JP ko-KRDo not apply English space-based tokenization
Saudi and UAE Arabicar-SA ar-AEInterface descriptions support RTL; protocol identifiers are not reversed

Using the keyword catalog

json
{"name":"dfc_manual","arguments":{
  "action":"keywords","locale":"de-DE","names":["<ACTUAL_KEYWORD_ID>"]
}}

The static keyword catalog of dfc_manual covers only the explicitly listed locales; if locale is omitted, the English reference is used. This is a reference default, not a rule for resolving the query language. When a static catalog is not provided for a regional variant, obtain actual suggestions via the current session's assist; do not fabricate aliases or fallback results. A single call accepts at most 32 names.

What not to translate

  • Table names, column names, enum values, customer names, formula names, and other real model strings.
  • Tool names, action and scope values, schema fields, error codes, and status values.
  • Resource IDs, hashes, opaque locators, and server-issued references.

For example, a German question can query the Chinese display column “销售金额”. Renaming it to a German column name creates a different identifier, not a UI translation. Re-initialize or update the session per the native protocol after changing languages, and re-fetch suggestions and disambiguation candidates.

Chapter 14

Federated analysis and interactive results

In the conditionally available analysis tools, preserve authorization, version, branch, and evidence status.

dfc_analysis_* is governed by datafocus.mcp.analysis.tools.enabled. The structured part still goes through Search's authoritative queries and the current row policy; the document part re-fetches the full source text under the current ACL. These tools are not an entry point for open SQL, arbitrary instructions, or arbitrary filter injection.

ToolPurposeRequired coordinates
dfc_analysis_askAsk a natural-language analysis questionontologyId and question; optional language and sessionId
dfc_analysis_result_getRead a previously returned resultontologyId sessionId resultId
dfc_analysis_refineFollow up on or modify the latest complete resultOriginal result, expectedRevision, and a stable idempotency key
dfc_analysis_pageFetch one page of a server-side branchOriginal branch and result version, pageNo pageSize
dfc_analysis_cancelCancel a result still in progressOriginal session and result
dfc_analysis_closeRelease a session that is not in a working stateOriginal session

Start analysis

json
{"name":"dfc_analysis_ask","arguments":{
  "ontologyId":"<ONTOLOGY_ID>",
  "question":"按区域分析已完成订单销售金额,并引用退货统计口径",
  "language":"zh-CN"
}}
  1. Read the returned sessionId, resultId, status, and revision; if needed, continue reading the original result.
  2. Check the status, completeness, row policy, and sources of each structured branch one by one; the completion of one branch does not mean the entire analysis is complete.
  3. Check document evidence, the fact ledger, citation eligibility, and limitations. Model-generated narratives cannot independently upgrade evidence eligibility.
  4. When follow-up questions are needed, base them on the latest complete results and pass expectedRevision; retries of the same change reuse the same idempotency key.
  5. Before closing, confirm the session is no longer working; cancellation and closing are different actions.

Controlled filtering and pagination

filter_patch uses the branchId, fieldRef, valueRef, and allowed operators provided by the server; typed filters currently declare only EQ. Do not replace opaque references with raw SQL, tableId, columnId, or filter trees fabricated by the client. For pagination, pageNo starts at 1 and is at most 10000; pageSize is at most 100.

Figure A7: Branches, versions, and pagination are bound together; after a source or version changes, re-query to obtain a new locator. Diagram.

Capability hints and behavior

Tool annotations are client hints, not security authorizations. Some generic templates use readOnlyHint, but that does not replace judgment about the actual action; canceling, closing, and creating a report change the corresponding working state. Always act according to tool semantics, user goals, and server-side permissions.

Chapter 15

Persistent visual reports and MCP Apps

Create resumable reports and read their results and interactive views under the current permissions.

dfc_report_* is controlled by datafocus.mcp.analysis.report-tools.enabled and requires the metadata and table query scopes. Unlike in-process Search sessions, reports use a persistent reportId; being persistent does not mean permissions are no longer checked.

json
{"name":"dfc_report_create","arguments":{
  "ontologyId":"<ONTOLOGY_ID>","goal":"比较区域与类别销售表现并核对口径",
  "title":"零售经营分析","language":"zh-CN",
  "idempotencyKey":"retail-report-20261019-01"
}}
{"name":"dfc_report_status","arguments":{
  "ontologyId":"<ONTOLOGY_ID>","reportId":"<REPORT_ID>"
}}

Workflow

  1. When creating a report, use a stable idempotencyKey of 8 to 128 supported characters.
  2. Save reportId, poll the status, and check the actual state, such as completed, failed, partially completed, or canceled.
  3. When reading results, verify the structured branches, visualizations, fact sources, document citations, and completeness.
  4. To cancel an unfinished report, use the original reportId; do not create another report in place of cancellation.
  5. After a network timeout, first read the original report status; a replay with the original idempotency key must carry the same business intent.

MCP Apps

Clients that support UI extensions read report pages through tool _meta and actual resource discovery. The persistent report page for r56 is ui://datafocus/analysis-report/v16/index.html; interactive analysis uses the corresponding server-side resource references; clients should not hard-code these in place of the values returned by tools. Without UI extensions, structured results can still be read.

Source bindings

Report reads re-check the Grant, ontology, request Origin binding, and current table permissions. Browser cross-origin integration must use approved actual origins; clients must not forge Origin to bypass the binding. An old reportId is neither a long-lived public link nor a credential for cross-user access.

Chapter 16

Artifact drafts, preview, plan, and apply

Hand generated content to the product's own server-side normalization, validation, and approval; do not let the model modify production resources directly.

Artifact tools require the authoring feature to be enabled, an actual artifact type, the relevant scope, and the original administrator write permissions. The default configured types are CONTROL_PANEL_SPEC and VIEW_SPEC; other form, HTTP source, or script types are also governed by separate configuration. Flash has no AutoML, so related types are not listed as available artifacts in this release.

Figure A8: The controlled sequence of context, candidate, preview, plan, approval, and apply. Diagram.
  1. dfc_authoring_capabilities reads the contracts and actions available under the current Grant.
  2. dfc_artifact_context obtains bounded context, contractVersion, contextHash, baseArtifactHash, and baseArtifactVersion.
  3. Generate candidates on the client according to the real contract, without executing the code within them.
  4. dfc_artifact_submit submits the original context and candidate, keeps the instruction unchanged, and uses a stable clientRequestId.
  5. Read proposalId, candidateHash, the validation results, and the preview; if there are actual errors, revise the candidate instead of faking a server pass status.
  6. To preview again, use dfc_artifact_preview with the same candidate hash.
  7. dfc_artifact_plan creates an immutable plan, using the real candidate, target version, and idempotency key.
  8. Handle approval according to the original interaction or an already-authorized policy, then call dfc_artifact_apply; only an APPLIED receipt shows that the change was actually applied.

Minimal context request

json
{"name":"dfc_artifact_context","arguments":{
  "artifactType":"CONTROL_PANEL_SPEC",
  "ontologyId":"<ONTOLOGY_ID>",
  "instruction":"为当前授权销售指标建立区域比较面板"
}}

VIEW_SPEC uses the currently authorized projectId; when editing an existing artifact, use the actual artifactId. Fields such as variables, previewInput, and viewport are provided according to the returned contract; do not guess or fabricate the internal structure of candidates.

Concurrency and retries

A plan is bound to the target version, candidate hash, and idempotency key. Once the target changes, the old plan can no longer be applied; re-read the context and resolve the actual conflicts. A transport timeout does not prove failure; first use dfc_artifact_status to query the original proposalId or planId. READY is not APPLIED.

Approval and automatic policy

Generic artifact plans require human approval through the original flow. Plans that comply with the ontology auto-publish policy are handled per approvalMode, and the user is not asked to sign a separate approval invented by the agent. approvalToken is server-issued material; an Agent cannot substitute a string of its own; the actual inputSchema and plan receipt determine the required fields.

Chapter 17

Ontology candidate creation and publishing contracts

Use the separately versioned ontology declarations and publishing configurations; do not apply ordinary display-artifact contracts to model publishing.

Creating a candidate

The ontology container must already exist and be within the Grant. Use dfc_ontology_table_schema to check the current structured source fields and v4 Binding fingerprints; a field can supply just sourceField and have its type discovered automatically. Explicit DECIMAL declarations require the current precision and scale; other types do not carry these two fields.

json
{"name":"dfc_ontology_table_schema","arguments":{
  "ontologyId":"<ONTOLOGY_ID>","sourceAssetRef":"table:<ACTUAL_TABLE_ID>",
  "fields":[{"sourceField":"区域"},{"sourceField":"销售金额"}]
}}

Candidate and publishing configuration

ContractPurposeKey boundaries
ontology-workspace-create-mcp-submit-v1Create a candidate from local declarationsReal authorized sources, compiled on the server; completion proofs are not accepted
ontology-workspace-create-mcp-submit-v2Mix local declarations and exact published referencesProvide the exact releaseSelections and closure dependencies
ontology-publication-mcp-submit-v1 to v3Bind an existing candidate to a publishing plan requestExplicit coordinates; target, source, approval, and validation are restored by the server
ontology-publication-mcp-submit-v4 to v6Separately enabled auto-publish configurationUse only when capabilities and the actual schema declare them
ontology-initial-activation-retirement-submit-v1Controlled initial activation and retirement operationsSeparate plan, new human approval, and exact scope

Publishing sequence

  1. Obtain the current candidate workspaceId, workspaceRevision, candidateHash, and actual sources.
  2. Choose the contract version according to server capabilities; submit coordinates such as releases and selection, without attaching fields that claim “approved” or “passed.”
  3. Keep the proposalId returned by submit and the original idempotencyKey. submit and MODEL_PLAN are different phases of the same request.
  4. Call dfc_artifact_plan using the original candidate, target version, and the same idempotency key.
  5. PLANNING_INCOMPLETE only means a valid plan has not yet been formed; VALIDATION_UNSATISFIED means current validation still has gaps; handle per nextAction.
  6. After the plan succeeds, continue according to HUMAN_REQUIRED or POLICY_AUTO, using the original approval and publishing capability.
  7. Confirm the result with the APPLIED receipt and subsequent real reads of the published model and authorized queries.

Timeout and recovery

After PLAN times out, read the original proposalId. MODEL_PLAN_SUBMITTED is an unfinished request; MODEL_PLAN_COMPLETED means the original receipt should be recovered with the original coordinates and original key, not that the client should create another new request. A terminal-state validation gap cannot be turned into a publishing pass by changing keys or resubmitting.

Human business authority

Agent-provided instructions and declarations are Agent inputs, not human policy signatures. MODEL_AUTHOR, MODEL_PUBLISH, auto-publish delegation, business confirmation, public key trust, budget, and source ACL continue to be determined by the original mechanisms. Client fields must not substitute for these facts.

Chapter 18

Published models, candidate queries, and reference closure

Use published business knowledge by exact version, and preserve the provisional nature of unpublished candidates.

dfc_ontology_graph's published_model, published_query, and candidate_query are conditionally exposed structured configurations, not synonyms for the ordinary search/neighbors actions. They are authorized by table query and the necessary modeling read permissions; graph visibility cannot substitute for table permissions.

Reading a published model

  1. When the tool's action enum actually includes published_model, submit the real committed releaseId.
  2. v1 returns authorized query templates; v2 adds exact PERSISTED references and releaseSelections; v3 adds dependency references, exact domainRef, and compact binding templates.
  3. Select objects, properties, Bindings, scopes, and versions from actual return values; do not generate RIDs or use latest.
  4. Submit fixed typed queries for published_query; results still need to pass current source and field authorization.

Candidate query

candidate_query uses the actual workspaceId, revision, candidateHash, and candidate declarations. When mixing published references, use the corresponding v2 typed LOCAL/PERSISTED coordinates and exact selection. Candidate results are always unpublished and provisional, and must not be treated as enterprise-confirmed knowledge.

Partial maintenance and closure

Select only the transitive dependencies required by the candidate root, and ensure every published reference has an exact entry in releaseSelections. Copying published content, submitting only a set of IDs, or expanding to all historical resources cannot substitute for current dependency and source checks.

Figure A9: Candidate root, exact published dependencies, and source authorization. Reference closure diagram.

The query for these actions is a versioned typed object; it does not accept SQL, physical table IDs, or source table names in place of its business references. Metadata templates and graph results are not, by themselves, eligible as fact citations.

Chapter 19

Delegated ontology agent tasks

Use persistent tasks and the original Grant to resume work; do not treat Agent instructions as human approval.

dfc_ontology_agent appears only when the Pi Runtime and the related permissions are actually available. QUERY uses read capabilities; AUTHORING additionally requires the modeling role and the corresponding authoring scope. It does not expose a separate, unconstrained execution engine.

json
{"name":"dfc_ontology_agent","arguments":{
  "contractVersion":"ontology-agent-task-v1","action":"start",
  "ontologyId":"<ONTOLOGY_ID>","mode":"QUERY",
  "instruction":"列出当前可查询的表,并说明各表用途",
  "idempotencyKey":"retail-discovery-01"
}}
{"name":"dfc_ontology_agent","arguments":{
  "contractVersion":"ontology-agent-task-v1","action":"status",
  "ontologyId":"<ONTOLOGY_ID>","runId":"<RUN_ID>"
}}

Strict parameter set

start uses contractVersion, action, ontologyId, mode, instruction, idempotencyKey; status/cancel use contractVersion, action, ontologyId, runId. The server checks the exact field set per action. instruction is at most 16000 characters; keys are 1 to 128 supported characters, starting with a letter or digit.

Resume and cancel

  1. Keep the original runId, Grant, mode, and idempotency key.
  2. The same key with the same instruction resumes the same run, without resubmitting another task; the same key with a changed instruction is rejected.
  3. status queries the original task status. Even after completion, its table queries, evidence, or publishing receipts must still be verified.
  4. Cancellation uses the original runId; confirm the result with the actual task status.

A completed run is not a model publishing receipt. Publishing tasks are still confirmed through the original artifact status and source checks; QUERY carries no implied write or publish rights.

Chapter 20

Business Workspace MCP

Query records based on published business contracts and execute commands through the original ActionPlan.

/mcp/business uses a separate protected resource and business system selection; the ontology Grant cannot be reused in place of business authorization. A business system must be published, callable by Agents, and compliant with the original security policy, and the current user must actually hold the runtime roles and capabilities.

ScopeToolBoundary
business-system:discoverdfb_systems dfb_system_describeDiscovers only systems covered by this authorization that are currently callable
business-system:readdfb_query dfb_record dfb_work_items dfb_action_statusRecords readable by the current user and their own plans
business-system:plandfb_action_planCreates immutable plans only; does not execute
business-system:executedfb_action_executeSeparate explicit authorization; executed per risk and approval
  1. dfb_systems discovers authorized systems.
  2. dfb_system_describe reads the current published contract, releaseId, and all hashes, queries, and commands.
  3. dfb_query uses the published queryKey, specifying objectKey, state, page, and pageSize as needed. It is not arbitrary SQL.
  4. dfb_record and dfb_work_items read the currently allowed records and work items.
  5. Before execution, use dfb_action_plan to provide the actual releaseId, releaseHash, canonicalIrHash, agentManifestHash, commandType, planIdempotencyKey, and contract payload.
  6. Verify riskClass, requiresApproval, and status; when target records are involved, keep expectedRecordVersion.
  7. dfb_action_execute executes only ready plans owned by the current connection; when human approval is required, DataFocus issues the approval token.
  8. After a failure or timeout, use dfb_action_status to recover the original plan; retries preserve the original idempotency semantics.
Figure A10: Published contracts, plans, approvals, and action execution. Diagram.

Connection and version binding

A plan is bound to the stable isolation ID of the current Grant. After an access token refresh, the same connection can still process its plans, but another OAuth connection cannot take them over. At execution time, the published version, IR/manifest hashes, target record versions, plan expiration, idempotency, and approvals are re-checked. The OAuth allowlist cannot bypass business governance.

Chapter 21

Business knowledge input and pending confirmation questions

Register business inputs when the corresponding production processor is available, and preserve the human confirmation boundary.

The following four tools are added conditionally by the public MCP controller, based on the installed processors and the current scope. They do not always appear in the base catalog. A declared schema does not mean the instance has the processors, budget, and permissions in place; always check tools/list first.

ToolPurposeAuthorizations or effects it does not produce
dfc_ontology_knowledge_input_proposeRegister original business inputs for an existing workspaceDoes not generate confirmation questions, approve, or publish
dfc_ontology_knowledge_input_previewGenerate a temporary preview of draft questions from the original inputNot persisted or confirmed; produces no production receipt
dfc_ontology_knowledge_question_submitSave authored but unconfirmed questionsDoes not automatically merge answers or obtain accountability permissions or publishing rights
dfc_ontology_business_scope_initializeExplicitly initialize a business system consumer scopeDoes not publish, activate, or grant source access

Input and preview

  1. Obtain workspaceId, workspaceRevision, localRef, and preparationDigest from the actual preparation work.
  2. propose uses the original input contract and a stable idempotencyKey to register business inputs; a given key can correspond only to one input.
  3. preview uses the idempotency key and ontologyId of the original input; each call returns a server-side revision and a 60-second window and is not an idempotent production completion receipt.
  4. When questions need to be stored, question_submit uses a new command key, the original originalInputKey, explicit questionRevision, validFrom, validUntil, and expectedRevision; at creation, expectedRevision is null.

Human confirmation entry point

The knowledgeConfirmationPage returned by question_submit is only a relative locator for the original login page, with one question pre-filled. It does not carry a bearer token, does not automatically open the page, and does not confirm knowledge. QUESTION_STORED_UNCONFIRMED explicitly means the question has not been confirmed; answers must not describe it as “knowledge published.”

Consumer scope initialization

business scope initialize requires both ontology publishing rights and creator or SourceManager administration rights for the exact business system. It uses the real coordinates of domainRid, domainRevisionId, and businessSystemId; clients cannot supply an arbitrary consumerScope or a fabricated completion proof. The returned INITIALIZED and COMPLETED states still explicitly carry published=false and activationAuthorized=false.

These requests are also subject to strict JSON, field-set, byte-size, and depth validation. Input requests are limited to 1 MiB; some specific operations have smaller limits. Full input and output schemas are delivered with the tool reference; the lenient parameter logic of the general MCP wrapper must not be applied to these strict contracts.

Chapter 22

Responses, errors, and safe retries

Interpret errors layer by layer, preserving task coordinates and idempotency semantics.

LayerWhat to checkHandling principle
Network and HTTPConnection, TLS, 401, 403, 400, 404, 405, etc.Do not treat failed responses as ordinary query results
JSON-RPCerror.code message dataDistinguish protocol, method, parameter, and authorization issues
MCP toolresult.isError and structuredContentHTTP 200 can still mean failure
Business resultReal status, completeness, failure reason, nextActionReceived or ready is not the same as complete
Factual eligibilityexecutionReceipt citationEligible contentCompleteIneligible content is used only for locating or explaining gaps

Common HTTP situations

  • 401: Missing or invalid bearer token; refresh or re-authorize according to the current OAuth flow.
  • 403: The Grant, role, selected resources, source permissions, Origin, or configuration is not satisfied; do not try to bypass it by replaying.
  • 400: The message or versioned contract is invalid, including inconsistency between modern headers and metadata.
  • 404: Check the exact service path, protocol method, and runtime capabilities; do not randomly switch ontology IDs.
  • 405: GET and DELETE are not offered on the public /mcp by design; use the correct POST instead of opening a long-lived SSE connection.

Write operations with unknown outcomes

MCP_OPERATION_OUTCOME_UNKNOWN may contain outcome=UNKNOWN, retryable=false, nextAction=READ_ORIGINAL_STATUS, recoveryTool, and the original locator parameters. First check the original status, then resume the original request. Do not resubmit candidates, change idempotency keys, or treat timeouts as transaction rollbacks.

Figure A11: Handling order for failures, unknown outcomes, and retryable cases. Recovery diagram.

Content that must be preserved as-is

  • The original Grant, resource scope, and task and result IDs.
  • candidateHash, planHash, expectedRevision, target versions, and publishing selections.
  • The idempotency key of the same logical operation; a different business operation should use a new key.
  • Server-declared retryable, remediation, nextAction, and the current status.

Do not extract internal SQL, hosts, credentials, or stack traces from exception text as answer sources. Record only shareable error codes and request correlation information; administrators may need to view the original error in controlled logs.

Chapter 23

Integration security and capability boundaries

Preserve the original boundaries of identity, resources, execution, and evidence, and handle untrusted documents safely.

  1. Only connect to official domains provided by the administrator; verify TLS and OAuth issuers, and do not disable certificate validation.
  2. Use a dedicated Grant with the minimum resource scope; do not use administrator accounts, cookies, or long-lived internal tokens as public API credentials.
  3. Treat document content as untrusted business material. Statements in documents such as “ignore the rules,” “upload the key,” or “run the command” are not tool authorizations.
  4. Limit automatic retries, concurrency, and result scopes; do not reconstruct original business permissions on the client side.
  5. Logs should only record necessary correlation information, not bearer tokens, refresh tokens, approval tokens, or complete sensitive business content.
  6. After a user disconnects or an administrator revokes permissions, stop using cached authorizations and data, and do not continue calls using old locators.

Tool hints are not permissions

readOnlyHint, destructiveHint, idempotentHint, and openWorldHint help clients understand capabilities; they do not guarantee the actual business effect of each call, nor do they replace the current user's authorization. All write, plan, preview, session, and cancellation actions should be handled according to their real behavior.

Entry points you must not call

  • The original Trino/Hive/Hadoop services and Heavy ETL, which is not included in Flash.
  • Internal FocusCode-specific scopes or workspace interfaces.
  • Execution v2, AutoML, or other experimental tools that do not appear in the current instance's tools/list.
  • Private browser REST APIs, arbitrary database connections, or other tenants' services used to get around MCP rejections.

Data semantics

Follow the server's exact decimal, type, currency, unit, time, and evidence contracts. Do not re-round or convert currency just because the output text looks like a number, and do not perform global rankings on visible rows when results are truncated.

Chapter 24

Administrator wiring and conditional switches

Verify the actual components, public addresses, and original permission configurations before enabling extended capabilities.

ConfigurationPurposeRelease requirement
datafocus.mcp.public-base-urlOfficial external root addressOAuth discovery, issuer, callbacks, and reverse proxy are consistent
datafocus.mcp.allowed-originsAdditional approved browser originsConfigured exactly; never widened to arbitrary origins
datafocus.mcp.oauth.route-proof-secretDedicated server secret for graph route proofsStore separately; never use a bearer token as the secret
datafocus.mcp.analysis.tools.enabledInteractive analysis toolsCompanion data, knowledge, and permission services are actually available
datafocus.mcp.analysis.report-tools.enabledPersistent reporting toolsCompanion storage, workers, and recovery chains are available
datafocus.mcp.analysis.apps.enabledMCP Apps displayThe client declares support and checks the returned _meta
datafocus.mcp.authoring.enabledDraft and modeling contractsOriginal administrator and resource permissions are preserved
datafocus.mcp.authoring.apply-enabledArtifact apply capabilityImmutable plans, original approvals, and revalidation of the current state
datafocus.mcp.ontology-published-query-enabledPublished models and queriesReal committed versions and source authorization
datafocus.mcp.ontology-candidate-query-enabledCandidate structured queriesCandidate ownership, exact versions, and read permission
datafocus.mcp.authoring.ontology-auto-publication-enabledAuthorizations related to auto-publish delegationValid original policies, public key trust, budget, and publishing rights

These names come from r56 configuration and implementation; whether they can be enabled depends on companion services and the original launch gates. Flipping a boolean alone does not supply missing processors, databases, validation budgets, or policies. The visibility of knowledge input extensions and Pi tasks depends on the actually installed components.

Edge proxy

Preserve Authorization, Content-Type, MCP-Protocol-Version, Mcp-Method, Mcp-Name, and approved Origin headers. Set the request body, timeouts, and TLS according to actual service requirements; do not forward the public /mcp to admin ports or another product.

Launch checklist

  • The status of anonymous discovery and protected calls matches expectations.
  • Regular users can discover only their authorized scope, and later requests are rejected after access is revoked.
  • Native Search sessions, SQL, source text, and optional reports each return real results.
  • Approvals for writes and publishing, and idempotent recovery, retain the original behavior.
  • Logs and public documentation contain no private keys, tokens, cookies, passwords, or internal customer data.
Chapter 25

Runnable client and call samples

Validate messages using the companion minimal client; do not bypass OAuth or current authorization.

examples/flash_mcp.py is a minimal protocol client that depends only on the Python standard library. It does not log in, does not perform approvals on your behalf, does not automatically call tools that are not visible, supports modern and legacy protocols, and uses separate exit layers for HTTP, JSON-RPC, and tool errors. Tokens are supplied through process environment variables and are not written into scripts or documentation files.

bash
export FLASH_BASE_URL='https://flash.example.com'
read -r -s -p 'Access token: ' FLASH_ACCESS_TOKEN
export FLASH_ACCESS_TOKEN

python3 examples/flash_mcp.py discover
python3 examples/flash_mcp.py tools
python3 examples/flash_mcp.py call dfc_ontologies --arguments '{"page":1,"pageSize":20}'

unset FLASH_ACCESS_TOKEN

Reading and querying

bash
python3 examples/flash_mcp.py call dfc_ontology_resources \
  --arguments-file examples/requests/ontology-resources.json

python3 examples/flash_mcp.py call dfc_table \
  --arguments-file examples/requests/table-detail.json

python3 examples/flash_mcp.py call dfc_table \
  --arguments-file examples/requests/top3-query.json

First replace placeholders such as ONTOLOGY_ID and TABLE_RESOURCE_ID in the request file with real values returned by the current authorization. The client refuses to run if any placeholder remains. The SQL sample requires the companion CSV to have been imported with the original column names; it cannot be submitted directly without the corresponding schema.

Other scenarios

  • Business entry point: use --endpoint business and obtain a new Grant for /mcp/business.
  • Legacy clients: choose --protocol 2025-11-25, initialize first, then invoke using the same protocol.
  • Built-in documentation: use resources or read-resource to read the actual URI.
  • Offline self-check: --self-test validates modern header and metadata construction without a token and without contacting the product server.

Scope of the samples

The client is a starting point for protocol integration; it does not automatically generate modeling candidates, save Q&A, or perform publishing. It outputs the raw JSON so that the calling Agent can verify the business state; do not promise users that queries, reports, or publishing are complete based solely on the process exit code.

Chapter 26

Embedding the ontology chat interface

Embed the human chat page into your business front end while preserving login and browser security boundaries.

html
<iframe
  title="OT Flash ontology agent"
  src="https://flash.example.com/10001/#/embed/ontology-agent/1001"
  style="width:100%;height:760px;border:0"
  referrerpolicy="strict-origin-when-cross-origin">
</iframe>

10001 is a sample tenant ID and 1001 is a sample ontology ID; replace them with real coordinates you are authorized to use. A single ontology can be specified via path or a supported query; all mode provides @ for selecting ontologies the current user can access. skillId is passed through only; do not claim on this basis that skill orchestration is executable.

Authentication and domains

The embedded page currently relies on a real DataFocus login state and checks /uc/status. Cross-site cookies, SSO, CSP frame-ancestors, and gateway configuration all affect embedding. It does not accept an MCP bearer token placed in the URL as a login-free channel; do not assemble the unimplemented outside external link yourself from design proposals.

MCP vs. the iframe

ApproachUserIdentity and results
Remote MCPExternal Agent or service integrationOAuth Grant with structured tool receipts
Ontology chat iframeHuman end usersOriginal login state and chat interface
MCP AppsMCP clients supporting extensionsControlled resources and current tool results, not a public replacement for iframe login
Chapter 27

Integration acceptance checklist

Prove the full business chain on a real instance, rather than merely confirming that interfaces return 200.

  1. Discovery: obtain the actually supported versions, the current tool catalog, and built-in resources.
  2. Authorization: regular users see only the ontologies and business systems they are permitted to access; operations without the required scope are rejected.
  3. Table structure: real display names, columns, types, and permissions are complete.
  4. SQL: single-dimensional, multidimensional, JOIN, date, TopN, and truncation checks match actual business definitions.
  5. Knowledge: locating, full source text, and fact-citation eligibility are consistent; mixed questions have both data and document evidence.
  6. Search: model, init, suggestions, results, close, and buffer integrity checks pass.
  7. Optional analysis and reports: real multi-branch states, pagination, permission changes, and cancellation retain the original behavior.
  8. Optional modeling: candidates, plans, original approvals, actual application, and version queries verified stage by stage.
  9. Business actions: release hash, target version, approval, idempotency, and cross-Grant isolation verified.
  10. Recovery: recover the original state after a network timeout; after a source update, old locators become invalid and new queries are used.

Result records

Record the instance version, user role, Grant scope, configuration version, actual operations, and results. Label separately the protocol client's offline self-check, the sample CSV's offline expected values, static JSON Schema validation, and real online functional acceptance. Do not extrapolate a pass in one stage to a pass for the whole product.

Chapter 28

Specification resources and maintenance

Use the complete tool schemas shipped with the manual and keep them in sync with the instance's actual discovery results.

ResourceContent
reference/mcp-tool-catalog.json32 ontology-side and 8 business-side declared input schemas; some tools also include their original output schemas
reference/locales.json21 selectable options and 24 compatible locales, with UI terminology
reference/search-keywords.jsonStatic keyword catalogs for 17 explicit locales
reference/analysis-contract-manifest.jsonVersion constraints for analysis, branches, facts, receipts, and reports
examples/Synthetic CSV, business definition notes, Top 3 SQL, expected results, and a minimal protocol client

Built-in documentation resources

text
datafocus://manuals/etl-formulas/v1
datafocus://manuals/search-keyword-queries/v1
datafocus://manuals/etl-functions/v1
datafocus://manuals/search-keywords/v1

resources/list and resources/read require the current user to hold at least one corresponding read entitlement among metadata, search operate, or etl operate. ETL documentation is a static cross-product reference; what Flash can execute is still limited to the scope it explicitly reports.

External protocol references

For MCP protocol and authorization background, refer to the official specifications: https://modelcontextprotocol.io/specification/2026-07-28/basic and https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization. The endpoints, tools, and conditional behavior of this product are governed by the r56 implementation and the current instance's discovery results; general protocol support must not be equated with the server providing all optional features.

Upgrade and maintenance

When upgrading, rediscover tools and versions and compare input schemas, output contracts, and configurations; old Grants do not automatically gain new scopes. Keep references, caches, and receipts bound to the source version; after confirming incompatible changes, re-obtain context and do not force old locators onto new business state.

Chapter 29

Tool parameter reference — basic and native Search

Full tool names and input fields, grouped by tool.

The tables below are a reading reference for the current r56 tool input fields. For full nested types, oneOf, conditionally required fields, schema constraints, and some output schemas, see reference/mcp-tool-catalog.json; before the final submission, you must still read the current Grant's tools/list. “Optional” in the tables does not remove the action's internal validation requirements.

dfc_manual

ParameterTypeRequirementMeaning and range
namesarrayOptional or conditionally requiredExplicit names to look up, up to 32 per call. maxItems: 32
actionstringOptional or conditionally requiredAction name. Use a value from the current enum with that action's parameters. enum: list, read, keywords, functions, etl_requests
localestringOptional or conditionally requiredExplicit static reference catalog locale, not the query's default language.
uristringOptional or conditionally requiredBuilt-in resource URI listed by the current tool. enum: datafocus://manuals/etl-formulas/v1, datafocus://manuals/search-keyword-queries/v1, datafocus://manuals/etl-functions/v1, datafocus://manuals/search-keywords/v1

dfc_search

ParameterTypeRequirementMeaning and range
dataobjectOptional or conditionally requiredRaw action payload; refer to the capability discovery and action field tables.
actionstringRequiredAction name. Use a value from the current enum with that action's parameters. enum: capabilities, model_create, model_read, open, request, poll, cancel, close

dfc_etl

ParameterTypeRequirementMeaning and range
dataobjectOptional or conditionally requiredRaw action payload; refer to the capability discovery and action field tables.
actionstringRequiredAction name. Use a value from the current enum with that action's parameters. enum: capabilities

dfc_ontologies

ParameterTypeRequirementMeaning and range
pageSizeintegerOptional or conditionally requiredItems per page; subject to the schema maximum. minimum: 1; maximum: 100
pageintegerOptional or conditionally requiredPage number, starting from 1. minimum: 1

dfc_ontology_resources

ParameterTypeRequirementMeaning and range
resourceTypesarrayOptional or conditionally requiredSet of resource types to return.
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
pageSizeintegerOptional or conditionally requiredItems per page; subject to the schema maximum. minimum: 1; maximum: 100
pageintegerOptional or conditionally requiredPage number, starting from 1. minimum: 1
Chapter 30

Tool parameter reference — tables, graph, and knowledge

Full tool names and input fields, grouped by tool.

The tables below are a reading reference for the current r56 tool input fields. For full nested types, oneOf, conditionally required fields, schema constraints, and some output schemas, see reference/mcp-tool-catalog.json; before the final submission, you must still read the current Grant's tools/list. “Optional” in the tables does not remove the action's internal validation requirements.

dfc_ontology_graph

ParameterTypeRequirementMeaning and range
relationTypesarrayOptional or conditionally requiredRelationship type filter.
depthintegerOptional or conditionally requiredNeighbor traversal depth. minimum: 1; maximum: 3
sourceTypesarrayOptional or conditionally requiredSource type filter.
queryobjectOptional or conditionally requiredQuery text, or the exact versioned query object corresponding to action.
limitintegerOptional or conditionally requiredMaximum number of results to return. minimum: 1; maximum: 100
actionstringRequiredAction name. Use a value from the current enum with that action's parameters. enum: search, neighbors, published_model, published_query, candidate_query
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
nodeKeystringOptional or conditionally requiredNode key copied from the actual graph result.
keywordstringOptional or conditionally requiredGraph locator keyword; not the keyword-based data query syntax.
nodeTypesarrayOptional or conditionally requiredNode type filter.

dfc_ontology_query

ParameterTypeRequirementMeaning and range
routeLocatorsarrayOptional or conditionally requiredThe typed route locator issued by the server, copied in full. maxItems: 20
topKintegerOptional or conditionally requiredUpper limit of recalled candidates; does not prove full coverage. minimum: 1; maximum: 20
queryModestringOptional or conditionally requiredSelect the evidence query mode from the tool enum. enum: vector, hybrid, graph
fanoutPlanobjectOptional or conditionally requiredRestricted branch retrieval plan, following the nested schema.
structuredPlanobjectOptional or conditionally requiredServer-side contract binding plan for the full document table; this is not SQL.
knowledgeIdsarrayOptional or conditionally requiredKnowledge base ID from the actual knowledgeBindings.
querystringRequiredQuery text, or the exact versioned query object corresponding to action.
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.

dfc_knowledge_search

ParameterTypeRequirementMeaning and range
topKintegerOptional or conditionally requiredUpper limit of recalled candidates; does not prove full coverage. minimum: 1; maximum: 20
minScorenumberOptional or conditionally requiredMinimum match score. minimum: 0; maximum: 1
knowledgeIdsarrayOptional or conditionally requiredKnowledge base ID from the actual knowledgeBindings.
querystringRequiredQuery text, or the exact versioned query object corresponding to action.
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
assetIdsarrayOptional or conditionally requiredCurrently permitted document asset ID.
retrievalStrategystringOptional or conditionally requiredRetrieval strategy that is actually supported. enum: auto, hybrid_stage2

dfc_knowledge_detail

ParameterTypeRequirementMeaning and range
qdrantIdstring / integerOptional or conditionally requiredIndex identifier returned by the actual locate call.
pageNointegerOptional or conditionally requiredActual page or pagination page number.
evidenceIdstringOptional or conditionally requiredEvidence ID returned by the same knowledge locate call.
actionstringRequiredAction name. Use a value from the current enum with that action's parameters. enum: chunk, document, page_context
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
documentIdstring / integerOptional or conditionally requiredDocument ID for the same locator.
radiusintegerOptional or conditionally requiredAdjacent page range. minimum: 0; maximum: 3
chunkIdstringOptional or conditionally requiredActual chunk ID for the same locator.

dfc_table

ParameterTypeRequirementMeaning and range
maxRowsintegerOptional or conditionally requiredUpper limit on returned rows; this is not a client-side ranking range. minimum: 1; maximum: 200
actionstringRequiredAction name. Use a value from the current enum with that action's parameters. enum: detail, query
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
idstringOptional or conditionally requiredReal table resource ID, not a physical name or display name.
sqlstringOptional or conditionally requiredA single read-only Doris SQL statement within the ontology scope, with explicit output columns.
Chapter 31

Tool parameter reference — analysis and reports

Full tool names and input fields, grouped by tool.

The tables below are a reading reference for the current r56 tool input fields. For full nested types, oneOf, conditionally required fields, schema constraints, and some output schemas, see reference/mcp-tool-catalog.json; before the final submission, you must still read the current Grant's tools/list. “Optional” in the tables does not remove the action's internal validation requirements.

dfc_analysis_ask

ParameterTypeRequirementMeaning and range
questionstringRequiredNatural language question, or a compatible follow-up question.
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
languagestringOptional or conditionally requiredExplicit answer or query locale; if omitted, the tool's own rules apply.
sessionIdstringOptional or conditionally requiredReal session locator under the same Grant.

dfc_analysis_refine

ParameterTypeRequirementMeaning and range
branchIdstringOptional or conditionally requiredStructured branch locator issued by the server.
resultIdstringRequiredAnalysis result locator from the original response.
questionstringOptional or conditionally requiredNatural language question, or a compatible follow-up question.
idempotencyKeystringRequiredIdempotency key, stably reused for the same logical operation.
changeobjectOptional or conditionally requiredNatural language change, or a typed filter_patch.
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
languagestringOptional or conditionally requiredExplicit answer or query locale; if omitted, the tool's own rules apply.
sessionIdstringRequiredReal session locator under the same Grant.
expectedRevisionintegerRequiredVersion precondition of the original result or business header; may be null when creating a question. minimum: 1
visualIdstringOptional or conditionally requiredVisualization locator bound to the branch.

dfc_analysis_page

ParameterTypeRequirementMeaning and range
branchIdstringRequiredStructured branch locator issued by the server.
resultIdstringRequiredAnalysis result locator from the original response.
pageNointegerRequiredActual page or pagination page number. minimum: 1; maximum: 10000
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
pageSizeintegerRequiredItems per page; subject to the schema maximum. minimum: 1; maximum: 100
sessionIdstringRequiredReal session locator under the same Grant.
expectedRevisionintegerRequiredVersion precondition of the original result or business header; may be null when creating a question. minimum: 1

dfc_analysis_result_get

ParameterTypeRequirementMeaning and range
resultIdstringRequiredAnalysis result locator from the original response.
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
sessionIdstringRequiredReal session locator under the same Grant.

dfc_analysis_cancel

ParameterTypeRequirementMeaning and range
resultIdstringRequiredAnalysis result locator from the original response.
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
sessionIdstringRequiredReal session locator under the same Grant.

dfc_analysis_close

ParameterTypeRequirementMeaning and range
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
sessionIdstringRequiredReal session locator under the same Grant.

dfc_report_create

ParameterTypeRequirementMeaning and range
goalstringRequiredAnalysis goal for the report.
idempotencyKeystringRequiredIdempotency key, stably reused for the same logical operation.
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
languagestringOptional or conditionally requiredExplicit answer or query locale; if omitted, the tool's own rules apply.
titlestringOptional or conditionally requiredOptional report title.

dfc_report_status

ParameterTypeRequirementMeaning and range
reportIdstringRequiredPersistent report locator under the current Grant.
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.

dfc_report_cancel

ParameterTypeRequirementMeaning and range
reportIdstringRequiredPersistent report locator under the current Grant.
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
Chapter 32

Tool parameter reference — modeling and original tasks

Full tool names and input fields, grouped by tool.

The tables below are a reading reference for the current r56 tool input fields. For full nested types, oneOf, conditionally required fields, schema constraints, and some output schemas, see reference/mcp-tool-catalog.json; before the final submission, you must still read the current Grant's tools/list. “Optional” in the tables does not remove the action's internal validation requirements.

dfc_ontology_agent

ParameterTypeRequirementMeaning and range
modestringOptional or conditionally requiredQUERY or AUTHORING; capabilities are authorized separately. enum: QUERY, AUTHORING
instructionstringOptional or conditionally requiredUser requirement text; must be consistent with the context and the submission. maxLength: 16000
idempotencyKeystringOptional or conditionally requiredIdempotency key stably reused for the same logical operation. maxLength: 128
actionstringRequiredAction name. Use a value from the current enum with that action's parameters. enum: start, status, cancel
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
runIdstringOptional or conditionally requiredOriginal task ID under the same ontology and Grant.
contractVersionstringRequiredUse the exact contract version that is actually supported. enum: ontology-agent-task-v1

dfc_authoring_capabilities

The input root object of this tool has no fields; use an empty arguments object.

dfc_artifact_context

ParameterTypeRequirementMeaning and range
artifactTypestringRequiredArtifact or ontology publication type that is actually enabled. enum: CONTROL_PANEL_SPEC, VIEW_SPEC
scopeTypestringOptional or conditionally requiredResource scope type in the actual artifact contract.
ontologyIdstringOptional or conditionally requiredReal ontology ID within the current authorization, preserved as a string.
projectIdstringOptional or conditionally requiredThe currently authorized project ID.
artifactIdstringOptional or conditionally requiredReal ID of an existing artifact being edited.
instructionstringRequiredUser requirement text; must be consistent with the context and the submission.
variablesobjectOptional or conditionally requiredVariable object provided according to the returned contract.
previewInputobjectOptional or conditionally requiredBounded preview input provided according to the contract.
viewportobjectOptional or conditionally requiredDisplay viewport required by the contract.

dfc_ontology_table_schema

ParameterTypeRequirementMeaning and range
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
sourceAssetRefstringRequiredA registered structured asset reference, e.g. table:123.
fieldsarrayRequiredFields of the current source with optional explicit type declarations. minItems: 1; maxItems: 64

dfc_artifact_preview

ParameterTypeRequirementMeaning and range
proposalIdstringRequiredThe original candidate ID created under the current Grant.
candidateHashstringRequiredThe exact hash of the original server-side candidate.
previewInputobjectRequiredBounded preview input provided according to the contract.

dfc_artifact_status

ParameterTypeRequirementMeaning and range
proposalIdstringOptional or conditionally requiredThe original candidate ID created under the current Grant.
planIdstringOptional or conditionally requiredThe immutable apply plan ID.

dfc_artifact_plan

ParameterTypeRequirementMeaning and range
proposalIdstringRequiredThe original candidate ID created under the current Grant.
candidateHashstringRequiredThe exact hash of the original server-side candidate.
expectedTargetVersionintegerRequiredThe current real target version precondition. minimum: 0
idempotencyKeystringRequiredIdempotency key, stably reused for the same logical operation.

dfc_artifact_apply

ParameterTypeRequirementMeaning and range
planIdstringRequiredThe immutable apply plan ID.
planHashstringRequiredThe hash returned with the original plan.
approvalTokenstringRequiredThe approval material originally issued by the server; do not generate it yourself.
idempotencyKeystringRequiredIdempotency key, stably reused for the same logical operation.

dfc_artifact_submit

ParameterTypeRequirementMeaning and range
Configuration 1 / artifactTypestringRequiredArtifact or ontology publication type that is actually enabled. enum: CONTROL_PANEL_SPEC, VIEW_SPEC
Configuration 1 / scopeTypestringOptional or conditionally requiredResource scope type in the actual artifact contract.
Configuration 1 / ontologyIdstringOptional or conditionally requiredReal ontology ID within the current authorization, preserved as a string.
Configuration 1 / projectIdstringOptional or conditionally requiredThe currently authorized project ID.
Configuration 1 / artifactIdstringOptional or conditionally requiredReal ID of an existing artifact being edited.
Configuration 1 / instructionstringRequiredUser requirement text; must be consistent with the context and the submission.
Configuration 1 / variablesobjectOptional or conditionally requiredVariable object provided according to the returned contract.
Configuration 1 / previewInputobjectOptional or conditionally requiredBounded preview input provided according to the contract.
Configuration 1 / viewportobjectOptional or conditionally requiredDisplay viewport required by the contract.
Configuration 1 / contractVersionstringRequiredUse the exact contract version that is actually supported.
Configuration 1 / contextHashstringRequiredThe full context hash returned by context.
Configuration 1 / baseArtifactHashstringRequiredThe base artifact hash returned by context.
Configuration 1 / baseArtifactVersionintegerRequiredThe base version returned by context. minimum: 0
Configuration 1 / candidateobjectRequiredA candidate object conforming to the currently returned contract.
Configuration 1 / clientRequestIdstringRequiredThe client idempotency key stably used for the current candidate request.
Configuration 2 / artifactTypestringRequiredArtifact or ontology publication type that is actually enabled. enum: ONTOLOGY_RELEASE
Configuration 2 / contractVersionstringRequiredUse the exact contract version that is actually supported. enum: ontology-publication-mcp-submit-v1, ontology-publication-mcp-submit-v2, ontology-publication-mcp-submit-v3, ontology-publication-mcp-submit-v4, ontology-publication-mcp-submit-v5, ontology-publication-mcp-submit-v6
Configuration 2 / ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
Configuration 2 / candidateHashstringRequiredThe exact hash of the original server-side candidate.
Configuration 2 / workspaceIdstringRequiredThe actual candidate workspace coordinates.
Configuration 2 / workspaceRevisionstringRequiredThe exact candidate version; do not use latest.
Configuration 2 / releasesobjectRequiredExact version selections, provided as the ontology publication contract requires.
Configuration 2 / selectionobjectRequiredProvides only explicit business selection coordinates; does not provide permission or completion proof.
Configuration 2 / idempotencyKeystringRequiredIdempotency key, stably reused for the same logical operation.
Configuration 3 / Configuration 1 / artifactTypestringRequiredArtifact or ontology publication type that is actually enabled. enum: ONTOLOGY_RELEASE
Configuration 3 / Configuration 1 / contractVersionstringRequiredUse the exact contract version that is actually supported. enum: ontology-workspace-create-mcp-submit-v1
Configuration 3 / Configuration 1 / ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
Configuration 3 / Configuration 1 / workspaceIdstringRequiredThe actual candidate workspace coordinates.
Configuration 3 / Configuration 1 / resourcesarrayRequiredThe original model declaration compiled by the server. minItems: 1
Configuration 3 / Configuration 1 / idempotencyKeystringRequiredIdempotency key, stably reused for the same logical operation.
Configuration 3 / Configuration 2 / artifactTypestringRequiredArtifact or ontology publication type that is actually enabled. enum: ONTOLOGY_RELEASE
Configuration 3 / Configuration 2 / contractVersionstringRequiredUse the exact contract version that is actually supported. enum: ontology-workspace-create-mcp-submit-v2
Configuration 3 / Configuration 2 / ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
Configuration 3 / Configuration 2 / workspaceIdstringRequiredThe actual candidate workspace coordinates.
Configuration 3 / Configuration 2 / resourcesarrayRequiredThe original model declaration compiled by the server. minItems: 1
Configuration 3 / Configuration 2 / idempotencyKeystringRequiredIdempotency key, stably reused for the same logical operation.
Configuration 3 / Configuration 2 / releaseSelectionsobjectRequiredThe exact releaseId of each published reference and its dependency closure.
Configuration 4 / artifactTypestringRequiredArtifact or ontology publication type that is actually enabled. enum: ONTOLOGY_RELEASE
Configuration 4 / contractVersionstringRequiredUse the exact contract version that is actually supported. enum: ontology-initial-activation-retirement-submit-v1
Configuration 4 / ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
Configuration 4 / domainRidstringRequiredThe real business domain RID.
Configuration 4 / consumerScopesarrayRequiredThe exact consumer scope allowed by the server. minItems: 1; maxItems: 256
Configuration 4 / idempotencyKeystringRequiredIdempotency key, stably reused for the same logical operation.
Chapter 33

Tool parameter reference — knowledge input and scope

Full tool names and input fields, grouped by tool.

The tables below are a reading reference for the current r56 tool input fields. For full nested types, oneOf, conditionally required fields, schema constraints, and some output schemas, see reference/mcp-tool-catalog.json; before the final submission, you must still read the current Grant's tools/list. “Optional” in the tables does not remove the action's internal validation requirements.

dfc_ontology_knowledge_input_propose

ParameterTypeRequirementMeaning and range
requestobjectRequiredThe original business input request; follows the complete nested schema.
idempotencyKeystringRequiredAn idempotency key that is stably reused for the same logical operation. minLength: 1; maxLength: 128

This tool also has its own outputSchema. Check the completeness of the output, its status, and any authorization fields explicitly set to false; do not read more into a completion status than it states.

dfc_ontology_knowledge_input_preview

ParameterTypeRequirementMeaning and range
idempotencyKeystringRequiredAn idempotency key that is stably reused for the same logical operation. minLength: 1; maxLength: 128
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.

This tool also has its own outputSchema. Check the completeness of the output, its status, and any authorization fields explicitly set to false; do not read more into a completion status than it states.

dfc_ontology_knowledge_question_submit

ParameterTypeRequirementMeaning and range
questionRevision$refRequiredThe explicit version of the question to be confirmed in this operation.
idempotencyKey$refRequiredIdempotency key, stably reused for the same logical operation.
originalInputKey$refRequiredThe idempotency key corresponding to the original knowledge input.
ontologyIdstringRequiredReal ontology ID within the current authorization, preserved as a string.
validUntil$refRequiredThe end of the question's validity window, in UTC.
expectedRevisiononeOfRequiredThe version precondition of the original result or business header; may be null when creating a question.
validFrom$refRequiredThe start of the question's validity window, in UTC.

This tool also has its own outputSchema. Check the completeness of the output, its status, and any authorization fields explicitly set to false; do not read more into a completion status than it states.

dfc_ontology_business_scope_initialize

ParameterTypeRequirementMeaning and range
domainRevisionIdstringRequiredThe exact business domain version. minLength: 1; maxLength: 128
idempotencyKeystringRequiredAn idempotency key that is stably reused for the same logical operation. minLength: 1; maxLength: 128
businessSystemIdstringRequiredThe real business system ID. minLength: 1
ontologyIdstringRequiredActual ontology ID within this authorization, preserved as a string. minLength: 1
domainRidstringRequiredActual business domain RID. minLength: 1; maxLength: 128

This tool also has its own outputSchema. Check the completeness of the output, its status, and any authorization fields explicitly set to false; do not read more into a completion status than it states.

Chapter 34

Tool parameter reference — Business Workspace

Full tool names and input fields, grouped by tool.

The tables below are a reading reference for the current r56 tool input fields. For full nested types, oneOf, conditionally required fields, schema constraints, and some output schemas, see reference/mcp-tool-catalog.json; before the final submission, you must still read the current Grant's tools/list. “Optional” in the tables does not remove the action's internal validation requirements.

dfb_systems

The input root object of this tool has no fields; use an empty arguments object.

dfb_system_describe

ParameterTypeRequirementMeaning and range
systemIdstring / integerRequiredThe system ID permitted by this business Grant.

dfb_query

ParameterTypeRequirementMeaning and range
systemIdstring / integerRequiredThe system ID permitted by this business Grant.
queryKeystringRequiredThe published query key returned by describe.
objectKeystringOptional or conditionally requiredPublished object key.
pageSizeintegerOptional or conditionally requiredItems per page; subject to the schema maximum. minimum: 1; maximum: 100
pageintegerOptional or conditionally requiredPage number, starting from 1. minimum: 1
statestringOptional or conditionally requiredBusiness status filter or server-side status.

dfb_record

ParameterTypeRequirementMeaning and range
recordIdstring / integerRequiredThe ID of the business record currently allowed to be read.
systemIdstring / integerRequiredThe system ID permitted by this business Grant.

dfb_work_items

ParameterTypeRequirementMeaning and range
systemIdstring / integerRequiredThe system ID permitted by this business Grant.

dfb_action_plan

ParameterTypeRequirementMeaning and range
expectedRecordVersionintegerOptional or conditionally requiredThe current optimistic-lock version of the target record. minimum: 1
systemIdstring / integerRequiredThe system ID permitted by this business Grant.
commandTypestringRequiredThe command type in the published contract.
canonicalIrHashstringRequiredThe hash of the currently published canonical IR.
releaseIdstring / integerRequiredThe actual published contract version ID.
payloadobjectRequiredThe payload conforming to the current command contract in describe.
releaseHashstringRequiredThe actual published contract hash.
targetRecordIdstring / integerOptional or conditionally requiredThe actual target record to be operated on.
agentManifestHashstringRequiredThe actual Agent capability manifest hash.
planIdempotencyKeystringRequiredThe stable idempotency key of the business plan.

dfb_action_status

ParameterTypeRequirementMeaning and range
actionPlanIdstring / integerRequiredThe action plan ID owned by the current business Grant.

dfb_action_execute

ParameterTypeRequirementMeaning and range
approvalTokenstringOptional or conditionally requiredThe approval material originally issued by the server; do not generate it yourself.
actionPlanIdstring / integerRequiredThe action plan ID owned by the current business Grant.