CloverDX Model Context Protocol (MCP) API | CloverDX 7.6.2 Documentation

> >

14. CloverDX Model Context Protocol (MCP) API

MCP (Model Context Protocol) is an emerging standard that enables AI agents to interact with external services and data sources. It provides a standardized way for AI models to access tools, resources, and context from various applications, allowing them to perform tasks beyond their base capabilities.

CloverDX MCP Server exposes a comprehensive set of tools that enable AI agents to fully interact with CloverDX:

Sandbox Management: browse, read, write, and organize files within CloverDX sandboxes.
Job Execution: run graphs and jobflows, wait for results, monitor status, and abort running jobs.
Graph Editing: create and modify CloverDX graphs and jobflows using structured XML operations.
Server Diagnostics: access server logs, performance metrics, and internal system database.
Component Reference: discover and configure CloverDX component types.
Knowledge Base: access the CloverDX knowledge library and manage project-scoped knowledge entries.
External Databases: query and inspect databases accessible via JDBC.
Support: report issues directly to the CloverDX Support Portal.

MCP API is available at:

http(s)://[cloverdx-server-host]:[port]/clover/mcp/all/v1

Besides this main endpoint, each tool group has an endpoint of its own. They all serve the same tools; what differs is how much of the catalogue a client connected to them sees:

Endpoint Serves

Endpoint	Serves
`/clover/mcp/all/v1`	Everything the caller is allowed to use, from every group.
`/clover/mcp/diagnostic/v1`	The diagnostic group only.
`/clover/mcp/authoring/v1`	The authoring group only.
`/clover/mcp/data-manager/v1`	The Data Manager group only: data sets, their columns and their rows. Offered only where a licensed Data Manager is configured locally on this Server, to callers holding both the Use AI Data Manager MCP tools and the Access to Data Manager app permission. Not served by a Server that proxies MCP to another Server.

/clover/mcp/all/v1

Everything the caller is allowed to use, from every group.

/clover/mcp/diagnostic/v1

The diagnostic group only.

/clover/mcp/authoring/v1

The authoring group only.

/clover/mcp/data-manager/v1

The Data Manager group only: data sets, their columns and their rows. Offered only where a licensed Data Manager is configured locally on this Server, to callers holding both the Use AI Data Manager MCP tools and the Access to Data Manager app permission. Not served by a Server that proxies MCP to another Server.

The older URL /clover/mcp/mcp still works and serves the same as /clover/mcp/all/v1, but it is deprecated. Configure new clients with the versioned one.

MCP Tools Reference

The following tables list all MCP tools available in CloverDX Server, grouped by functional area. The Access column indicates whether a tool is available in read-only mode, the Permission column names the permission a caller needs to use the tool. To configure which tools the Server exposes, see MCP tools permissions configuration. Tools that work with sandbox files additionally honour the sandbox file access configuration, which can restrict them to files matching administrator-defined patterns.

Tool groups and permissions

Independently of the functional areas below, every tool belongs to a tool group, and the group decides which permission its caller needs:

Use AI Diagnostic MCP tools covers the tools for looking into a running Server – listing jobs, their status, logs and tracking, server and performance logs, the system database, browsing and reading sandbox files, and reporting an issue to CloverDX support. These tools need no seat.
Use AI Authoring MCP tools covers the tools that build or change a solution – editing sandbox files, graph editing, job execution, the component reference and the knowledge base. A user holding this permission occupies one AI Authoring seat – the same seat that licenses the AI Assistant in the Designer.
Use AI Data Manager MCP tools covers the tools working with Data Manager data sets. It needs Access to Data Manager app as well, and the group is offered only where a licensed Data Manager is configured locally on the Server – see Data Manager in the AI Assistant. A user holding this permission occupies one AI Authoring seat; a user holding it together with Use AI Authoring MCP tools occupies one seat, not two.

Granting Use all MCP tools grants all three permissions. See MCP permissions and AI Authoring seats for the whole model.

The authoring and the Data Manager group are not available through an MCP proxy.

Sandbox Tools

Tools for browsing and managing files inside CloverDX sandboxes.

Table 40. Sandbox Tools
Tool	Description	Access	Permission
`sandbox_list`	List all sandboxes accessible to the current user.	Read	Use AI Diagnostic MCP tools
`sandbox_get_detail`	Get detailed information about a specific sandbox — root path, owner, distribution type, and suspension state.	Read	Use AI Authoring MCP tools
`sandbox_list_files`	List files and folders inside a sandbox directory.	Read	Use AI Diagnostic MCP tools
`sandbox_find_file`	Recursively search for files in a sandbox using wildcard patterns (`*`, `?`).	Read	Use AI Diagnostic MCP tools
`sandbox_read_file`	Read the text content of a file stored in a sandbox. Supports optional line range and encoding detection.	Read	Use AI Diagnostic MCP tools
`sandbox_analyze_file`	Extract or profile content from binary and structured files: extract text from PDF documents (`extract_pdf`), read Excel sheets (`extract_excel`), or profile CSV files for data-quality statistics (`profile_csv`).	Read	Use AI Authoring MCP tools
`sandbox_list_assets`	List reusable shared assets in a sandbox: metadata definitions (`.fmt`), connection configurations (`.cfg`), lookup tables (`.cfg`, or older `.lkp`), CTL files, sequences, and parameter files.	Read	Use AI Authoring MCP tools
`sandbox_get_workspace_parameters`	Resolve sandbox workspace parameter values such as `${DATAIN_DIR}` and `${CONN_DIR}` with server-side defaults and system property overlays.	Read	Use AI Authoring MCP tools
`sandbox_grep_files`	Search file contents across one or more sandboxes using literal strings or regular expressions.	Read	Use AI Diagnostic MCP tools
`sandbox_write_file`	Create or update a file in a sandbox. Supports overwrite, append, insert, and line-range replace modes.	Write	Use AI Authoring MCP tools
`sandbox_patch_file`	Apply targeted anchor-based patches to a text file in a sandbox without replacing the whole file. Preferred for editing CTL, SQL, and properties files.	Write	Use AI Authoring MCP tools
`sandbox_copy_file`	Copy a file within or across sandboxes. Overwrites the destination if it already exists.	Write	Use AI Authoring MCP tools
`sandbox_rename_file`	Rename a file within its current directory in a sandbox.	Write	Use AI Authoring MCP tools
`sandbox_delete_file`	Delete a file from a sandbox. This operation is irreversible.	Write	Use AI Authoring MCP tools
`sandbox_create_directory`	Create a new directory in a sandbox.	Write	Use AI Authoring MCP tools
`sandbox_delete_directory`	Delete a directory from a sandbox, including all its contents. This operation is irreversible.	Write	Use AI Authoring MCP tools
`sandbox_git`	Perform git version-control operations on a sandbox repository: commit, log, diff, status, branch management, stash, and more.	Write	Use AI Authoring MCP tools

Job Tools

Tools for running, monitoring, and debugging graph and jobflow executions.

Table 41. Job Tools
Tool	Description	Access	Permission
`job_list`	List recent graph and jobflow executions from the execution history, with optional filtering by sandbox, job file, and status.	Read	Use AI Diagnostic MCP tools
`job_get_status`	Get the current execution status of a job run without fetching the full log.	Read	Use AI Diagnostic MCP tools
`job_get_log`	Retrieve the full execution log for a job run (up to 1 MiB).	Read	Use AI Diagnostic MCP tools
`job_get_tracking`	Get per-phase, per-node, and per-port execution tracking data, including record and byte counts for each component.	Read	Use AI Diagnostic MCP tools
`job_get_edge_debug_data`	Fetch sample records that flowed through a specific graph edge during a debug-enabled run.	Read	Use AI Authoring MCP tools
`job_await`	Wait for a running job to reach a terminal state (finished, error, or aborted). Safe to re-call on timeout.	Read	Use AI Authoring MCP tools
`job_validate`	Validate a graph or jobflow file using the server-side configuration checker. Reports errors, warnings, and info messages.	Read	Use AI Authoring MCP tools
`job_plan`	Record a structured graph design plan and validate its internal consistency before writing any XML.	Read	Use AI Authoring MCP tools
`job_run`	Submit a graph or jobflow for asynchronous execution. Returns a run ID immediately.	Write	Use AI Authoring MCP tools
`job_abort`	Abort a running graph or jobflow execution. Also terminates any child jobs it spawned.	Write	Use AI Diagnostic MCP tools

Graph Editing Tools

Tools for inspecting and modifying CloverDX graphs (.grf), jobflows (.jbf), and subgraphs (.sgrf) via the XML DOM, and for validating the CTL code that goes into them.

Table 42. Graph Editing Tools
Tool	Description	Access	Permission
`graph_resolve_edge_schemas`	Resolve the record schema (field names, types, nullability) that would flow along each edge of a graph at runtime, including propagated schemas.	Read	Use AI Authoring MCP tools
`graph_list_elements`	List specific element types defined in a job file: metadata records, lookup tables, dictionaries, sequences, or nodes (components with their complete configuration and, optionally, the metadata of their ports). Several specific elements can be requested in one call.	Read	Use AI Authoring MCP tools
`graph_element_lineage`	Explain selected components of a job file locally: how each produces its output fields (CTL, variables, functions) and affects records, stopping at its input ports. Several components in one call, each with an analysis status. The job is initialized on the server, not run; the caller needs the execute permission on its sandbox, as for a run.	Read	Use AI Authoring MCP tools
`graph_lineage`	Trace the data lineage of a graph: for each field written by its targets, the source fields, the transformations (CTL code), and the joins, filters, routing, and aggregations that decide which records reach the target. The graph is initialized on the server, not run; the caller needs the execute permission on its sandbox, as for a run, and on the sandbox of every subgraph traced into. Can trace into subgraphs, resolve DB columns from database catalog files (written by the DBCatalogExport component), and return a summary, standard, or full level of detail.	Read	Use AI Authoring MCP tools
`graph_jobflow_lineage`	Trace what happens when a jobflow runs: the jobs it runs (child jobflows traced with the parameter values passed to them, graphs listed with the `graph_lineage` call tracing them), in which order and how many times, under which conditions, the parameters and dictionary values passed to each child job and their sources, the files and tables touched, and what a failure of each step leads to. The jobflow is initialized on the server, not run; the caller needs the execute permission on its sandbox, as for a run, and on the sandbox of every child job traced. How the jobflow is started (listeners, schedules) is not analysed.	Read	Use AI Authoring MCP tools
`ctl_validate`	Validate standalone CTL2 code against explicit port metadata, without a job file. Reports compilation and metadata problems with their position in the code, and checks the entry functions the given component type requires.	Read	Use AI Authoring MCP tools
`graph_edit_properties`	Set or update attribute values, CTL transformation code, or metadata record definitions on existing graph elements. Supports bulk edits and dry-run preview.	Write	Use AI Authoring MCP tools
`graph_edit_structure`	Add, delete, or move whole structural elements in a job — nodes, edges, phases, metadata definitions, connections, and more. Supports dry-run preview.	Write	Use AI Authoring MCP tools
`graph_layout`	Re-arrange every component of a job file into a deterministic left-to-right layout. Job files are laid out automatically on every write, keeping the positions a human set; this tool re-arranges the whole file regardless. Supports dry-run preview.	Write	Use AI Authoring MCP tools

Component Tools

Tools for discovering and understanding CloverDX component types.

Table 43. Component Tools
Tool	Description	Access	Permission
`component_list`	Browse and search available CloverDX component types by name, category, or keyword.	Read	Use AI Authoring MCP tools
`component_get_info`	Get detailed configuration information for a component type: input/output ports, properties, required settings, and metadata propagation rules.	Read	Use AI Authoring MCP tools
`component_get_guide`	Fetch the in-depth reference guide for a component, including configuration examples, CTL mapping syntax, and known pitfalls.	Read	Use AI Authoring MCP tools

Server Tools

Tools for inspecting CloverDX Server state, logs, and internal system database.

Table 44. Server Tools
Tool	Description	Access	Permission
`server_deployment`	Get a snapshot of the running CloverDX Server environment — JVM, OS, memory, cluster topology, and configuration. Can also return the official support matrix.	Read	Use AI Diagnostic MCP tools
`server_logs_search`	Search server log entries by time range and regular expression pattern. Supports multiple log appenders: main server log, cluster, user actions, job queue, data services, and others.	Read	Use AI Diagnostic MCP tools
`server_perf_logs_query`	Execute SQL queries (Apache Calcite dialect) against the server performance log. Returns time-series CPU, memory, GC, and I/O metrics sampled every 3 seconds.	Read	Use AI Diagnostic MCP tools
`server_db_get_schema`	Retrieve the table and column schema of the CloverDX internal system database (execution history, users, sandboxes, schedules, and other server-managed records).	Read	Use AI Diagnostic MCP tools
`server_db_execute_query`	Execute a read-only SQL SELECT query against the CloverDX internal system database.	Read	Use AI Diagnostic MCP tools

External Database Tools

Tools for interacting with external databases accessible via JDBC.

Table 45. External Database Tools
Tool	Description	Access	Permission
`db_get_schema`	Query schemas, tables, or columns of any database accessible via JDBC — using either a saved connection configuration file or inline connection properties. Supports all major databases (PostgreSQL, Oracle, MSSQL, MySQL, and others). Can also answer from a database catalog file written by the DBCatalogExport component, without connecting; the answer then says how old the catalog is and which schemas it covers.	Read	Use AI Authoring MCP tools
`db_execute_query`	Execute SQL (SELECT, DML, or DDL) against any database accessible via JDBC. Results are returned as JSON or delimited text.	Write	Use AI Authoring MCP tools

Knowledge Tools

Tools for accessing the knowledge space – the built-in CloverDX knowledge library, the customer’s own company entries and the project-scoped entries – and for managing the project-scoped ones.

Table 46. Knowledge Tools
Tool	Description	Access	Permission
`knowledge_list_resources`	List all static reference documents exposed as MCP resources by the installed CloverDX knowledge library, including graph XML reference, CTL language reference, and component guides.	Read	Use AI Authoring MCP tools
`knowledge_read_resource`	Fetch the content of a specific knowledge resource by its URI.	Read	Use AI Authoring MCP tools
`kb_search`	Search the whole knowledge space by keyword: the entries shipped in the CloverDX knowledge library (`platform/`), the customer’s own entries (`company/`) and the project entries (`project/`). Hits are filtered by the agent role the caller declares and each one carries the path to read it with.	Read	Use AI Authoring MCP tools
`kb_read`	Read the body of one knowledge entry by its `<subtree>/[<topic>/]<name>` path, e.g. `platform/guides/joiner-selection`.	Read	Use AI Authoring MCP tools
`kb_store`	Store or update a knowledge entry in the `project/` subtree, the only writable one. Used by AI agents to persist project-specific facts (business rules, conventions, validated findings) across sessions. Requires `sandboxCode` and `projectName`.	Write	Use AI Authoring MCP tools
`kb_delete`	Delete one entry from the `project/` subtree. Requires `sandboxCode` and `projectName`.	Write	Use AI Authoring MCP tools
`knowledge_context_get`	Return what one agent role sees of the knowledge space: the pinned rules addressed to that role and the index of entries visible to it. The assistant host calls it when it composes a system prompt; other clients can call it to preview a role’s view.	Read	Use AI Authoring MCP tools

Agent Utility Tools

Tools used by AI agents to manage session state and workflow guidance.

Table 47. Agent Utility Tools
Tool	Description	Access	Permission
`note_read`	Read notes from the session-scoped working memory.	Read	Use AI Authoring MCP tools
`think`	Log explicit reasoning before taking an action. Helps AI agents plan component selection, graph edits, and error diagnostics.	Read	Use AI Authoring MCP tools
`task_workflow_get`	Get step-by-step procedural instructions for a CloverDX task type: creating a graph, editing a graph, creating a jobflow, or validating and running a job.	Read	Use AI Authoring MCP tools
`note_add`	Append a note to a named section in session-scoped working memory. Notes are lost when the MCP session ends.	Write	Use AI Authoring MCP tools
`note_clear`	Clear notes from session-scoped working memory — either a specific section or all sections.	Write	Use AI Authoring MCP tools
`report_support_issue`	Report a problem to the CloverDX Support Portal. Optionally attaches a diagnostic support package containing logs and configuration details.	Write	Use AI Diagnostic MCP tools

Data Manager Tools

Tools for discovering and administering Data Manager data sets and their rows. Transactional data sets (rows staged on their way to a target system) and reference data sets (managed lookup tables) have separate tools, because their settings and statistics differ; only the search covers both. Every tool but the search answers with the JSON of the Data Manager REST API without @self, and shows a caller only the data sets they may see in Data Manager; a writing tool is subject to the same data set permissions as the REST API. The tools are offered only where a licensed Data Manager is configured locally on this Server. The writing tools offer nothing the REST API does not; two of its bulk row operations, purge and approveAll, are left out because they act on a whole data set without naming rows.

Table 48. Data Manager Tools
Tool	Description	Access	Permission
`dataset_transactional_list`	List the transactional data sets the caller may see, with code, name, category, owner, enabled flag and row statistics. `detail=full` adds the layout and settings of each.	Read	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_transactional_get`	Describe one transactional data set: layout (columns with technical names and types), permissions, connected data apps, retention and batch key, statistics.	Read	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_reference_list`	List the reference data sets the caller may see, with code, name, category, owner, enabled flag and row statistics. `detail=full` adds the layout and settings of each.	Read	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_reference_get`	Describe one reference data set: layout (columns with technical names and types), lookup key, effective dates setting, permissions, connected data apps, statistics.	Read	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_search`	Find data sets of both types by code, name, description, category, owner, or a column’s label or technical name. `queries` holds alternative wordings; a wording matches when each of its words occurs, ignoring case, in some searched value. Optional `fields`, `type` and `category` narrow the search. Returns the matching data sets with their type and what matched in each.	Read	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_transactional_read_rows`	Read rows of a transactional data set with the filter, row ids, audit and error filters, sort order and paging of the REST row search; at most 200 rows per call, `detail=full` wraps each cell with its last modification and message. Needs the editor permission on the data set.	Read	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_transactional_read_row_audit`	Read the change history of one transactional row, latest change first, optionally narrowed to one column. Needs the editor permission on the data set.	Read	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_reference_read_rows`	Read rows of a reference data set with the filter, row ids, audit filter, change state filter (`published` by default), sort order and paging of the REST row search; at most 200 rows per call.	Read	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_reference_read_row_audit`	Read the change history of one reference row, latest change first, optionally narrowed to one column. Needs the editor permission on the data set.	Read	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_transactional_create`	Create a transactional data set from a definition in the REST API’s JSON: name, columns, permissions, connected data apps, retention and batch key. Needs the server permission to create data sets.	Write	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_transactional_update`	Replace the definition of a transactional data set with a complete new one; columns keep their data by `@id`. Needs the admin permission on the data set.	Write	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_transactional_set_enabled`	Enable or disable a transactional data set. Needs the admin permission on the data set.	Write	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_transactional_delete`	Delete a transactional data set with its rows and change history. Needs the admin permission on the data set.	Write	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_transactional_insert_rows`	Insert up to 200 rows into a transactional data set, as a job load would. Needs the editor permission on the data set.	Write	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_transactional_update_rows`	Change the content of up to 200 rows of a transactional data set, with a strict or controlled error policy; system columns, the status among them, are refused. Needs the editor permission on the data set.	Write	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_transactional_apply_row_action`	Apply approve, unapprove, edit, unedit, delete or undelete to rows given by id. Approving and unapproving need the approver permission, the rest the editor permission on the data set.	Write	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_transactional_commit_rows`	Mark approved rows as committed, the state the unload to the target system takes them in, stopping at the first failure or listing the failures. Needs the approver permission on the data set.	Write	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_reference_create`	Create a reference data set from a definition in the REST API’s JSON: name, columns, lookup key, effective dates, permissions and connected data apps. Needs the server permission to create data sets.	Write	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_reference_update`	Replace the definition of a reference data set with a complete new one; columns keep their data by `@id`. Needs the admin permission on the data set.	Write	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_reference_set_enabled`	Enable or disable a reference data set. Needs the admin permission on the data set.	Write	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_reference_delete`	Delete a reference data set with its rows, pending changes and change history. Needs the admin permission on the data set.	Write	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_reference_insert_rows`	Insert up to 200 rows into a reference data set as pending changes, with a strict or controlled error policy. Needs the editor permission on the data set.	Write	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_reference_update_rows`	Change the content of up to 200 rows of a reference data set as pending changes, with a strict or controlled error policy; system columns other than `_enabled`, `_valid_from` and `_valid_to` are refused. Needs the editor permission on the data set.	Write	Use AI Data Manager MCP tools + Access to Data Manager app
`dataset_reference_apply_row_action`	Apply approve, discardChanges, enable, disable, delete or duplicate to rows given by id. Approving needs the approver permission, the rest the editor permission on the data set.	Write	Use AI Data Manager MCP tools + Access to Data Manager app