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.
Table of contents
- 1Agent integration scope and completion criteria
- 2Quick connection and capability discovery
- 3OAuth discovery, registration, and authorization
- 4Scope, resource boundaries, and real-time permissions
- 5HTTP and modern MCP messages
- 6Legacy protocol client compatibility
- 7Choosing the right tool and evidence channel
- 8Ontology resources and ID types
- 9Doris table query and structure contract
- 10Multidimensional Top 3 and truncation handling
- 11Knowledge retrieval: full source text and evidence eligibility
- 12Native Search model and session
- 13Language and region conventions
- 14Federated analysis and interactive results
- 15Persistent visual reports and MCP Apps
- 16Artifact drafts, preview, plan, and apply
- 17Ontology candidate creation and publishing contracts
- 18Published models, candidate queries, and reference closure
- 19Delegated ontology agent tasks
- 20Business Workspace MCP
- 21Business knowledge input and pending confirmation questions
- 22Responses, errors, and safe retries
- 23Integration security and capability boundaries
- 24Administrator wiring and conditional switches
- 25Runnable client and call samples
- 26Embedding the ontology chat interface
- 27Integration acceptance checklist
- 28Specification resources and maintenance
- 29Tool parameter reference — basic and native Search
- 30Tool parameter reference — tables, graph, and knowledge
- 31Tool parameter reference — analysis and reports
- 32Tool parameter reference — modeling and original tasks
- 33Tool parameter reference — knowledge input and scope
- 34Tool parameter reference — Business Workspace
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.
| Entry | Purpose | Boundary |
|---|---|---|
| /mcp | Ontologies, data tables, document knowledge, native Search, and conditionally available analysis and modeling | Intersection of the current user's permissions and the resources covered by this authorization |
| /mcp/business | Business system discovery, queries, action plans, status, and execution | Separate business system authorization and published contracts |
| Embedded ontology agent page | Ontology chat in the human user interface | Requires 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.
Quick connection and capability discovery
Start with the instance's official domain and discover actually available tools with least privilege.
- 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.
- Configure the MCP server address as https://flash.example.com/mcp; the Business Workspace uses /mcp/business on the same domain.
- Trigger OAuth login and authorization as supported by the client and verify resources and scope; do not submit usernames and passwords to MCP.
- Use protocol discovery or initialization appropriate to the protocol era, then read tools/list and resource descriptions.
- First make a small read-only request to verify structured results and error handling, then execute the user's goal.
Client configuration snippet
{
"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
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.
OAuth discovery, registration, and authorization
Use the authorization code flow with PKCE; do not expose product login credentials to the Agent.
| Endpoint | Method | Purpose |
|---|---|---|
| /.well-known/oauth-protected-resource | GET | Ontology MCP resource discovery |
| /.well-known/oauth-protected-resource/mcp | GET | Ontology resource path compatibility discovery |
| /.well-known/oauth-protected-resource/mcp/business | GET | Business MCP resource discovery |
| /.well-known/oauth-authorization-server | GET | Authorization server metadata |
| /oauth/register | POST JSON | Dynamic registration of a public client |
| /oauth/authorize | GET or POST form | Log in, select resources, and confirm authorization |
| /oauth/token | POST form | Authorization code exchange and refresh rotation |
| /oauth/revoke | POST form | Token revocation |
| /oauth/grants | GET | View authorized connections (logged-in users) |
| /oauth/grants/revoke | POST form | Revoke a connection through the original page flow |
Authorization sequence
- 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.
- 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.
- Generate a random state and code_verifier, and compute the S256 code_challenge.
- 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.
- 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.
- Receive the callback and verify state and issuer, then exchange the authorization code using the original code_verifier.
- Use the access_token only for MCP Bearer authentication. Refresh using the original OAuth flow and securely store the rotated refresh_token.
Registration example
{
"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.
Scope, resource boundaries, and real-time permissions
Authorization scopes delegate existing permissions; they do not elevate roles or share business state across Grants.
| Scope | Typical capabilities | Important constraints |
|---|---|---|
| ontology.metadata:read | Ontologies, resources, and table structures | Ontologies and tables must be within the authorized and currently readable scope |
| ontology.graph:read | Graph search and neighbors | Returns locator information, not factual evidence |
| ontology.knowledge:read | Knowledge location and full source text | Original knowledge base and document permissions still apply |
| ontology.table:query | Ontology table SQL and published model queries | Table queries also require the metadata scope; actual source and column permissions remain in effect |
| search:operate | Native keyword models and sessions | Separate, explicit delegation; runs under the original model and the user's table and column permissions |
| etl:operate | Flash ETL capabilities | Heavy ETL is not exposed |
| authoring.contract:read | Conditionally available modeling contracts | Also requires the feature switch and the related resources |
| authoring.artifact:read | Reads of candidates, plans, and similar items under the current authorization | Bound to the original principal, Grant, and resources |
| authoring.artifact:draft | Candidate submission, preview, etc. | Does not authorize execution or publication |
| authoring.artifact:apply | Controlled plans and apply | Still requires the original business role, policy, and approval |
| execution.script:draft | Specific script drafts | Does not authorize actual script execution |
| datasource.http:read / draft / test / import | Conditionally available HTTP data source artifact capabilities | Each has its own switch; original permissions still apply |
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.
HTTP and modern MCP messages
Correctly send per-request metadata and matching route headers, and handle HTTP and tool results separately.
| Item | r56 behavior |
|---|---|
| Transport | Stateless Streamable HTTP, POST JSON-RPC |
| Supported version identifiers | 2026-07-28, plus 2025-11-25, 2025-06-18, and 2025-03-26 |
| Modern methods | server/discover, tools/list, tools/call, resources/list, resources/read, enabled according to actual capabilities |
| Session header | No Mcp-Session-Id is assigned |
| GET and DELETE | /mcp and /mcp/business return 405 |
| Server SSE notifications | Not provided on these two public MCP entry points |
| Catalog cache | Modern discovery and list responses return ttlMs=60000 and cacheScope=private |
| Normal results | Modern 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
{
"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.
Legacy protocol client compatibility
Keep a consistent protocol era in clients that still use the initialization handshake.
{
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {"name": "flash-legacy-client", "version": "1.0.0"}
}
}- Send initialize and read the protocol version and capabilities negotiated by the server.
- Send the initialization-complete notification required by the client's protocol; a notification has no normal tool result.
- Use tools/list to read the currently authorized tools, then send tools/call.
- 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
| Situation | Typical result | Resolution |
|---|---|---|
| Inconsistent modern headers and payload | HTTP 400 JSON-RPC -32020 | Correct the headers, metadata, and tool name |
| Unsupported version | -32022 with a list of supported versions | Choose a protocol version that is actually supported |
| Unknown method | JSON-RPC -32601; modern requests may get HTTP 404 | Check the protocol era and method |
| Missing or invalid parameters | JSON-RPC parameter error or tool isError | Correct according to the actual inputSchema |
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.
| Task | Preferred tool | Evidence required for completion |
|---|---|---|
| Discover authorized subjects and resources | dfc_ontologies dfc_ontology_resources | Actual resource ID types and current visibility scope |
| Table statistics and TopN | dfc_table query | Successful execution receipt and the full evidenceRows |
| Look up policies, contracts, or reports | dfc_ontology_query or knowledge search/detail | Complete, authorized source text that can be used as facts |
| Locate graph objects | dfc_ontology_graph search/neighbors | Locate the actual source first, then obtain the corresponding facts |
| Native keyword interaction | dfc_manual then dfc_search | Actual results in the original model and business frames |
| Federated analysis and reports | dfc_analysis_* or dfc_report_* | Actual status of each structured branch and of the document evidence |
| Modify presentation or the ontology model | dfc_authoring_* and artifact tools | Verify candidates, plans, approvals, and applied changes separately |
| Execute business commands | dfb_* on /mcp/business | Published 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.
Ontology resources and ID types
Obtain the actual resource coordinates first to prevent conflating storage names, document IDs, and knowledge base IDs.
- Call dfc_ontologies and page through the ontologies covered by this authorization that are still readable, using page and pageSize.
- Call dfc_ontology_resources with the real ontologyId; select tables, answers, pinboards, documents, and knowledgeBindings as needed.
- Handle pagination separately for each resource type. pageSize has a maximum of 100; do not infer the full resource scope from the first page.
- Save the type and original ID declared by the resource and use them verbatim in subsequent calls.
{"name":"dfc_ontology_resources","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"resourceTypes":["tables","documents","knowledgeBindings"],
"page":1,"pageSize":100
}}| Coordinate | Source | Cannot be replaced by |
|---|---|---|
| ontologyId | Authorized ontology list or current valid context | Another ontology's ID |
| Table resource id | tables list or trusted context | physicalName or displayed table name |
| tblDisplayName colDisplayName | Current table and column metadata | A guessed physical SQL identifier |
| knowledgeId | knowledgeBindings or an actual knowledge retrieval receipt | Document resource id |
| assetId documentId chunkId evidenceId | The same actual locator receipt | Fields stitched together from different locator results |
| rid revisionId releaseId | Published model or server-side candidate context | An 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.
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
{"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
{
"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 target | Form | Note |
|---|---|---|
| DATE | CAST('2026-09-01' AS DATE) and CURRENT_DATE | Do not use a bare text literal and assume it is a date |
| DATETIME | CAST('2026-09-01 00:00:00' AS DATETIME) and CURRENT_TIMESTAMP | Verify the source time zone and the session time zone |
| Relative time | DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR) | Use the corresponding current function for dates and timestamps |
| Time grouping | YEAR(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.
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.
- Obtain the real structure and the current business definition, and clarify currency, period, 订单状态, and tie-breaking rules.
- Submit server-side aggregation and ranking SQL. Do not query only the 区域 totals and then present them as the 产品 ranking within each 类别.
- Check the output column contract against the actual evidenceRows, and confirm that the returned data covers all required groups.
- 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.
- If the source changes in the meantime, re-query and state the new version explicitly; do not mix different data versions or stale cursors.
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.
Knowledge retrieval: full source text and evidence eligibility
Separate locating, reading, and fact citation, and preserve provenance and completeness.
Two common paths
| Path | Purpose | Key points |
|---|---|---|
| dfc_ontology_query | Search within ontology-bound knowledge, optionally combined with graph routing | Check the complete canonical answerContextItems and evidence eligibility |
| dfc_knowledge_search → dfc_knowledge_detail chunk | Locate via explicit search, then read the selected chunk | Search previews are not facts; read the full source text for the same locator |
{"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.
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.
Native Search model and session
Use the Rust Search keyword protocol via dfc_search, and wait for the terminal state of the native business frame.
Read the documentation before discovering capabilities
{"name":"dfc_manual","arguments":{
"action":"read","uri":"datafocus://manuals/search-keyword-queries/v1"
}}
{"name":"dfc_search","arguments":{"action":"capabilities"}}dfc_search requires search:operate to be granted explicitly. It wraps the native keyword WebSocket and does not rewrite keywords into SQL or LLM requests. The session is bound to the current tenant, user, Grant, client, and model, and the original table and column permissions are re-checked on each operation.
Minimal session flow
{"name":"dfc_search","arguments":{
"action":"model_create","data":{"tableIds":["<ACTUAL_TABLE_ID>"]}
}}
{"name":"dfc_search","arguments":{
"action":"open","data":{"sourceToken":"<MODEL_SOURCE_TOKEN>","language":"en-US"}
}}
{"name":"dfc_search","arguments":{
"action":"poll","data":{"sessionId":"<SEARCH_SESSION_ID>","waitMillis":10000}
}}
{"name":"dfc_search","arguments":{
"action":"request","data":{"sessionId":"<SEARCH_SESSION_ID>",
"message":{"type":"assist","datas":{}}}
}}
{"name":"dfc_search","arguments":{
"action":"request","data":{"sessionId":"<SEARCH_SESSION_ID>",
"message":{"type":"search","datas":{"search":"<QUERY_USING_ACTUAL_COLUMNS>","ambiguities":[]}}}
}}- Use model_create with 1 to 100 real table IDs you are authorized for, or use model_read with your own existing sourceToken.
- open only returns initializationSent; poll first, read the native init business response, and confirm success.
- Read assist and suggestions, then send a supported native message. In query datas, isNl is fixed to false by the wrapper.
- Continuously read frames, distinguishing suggestions, parsing, acceptance, and the final business result.
- Call close at the end; call cancel when cancellation is needed, and verify termination against the real task state.
| action | data | Meaning |
|---|---|---|
| capabilities | Omitted or empty object | Read actions, commands, TTL, and transport notes |
| model_create | tableIds array | Create an authorized model for the current user |
| model_read | sourceToken | Read models, filtering out unauthorized columns and sensitive source configurations |
| open | sourceToken with optional language | Establish a native session and send init |
| request | sessionId and message | Send a native type/datas protocol message |
| poll | sessionId and waitMillis 0 to 30000 | Drain the currently buffered frames, with an optional bounded wait |
| cancel close | sessionId | Close this native session; this does not prove a BI terminal state |
Supported native commands
search associateSearch guide assist exportContext reInit
putFormula modifyFormula deleteFormula fnamecheck
disambiguite reDisambiguite clearDisambiguiteCommand casing and datas structure follow the current capabilities and the native session protocol. Do not add nonexistent actions to the request; for example, the spelling of disambiguite must be preserved as it appears in the actual protocol. Messages are limited to 256 Ki characters.
Sessions and integrity
The session TTL is 10 minutes and is retained only for the lifetime of the current process; it is not a durable, resumable task. The buffer holds at most 256 frames and is subject to memory limits; when bufferOverflow=true, already-fetched frames must not be treated as a complete result. After a transport error, poll the native session first; do not blindly resend a query that may already have been executed.
The current wrapper does not provide answer or pinboard saving, history read/write, or arbitrary context restoration. The existence of exportContext does not mean arbitrary context can be restored on your own. To save results, use the native resource capabilities actually exposed by the instance; do not guess or fabricate actions.
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 region | Query locale | Notes |
|---|---|---|
| Simplified Chinese and Traditional Chinese | zh-CN zh-Hant | The original Chinese rules differ from the Traditional Chinese catalog |
| US, UK, Australian, and Canadian English | en-US en-GB en-AU en-CA | UI/keyword packages may be shared; regional metadata is preserved |
| German, Italian, Russian | de-DE it-IT ru-RU | Use the current session's suggestions |
| Spanish (Spain and Latin America) | es-ES es-US | The product region ID is es-US |
| French (France and Canada) | fr-FR fr-CA | Region IDs are not merged |
| Portuguese (Portugal and Brazil) | pt-PT pt-BR | Catalogs and regional conventions are kept separate |
| Dutch, Danish, Norwegian, Finnish, and Swedish | nl-NL da-DK nb-NO fi-FI sv-SE | Norwegian is Bokmål |
| Japanese and Korean | ja-JP ko-KR | Do not apply English space-based tokenization |
| Saudi and UAE Arabic | ar-SA ar-AE | Interface descriptions support RTL; protocol identifiers are not reversed |
Using the keyword catalog
{"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.
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.
| Tool | Purpose | Required coordinates |
|---|---|---|
| dfc_analysis_ask | Ask a natural-language analysis question | ontologyId and question; optional language and sessionId |
| dfc_analysis_result_get | Read a previously returned result | ontologyId sessionId resultId |
| dfc_analysis_refine | Follow up on or modify the latest complete result | Original result, expectedRevision, and a stable idempotency key |
| dfc_analysis_page | Fetch one page of a server-side branch | Original branch and result version, pageNo pageSize |
| dfc_analysis_cancel | Cancel a result still in progress | Original session and result |
| dfc_analysis_close | Release a session that is not in a working state | Original session |
Start analysis
{"name":"dfc_analysis_ask","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"question":"按区域分析已完成订单销售金额,并引用退货统计口径",
"language":"zh-CN"
}}- Read the returned sessionId, resultId, status, and revision; if needed, continue reading the original result.
- 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.
- Check document evidence, the fact ledger, citation eligibility, and limitations. Model-generated narratives cannot independently upgrade evidence eligibility.
- 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.
- 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.
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.
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.
{"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
- When creating a report, use a stable idempotencyKey of 8 to 128 supported characters.
- Save reportId, poll the status, and check the actual state, such as completed, failed, partially completed, or canceled.
- When reading results, verify the structured branches, visualizations, fact sources, document citations, and completeness.
- To cancel an unfinished report, use the original reportId; do not create another report in place of cancellation.
- 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.
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.
- dfc_authoring_capabilities reads the contracts and actions available under the current Grant.
- dfc_artifact_context obtains bounded context, contractVersion, contextHash, baseArtifactHash, and baseArtifactVersion.
- Generate candidates on the client according to the real contract, without executing the code within them.
- dfc_artifact_submit submits the original context and candidate, keeps the instruction unchanged, and uses a stable clientRequestId.
- Read proposalId, candidateHash, the validation results, and the preview; if there are actual errors, revise the candidate instead of faking a server pass status.
- To preview again, use dfc_artifact_preview with the same candidate hash.
- dfc_artifact_plan creates an immutable plan, using the real candidate, target version, and idempotency key.
- 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
{"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.
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.
{"name":"dfc_ontology_table_schema","arguments":{
"ontologyId":"<ONTOLOGY_ID>","sourceAssetRef":"table:<ACTUAL_TABLE_ID>",
"fields":[{"sourceField":"区域"},{"sourceField":"销售金额"}]
}}Candidate and publishing configuration
| Contract | Purpose | Key boundaries |
|---|---|---|
| ontology-workspace-create-mcp-submit-v1 | Create a candidate from local declarations | Real authorized sources, compiled on the server; completion proofs are not accepted |
| ontology-workspace-create-mcp-submit-v2 | Mix local declarations and exact published references | Provide the exact releaseSelections and closure dependencies |
| ontology-publication-mcp-submit-v1 to v3 | Bind an existing candidate to a publishing plan request | Explicit coordinates; target, source, approval, and validation are restored by the server |
| ontology-publication-mcp-submit-v4 to v6 | Separately enabled auto-publish configuration | Use only when capabilities and the actual schema declare them |
| ontology-initial-activation-retirement-submit-v1 | Controlled initial activation and retirement operations | Separate plan, new human approval, and exact scope |
Publishing sequence
- Obtain the current candidate workspaceId, workspaceRevision, candidateHash, and actual sources.
- Choose the contract version according to server capabilities; submit coordinates such as releases and selection, without attaching fields that claim “approved” or “passed.”
- Keep the proposalId returned by submit and the original idempotencyKey. submit and MODEL_PLAN are different phases of the same request.
- Call dfc_artifact_plan using the original candidate, target version, and the same idempotency key.
- PLANNING_INCOMPLETE only means a valid plan has not yet been formed; VALIDATION_UNSATISFIED means current validation still has gaps; handle per nextAction.
- After the plan succeeds, continue according to HUMAN_REQUIRED or POLICY_AUTO, using the original approval and publishing capability.
- 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.
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
- When the tool's action enum actually includes published_model, submit the real committed releaseId.
- v1 returns authorized query templates; v2 adds exact PERSISTED references and releaseSelections; v3 adds dependency references, exact domainRef, and compact binding templates.
- Select objects, properties, Bindings, scopes, and versions from actual return values; do not generate RIDs or use latest.
- 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.
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.
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.
{"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
- Keep the original runId, Grant, mode, and idempotency key.
- The same key with the same instruction resumes the same run, without resubmitting another task; the same key with a changed instruction is rejected.
- status queries the original task status. Even after completion, its table queries, evidence, or publishing receipts must still be verified.
- 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.
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.
| Scope | Tool | Boundary |
|---|---|---|
| business-system:discover | dfb_systems dfb_system_describe | Discovers only systems covered by this authorization that are currently callable |
| business-system:read | dfb_query dfb_record dfb_work_items dfb_action_status | Records readable by the current user and their own plans |
| business-system:plan | dfb_action_plan | Creates immutable plans only; does not execute |
| business-system:execute | dfb_action_execute | Separate explicit authorization; executed per risk and approval |
- dfb_systems discovers authorized systems.
- dfb_system_describe reads the current published contract, releaseId, and all hashes, queries, and commands.
- dfb_query uses the published queryKey, specifying objectKey, state, page, and pageSize as needed. It is not arbitrary SQL.
- dfb_record and dfb_work_items read the currently allowed records and work items.
- Before execution, use dfb_action_plan to provide the actual releaseId, releaseHash, canonicalIrHash, agentManifestHash, commandType, planIdempotencyKey, and contract payload.
- Verify riskClass, requiresApproval, and status; when target records are involved, keep expectedRecordVersion.
- dfb_action_execute executes only ready plans owned by the current connection; when human approval is required, DataFocus issues the approval token.
- After a failure or timeout, use dfb_action_status to recover the original plan; retries preserve the original idempotency semantics.
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.
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.
| Tool | Purpose | Authorizations or effects it does not produce |
|---|---|---|
| dfc_ontology_knowledge_input_propose | Register original business inputs for an existing workspace | Does not generate confirmation questions, approve, or publish |
| dfc_ontology_knowledge_input_preview | Generate a temporary preview of draft questions from the original input | Not persisted or confirmed; produces no production receipt |
| dfc_ontology_knowledge_question_submit | Save authored but unconfirmed questions | Does not automatically merge answers or obtain accountability permissions or publishing rights |
| dfc_ontology_business_scope_initialize | Explicitly initialize a business system consumer scope | Does not publish, activate, or grant source access |
Input and preview
- Obtain workspaceId, workspaceRevision, localRef, and preparationDigest from the actual preparation work.
- propose uses the original input contract and a stable idempotencyKey to register business inputs; a given key can correspond only to one input.
- 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.
- 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.
Responses, errors, and safe retries
Interpret errors layer by layer, preserving task coordinates and idempotency semantics.
| Layer | What to check | Handling principle |
|---|---|---|
| Network and HTTP | Connection, TLS, 401, 403, 400, 404, 405, etc. | Do not treat failed responses as ordinary query results |
| JSON-RPC | error.code message data | Distinguish protocol, method, parameter, and authorization issues |
| MCP tool | result.isError and structuredContent | HTTP 200 can still mean failure |
| Business result | Real status, completeness, failure reason, nextAction | Received or ready is not the same as complete |
| Factual eligibility | executionReceipt citationEligible contentComplete | Ineligible 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.
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.
Integration security and capability boundaries
Preserve the original boundaries of identity, resources, execution, and evidence, and handle untrusted documents safely.
- Only connect to official domains provided by the administrator; verify TLS and OAuth issuers, and do not disable certificate validation.
- Use a dedicated Grant with the minimum resource scope; do not use administrator accounts, cookies, or long-lived internal tokens as public API credentials.
- 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.
- Limit automatic retries, concurrency, and result scopes; do not reconstruct original business permissions on the client side.
- Logs should only record necessary correlation information, not bearer tokens, refresh tokens, approval tokens, or complete sensitive business content.
- 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.
Administrator wiring and conditional switches
Verify the actual components, public addresses, and original permission configurations before enabling extended capabilities.
| Configuration | Purpose | Release requirement |
|---|---|---|
| datafocus.mcp.public-base-url | Official external root address | OAuth discovery, issuer, callbacks, and reverse proxy are consistent |
| datafocus.mcp.allowed-origins | Additional approved browser origins | Configured exactly; never widened to arbitrary origins |
| datafocus.mcp.oauth.route-proof-secret | Dedicated server secret for graph route proofs | Store separately; never use a bearer token as the secret |
| datafocus.mcp.analysis.tools.enabled | Interactive analysis tools | Companion data, knowledge, and permission services are actually available |
| datafocus.mcp.analysis.report-tools.enabled | Persistent reporting tools | Companion storage, workers, and recovery chains are available |
| datafocus.mcp.analysis.apps.enabled | MCP Apps display | The client declares support and checks the returned _meta |
| datafocus.mcp.authoring.enabled | Draft and modeling contracts | Original administrator and resource permissions are preserved |
| datafocus.mcp.authoring.apply-enabled | Artifact apply capability | Immutable plans, original approvals, and revalidation of the current state |
| datafocus.mcp.ontology-published-query-enabled | Published models and queries | Real committed versions and source authorization |
| datafocus.mcp.ontology-candidate-query-enabled | Candidate structured queries | Candidate ownership, exact versions, and read permission |
| datafocus.mcp.authoring.ontology-auto-publication-enabled | Authorizations related to auto-publish delegation | Valid 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.
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.
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_TOKENReading and querying
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.jsonFirst 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.
Embedding the ontology chat interface
Embed the human chat page into your business front end while preserving login and browser security boundaries.
<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
| Approach | User | Identity and results |
|---|---|---|
| Remote MCP | External Agent or service integration | OAuth Grant with structured tool receipts |
| Ontology chat iframe | Human end users | Original login state and chat interface |
| MCP Apps | MCP clients supporting extensions | Controlled resources and current tool results, not a public replacement for iframe login |
Integration acceptance checklist
Prove the full business chain on a real instance, rather than merely confirming that interfaces return 200.
- Discovery: obtain the actually supported versions, the current tool catalog, and built-in resources.
- Authorization: regular users see only the ontologies and business systems they are permitted to access; operations without the required scope are rejected.
- Table structure: real display names, columns, types, and permissions are complete.
- SQL: single-dimensional, multidimensional, JOIN, date, TopN, and truncation checks match actual business definitions.
- Knowledge: locating, full source text, and fact-citation eligibility are consistent; mixed questions have both data and document evidence.
- Search: model, init, suggestions, results, close, and buffer integrity checks pass.
- Optional analysis and reports: real multi-branch states, pagination, permission changes, and cancellation retain the original behavior.
- Optional modeling: candidates, plans, original approvals, actual application, and version queries verified stage by stage.
- Business actions: release hash, target version, approval, idempotency, and cross-Grant isolation verified.
- 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.
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.
| Resource | Content |
|---|---|
| reference/mcp-tool-catalog.json | 32 ontology-side and 8 business-side declared input schemas; some tools also include their original output schemas |
| reference/locales.json | 21 selectable options and 24 compatible locales, with UI terminology |
| reference/search-keywords.json | Static keyword catalogs for 17 explicit locales |
| reference/analysis-contract-manifest.json | Version 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
datafocus://manuals/etl-formulas/v1
datafocus://manuals/search-keyword-queries/v1
datafocus://manuals/etl-functions/v1
datafocus://manuals/search-keywords/v1resources/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.
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
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| names | array | Optional or conditionally required | Explicit names to look up, up to 32 per call. maxItems: 32 |
| action | string | Optional or conditionally required | Action name. Use a value from the current enum with that action's parameters. enum: list, read, keywords, functions, etl_requests |
| locale | string | Optional or conditionally required | Explicit static reference catalog locale, not the query's default language. |
| uri | string | Optional or conditionally required | Built-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
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| data | object | Optional or conditionally required | Raw action payload; refer to the capability discovery and action field tables. |
| action | string | Required | Action 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
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| data | object | Optional or conditionally required | Raw action payload; refer to the capability discovery and action field tables. |
| action | string | Required | Action name. Use a value from the current enum with that action's parameters. enum: capabilities |
dfc_ontologies
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| pageSize | integer | Optional or conditionally required | Items per page; subject to the schema maximum. minimum: 1; maximum: 100 |
| page | integer | Optional or conditionally required | Page number, starting from 1. minimum: 1 |
dfc_ontology_resources
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| resourceTypes | array | Optional or conditionally required | Set of resource types to return. |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| pageSize | integer | Optional or conditionally required | Items per page; subject to the schema maximum. minimum: 1; maximum: 100 |
| page | integer | Optional or conditionally required | Page number, starting from 1. minimum: 1 |
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
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| relationTypes | array | Optional or conditionally required | Relationship type filter. |
| depth | integer | Optional or conditionally required | Neighbor traversal depth. minimum: 1; maximum: 3 |
| sourceTypes | array | Optional or conditionally required | Source type filter. |
| query | object | Optional or conditionally required | Query text, or the exact versioned query object corresponding to action. |
| limit | integer | Optional or conditionally required | Maximum number of results to return. minimum: 1; maximum: 100 |
| action | string | Required | Action name. Use a value from the current enum with that action's parameters. enum: search, neighbors, published_model, published_query, candidate_query |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| nodeKey | string | Optional or conditionally required | Node key copied from the actual graph result. |
| keyword | string | Optional or conditionally required | Graph locator keyword; not the keyword-based data query syntax. |
| nodeTypes | array | Optional or conditionally required | Node type filter. |
dfc_ontology_query
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| routeLocators | array | Optional or conditionally required | The typed route locator issued by the server, copied in full. maxItems: 20 |
| topK | integer | Optional or conditionally required | Upper limit of recalled candidates; does not prove full coverage. minimum: 1; maximum: 20 |
| queryMode | string | Optional or conditionally required | Select the evidence query mode from the tool enum. enum: vector, hybrid, graph |
| fanoutPlan | object | Optional or conditionally required | Restricted branch retrieval plan, following the nested schema. |
| structuredPlan | object | Optional or conditionally required | Server-side contract binding plan for the full document table; this is not SQL. |
| knowledgeIds | array | Optional or conditionally required | Knowledge base ID from the actual knowledgeBindings. |
| query | string | Required | Query text, or the exact versioned query object corresponding to action. |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
dfc_knowledge_search
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| topK | integer | Optional or conditionally required | Upper limit of recalled candidates; does not prove full coverage. minimum: 1; maximum: 20 |
| minScore | number | Optional or conditionally required | Minimum match score. minimum: 0; maximum: 1 |
| knowledgeIds | array | Optional or conditionally required | Knowledge base ID from the actual knowledgeBindings. |
| query | string | Required | Query text, or the exact versioned query object corresponding to action. |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| assetIds | array | Optional or conditionally required | Currently permitted document asset ID. |
| retrievalStrategy | string | Optional or conditionally required | Retrieval strategy that is actually supported. enum: auto, hybrid_stage2 |
dfc_knowledge_detail
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| qdrantId | string / integer | Optional or conditionally required | Index identifier returned by the actual locate call. |
| pageNo | integer | Optional or conditionally required | Actual page or pagination page number. |
| evidenceId | string | Optional or conditionally required | Evidence ID returned by the same knowledge locate call. |
| action | string | Required | Action name. Use a value from the current enum with that action's parameters. enum: chunk, document, page_context |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| documentId | string / integer | Optional or conditionally required | Document ID for the same locator. |
| radius | integer | Optional or conditionally required | Adjacent page range. minimum: 0; maximum: 3 |
| chunkId | string | Optional or conditionally required | Actual chunk ID for the same locator. |
dfc_table
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| maxRows | integer | Optional or conditionally required | Upper limit on returned rows; this is not a client-side ranking range. minimum: 1; maximum: 200 |
| action | string | Required | Action name. Use a value from the current enum with that action's parameters. enum: detail, query |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| id | string | Optional or conditionally required | Real table resource ID, not a physical name or display name. |
| sql | string | Optional or conditionally required | A single read-only Doris SQL statement within the ontology scope, with explicit output columns. |
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
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| question | string | Required | Natural language question, or a compatible follow-up question. |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| language | string | Optional or conditionally required | Explicit answer or query locale; if omitted, the tool's own rules apply. |
| sessionId | string | Optional or conditionally required | Real session locator under the same Grant. |
dfc_analysis_refine
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| branchId | string | Optional or conditionally required | Structured branch locator issued by the server. |
| resultId | string | Required | Analysis result locator from the original response. |
| question | string | Optional or conditionally required | Natural language question, or a compatible follow-up question. |
| idempotencyKey | string | Required | Idempotency key, stably reused for the same logical operation. |
| change | object | Optional or conditionally required | Natural language change, or a typed filter_patch. |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| language | string | Optional or conditionally required | Explicit answer or query locale; if omitted, the tool's own rules apply. |
| sessionId | string | Required | Real session locator under the same Grant. |
| expectedRevision | integer | Required | Version precondition of the original result or business header; may be null when creating a question. minimum: 1 |
| visualId | string | Optional or conditionally required | Visualization locator bound to the branch. |
dfc_analysis_page
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| branchId | string | Required | Structured branch locator issued by the server. |
| resultId | string | Required | Analysis result locator from the original response. |
| pageNo | integer | Required | Actual page or pagination page number. minimum: 1; maximum: 10000 |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| pageSize | integer | Required | Items per page; subject to the schema maximum. minimum: 1; maximum: 100 |
| sessionId | string | Required | Real session locator under the same Grant. |
| expectedRevision | integer | Required | Version precondition of the original result or business header; may be null when creating a question. minimum: 1 |
dfc_analysis_result_get
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| resultId | string | Required | Analysis result locator from the original response. |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| sessionId | string | Required | Real session locator under the same Grant. |
dfc_analysis_cancel
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| resultId | string | Required | Analysis result locator from the original response. |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| sessionId | string | Required | Real session locator under the same Grant. |
dfc_analysis_close
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| sessionId | string | Required | Real session locator under the same Grant. |
dfc_report_create
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| goal | string | Required | Analysis goal for the report. |
| idempotencyKey | string | Required | Idempotency key, stably reused for the same logical operation. |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| language | string | Optional or conditionally required | Explicit answer or query locale; if omitted, the tool's own rules apply. |
| title | string | Optional or conditionally required | Optional report title. |
dfc_report_status
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| reportId | string | Required | Persistent report locator under the current Grant. |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
dfc_report_cancel
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| reportId | string | Required | Persistent report locator under the current Grant. |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
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
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| mode | string | Optional or conditionally required | QUERY or AUTHORING; capabilities are authorized separately. enum: QUERY, AUTHORING |
| instruction | string | Optional or conditionally required | User requirement text; must be consistent with the context and the submission. maxLength: 16000 |
| idempotencyKey | string | Optional or conditionally required | Idempotency key stably reused for the same logical operation. maxLength: 128 |
| action | string | Required | Action name. Use a value from the current enum with that action's parameters. enum: start, status, cancel |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| runId | string | Optional or conditionally required | Original task ID under the same ontology and Grant. |
| contractVersion | string | Required | Use 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
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| artifactType | string | Required | Artifact or ontology publication type that is actually enabled. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| scopeType | string | Optional or conditionally required | Resource scope type in the actual artifact contract. |
| ontologyId | string | Optional or conditionally required | Real ontology ID within the current authorization, preserved as a string. |
| projectId | string | Optional or conditionally required | The currently authorized project ID. |
| artifactId | string | Optional or conditionally required | Real ID of an existing artifact being edited. |
| instruction | string | Required | User requirement text; must be consistent with the context and the submission. |
| variables | object | Optional or conditionally required | Variable object provided according to the returned contract. |
| previewInput | object | Optional or conditionally required | Bounded preview input provided according to the contract. |
| viewport | object | Optional or conditionally required | Display viewport required by the contract. |
dfc_ontology_table_schema
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| sourceAssetRef | string | Required | A registered structured asset reference, e.g. table:123. |
| fields | array | Required | Fields of the current source with optional explicit type declarations. minItems: 1; maxItems: 64 |
dfc_artifact_preview
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| proposalId | string | Required | The original candidate ID created under the current Grant. |
| candidateHash | string | Required | The exact hash of the original server-side candidate. |
| previewInput | object | Required | Bounded preview input provided according to the contract. |
dfc_artifact_status
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| proposalId | string | Optional or conditionally required | The original candidate ID created under the current Grant. |
| planId | string | Optional or conditionally required | The immutable apply plan ID. |
dfc_artifact_plan
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| proposalId | string | Required | The original candidate ID created under the current Grant. |
| candidateHash | string | Required | The exact hash of the original server-side candidate. |
| expectedTargetVersion | integer | Required | The current real target version precondition. minimum: 0 |
| idempotencyKey | string | Required | Idempotency key, stably reused for the same logical operation. |
dfc_artifact_apply
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| planId | string | Required | The immutable apply plan ID. |
| planHash | string | Required | The hash returned with the original plan. |
| approvalToken | string | Required | The approval material originally issued by the server; do not generate it yourself. |
| idempotencyKey | string | Required | Idempotency key, stably reused for the same logical operation. |
dfc_artifact_submit
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| Configuration 1 / artifactType | string | Required | Artifact or ontology publication type that is actually enabled. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| Configuration 1 / scopeType | string | Optional or conditionally required | Resource scope type in the actual artifact contract. |
| Configuration 1 / ontologyId | string | Optional or conditionally required | Real ontology ID within the current authorization, preserved as a string. |
| Configuration 1 / projectId | string | Optional or conditionally required | The currently authorized project ID. |
| Configuration 1 / artifactId | string | Optional or conditionally required | Real ID of an existing artifact being edited. |
| Configuration 1 / instruction | string | Required | User requirement text; must be consistent with the context and the submission. |
| Configuration 1 / variables | object | Optional or conditionally required | Variable object provided according to the returned contract. |
| Configuration 1 / previewInput | object | Optional or conditionally required | Bounded preview input provided according to the contract. |
| Configuration 1 / viewport | object | Optional or conditionally required | Display viewport required by the contract. |
| Configuration 1 / contractVersion | string | Required | Use the exact contract version that is actually supported. |
| Configuration 1 / contextHash | string | Required | The full context hash returned by context. |
| Configuration 1 / baseArtifactHash | string | Required | The base artifact hash returned by context. |
| Configuration 1 / baseArtifactVersion | integer | Required | The base version returned by context. minimum: 0 |
| Configuration 1 / candidate | object | Required | A candidate object conforming to the currently returned contract. |
| Configuration 1 / clientRequestId | string | Required | The client idempotency key stably used for the current candidate request. |
| Configuration 2 / artifactType | string | Required | Artifact or ontology publication type that is actually enabled. enum: ONTOLOGY_RELEASE |
| Configuration 2 / contractVersion | string | Required | Use 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 / ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| Configuration 2 / candidateHash | string | Required | The exact hash of the original server-side candidate. |
| Configuration 2 / workspaceId | string | Required | The actual candidate workspace coordinates. |
| Configuration 2 / workspaceRevision | string | Required | The exact candidate version; do not use latest. |
| Configuration 2 / releases | object | Required | Exact version selections, provided as the ontology publication contract requires. |
| Configuration 2 / selection | object | Required | Provides only explicit business selection coordinates; does not provide permission or completion proof. |
| Configuration 2 / idempotencyKey | string | Required | Idempotency key, stably reused for the same logical operation. |
| Configuration 3 / Configuration 1 / artifactType | string | Required | Artifact or ontology publication type that is actually enabled. enum: ONTOLOGY_RELEASE |
| Configuration 3 / Configuration 1 / contractVersion | string | Required | Use the exact contract version that is actually supported. enum: ontology-workspace-create-mcp-submit-v1 |
| Configuration 3 / Configuration 1 / ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| Configuration 3 / Configuration 1 / workspaceId | string | Required | The actual candidate workspace coordinates. |
| Configuration 3 / Configuration 1 / resources | array | Required | The original model declaration compiled by the server. minItems: 1 |
| Configuration 3 / Configuration 1 / idempotencyKey | string | Required | Idempotency key, stably reused for the same logical operation. |
| Configuration 3 / Configuration 2 / artifactType | string | Required | Artifact or ontology publication type that is actually enabled. enum: ONTOLOGY_RELEASE |
| Configuration 3 / Configuration 2 / contractVersion | string | Required | Use the exact contract version that is actually supported. enum: ontology-workspace-create-mcp-submit-v2 |
| Configuration 3 / Configuration 2 / ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| Configuration 3 / Configuration 2 / workspaceId | string | Required | The actual candidate workspace coordinates. |
| Configuration 3 / Configuration 2 / resources | array | Required | The original model declaration compiled by the server. minItems: 1 |
| Configuration 3 / Configuration 2 / idempotencyKey | string | Required | Idempotency key, stably reused for the same logical operation. |
| Configuration 3 / Configuration 2 / releaseSelections | object | Required | The exact releaseId of each published reference and its dependency closure. |
| Configuration 4 / artifactType | string | Required | Artifact or ontology publication type that is actually enabled. enum: ONTOLOGY_RELEASE |
| Configuration 4 / contractVersion | string | Required | Use the exact contract version that is actually supported. enum: ontology-initial-activation-retirement-submit-v1 |
| Configuration 4 / ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| Configuration 4 / domainRid | string | Required | The real business domain RID. |
| Configuration 4 / consumerScopes | array | Required | The exact consumer scope allowed by the server. minItems: 1; maxItems: 256 |
| Configuration 4 / idempotencyKey | string | Required | Idempotency key, stably reused for the same logical operation. |
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
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| request | object | Required | The original business input request; follows the complete nested schema. |
| idempotencyKey | string | Required | An 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
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| idempotencyKey | string | Required | An idempotency key that is stably reused for the same logical operation. minLength: 1; maxLength: 128 |
| ontologyId | string | Required | Real 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
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| questionRevision | $ref | Required | The explicit version of the question to be confirmed in this operation. |
| idempotencyKey | $ref | Required | Idempotency key, stably reused for the same logical operation. |
| originalInputKey | $ref | Required | The idempotency key corresponding to the original knowledge input. |
| ontologyId | string | Required | Real ontology ID within the current authorization, preserved as a string. |
| validUntil | $ref | Required | The end of the question's validity window, in UTC. |
| expectedRevision | oneOf | Required | The version precondition of the original result or business header; may be null when creating a question. |
| validFrom | $ref | Required | The 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
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| domainRevisionId | string | Required | The exact business domain version. minLength: 1; maxLength: 128 |
| idempotencyKey | string | Required | An idempotency key that is stably reused for the same logical operation. minLength: 1; maxLength: 128 |
| businessSystemId | string | Required | The real business system ID. minLength: 1 |
| ontologyId | string | Required | Actual ontology ID within this authorization, preserved as a string. minLength: 1 |
| domainRid | string | Required | Actual 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.
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
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| systemId | string / integer | Required | The system ID permitted by this business Grant. |
dfb_query
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| systemId | string / integer | Required | The system ID permitted by this business Grant. |
| queryKey | string | Required | The published query key returned by describe. |
| objectKey | string | Optional or conditionally required | Published object key. |
| pageSize | integer | Optional or conditionally required | Items per page; subject to the schema maximum. minimum: 1; maximum: 100 |
| page | integer | Optional or conditionally required | Page number, starting from 1. minimum: 1 |
| state | string | Optional or conditionally required | Business status filter or server-side status. |
dfb_record
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| recordId | string / integer | Required | The ID of the business record currently allowed to be read. |
| systemId | string / integer | Required | The system ID permitted by this business Grant. |
dfb_work_items
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| systemId | string / integer | Required | The system ID permitted by this business Grant. |
dfb_action_plan
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| expectedRecordVersion | integer | Optional or conditionally required | The current optimistic-lock version of the target record. minimum: 1 |
| systemId | string / integer | Required | The system ID permitted by this business Grant. |
| commandType | string | Required | The command type in the published contract. |
| canonicalIrHash | string | Required | The hash of the currently published canonical IR. |
| releaseId | string / integer | Required | The actual published contract version ID. |
| payload | object | Required | The payload conforming to the current command contract in describe. |
| releaseHash | string | Required | The actual published contract hash. |
| targetRecordId | string / integer | Optional or conditionally required | The actual target record to be operated on. |
| agentManifestHash | string | Required | The actual Agent capability manifest hash. |
| planIdempotencyKey | string | Required | The stable idempotency key of the business plan. |
dfb_action_status
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| actionPlanId | string / integer | Required | The action plan ID owned by the current business Grant. |
dfb_action_execute
| Parameter | Type | Requirement | Meaning and range |
|---|---|---|---|
| approvalToken | string | Optional or conditionally required | The approval material originally issued by the server; do not generate it yourself. |
| actionPlanId | string / integer | Required | The action plan ID owned by the current business Grant. |