> For the complete documentation index, see [llms.txt](https://docs.ovaledge.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ovaledge.com/release8.2/mcp-server/ovaledge-mcp-api-reference-guide.md). # OvalEdge MCP API Reference Guide This article provides the technical reference for the OvalEdge Model Context Protocol (MCP) APIs that enable AI assistants and external applications to securely interact with the OvalEdge platform. The APIs support a broad range of metadata discovery, governance, data quality, lineage, access management, and documentation capabilities through standardized REST endpoints. Each API reference includes the endpoint details, supported MCP tool, authentication requirements, request parameters, example requests and responses, HTTP status codes, and implementation notes. Together, these APIs enable developers to search and retrieve catalog metadata, manage governance artifacts, evaluate data quality recommendations, query access permissions, explore lineage and relationships, and perform governed updates while respecting OvalEdge role-based access controls and security policies. ## API Details ### Search Catalog | Field | Value | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Search Catalog | | API Description | Searches the OvalEdge catalog using a keyword and optional semantic search. Supports filtering by connection, schema, object type, owner, steward, tags, glossary terms, custom fields, classifications, and data products. Returns catalog assets that match the search criteria and the user's access permissions. | | Method | GET | | Endpoint URL | /api/v1/mcp/search-catalog | | Method Name | McpApi.searchCatalog → McpApiService.searchCatalog | | MCP Tool | search\_catalog\_assets | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Query Parameters** | Parameter | Required | Default | Description | | --------------- | -------- | ------- | ------------------------------------------------------------------------------------------- | | searchTerms | Yes | — | Keywords to search. Accepts a JSON array or comma-separated values. | | contextQuery | No | — | Natural language context used for semantic/vector search. | | page | No | 1 | Page number. | | limit | No | 20 | Maximum number of results returned. | | connectionName | No | — | Filters assets by connection. | | serverType | No | — | Filters by connection technology such as Snowflake, MySQL, Redshift, Oracle, or SQL Server. | | schemaName | No | — | Filters assets by schema. | | owner | No | — | Filters assets by owner. | | steward | No | — | Filters assets by steward. | | custodian | No | — | Filters assets by custodian. | | objectType | No | — | Filters by asset type. | | tags | No | — | Filters by tag names. Accepts JSON array or comma-separated values. | | terms | No | — | Filters by glossary terms. | | customFields | No | — | Filters by custom field values. | | dataProducts | No | — | Filters by data product names. | | classifications | No | — | Filters by classification names. | #### **Supported Object Types** * oetable * oecolumn * oefile * glossary * oetag #### **Example Request** ``` GET /api/v1/mcp/search-catalog? searchTerms=["customer","revenue"]& contextQuery=customer revenue metrics& page=1& limit=20 ``` #### **Example Response** ```json { "ok": true, "message": null, "data": { "page": 1, "limit": 20, "totalResults": 125, "results": [ { "objectId": 12345, "objectType": "oetable", "objectName": "CUSTOMERS", "fullyQualifiedName": "Snowflake.SALES.CUSTOMERS", "businessDescription": "Customer master information", "redirectUrl": "https://.../nav/..." } ] } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | ----------------------------- | | 200 | Search completed successfully | | 400 | Invalid request parameters | | 401 | Authentication failed | | 403 | Access denied | | 500 | Internal server error | Notes * Supports both keyword (BM25) and semantic search. * Results are filtered according to the user's catalog permissions. * List parameters accept JSON arrays or comma-separated values. ### Object Details | Field | Value | | --------------- | -------------------------------------------------------------------------------------------------------------------------- | | API Name | Get Object Details | | API Description | Retrieves detailed metadata for a catalog object using either its Fully Qualified Name (FQN) or Object ID and Object Type. | | Method | GET | | Endpoint URL | /api/v1/mcp/object-details | | Method Name | McpApi.getObjectDetails → McpApiService.getObjectDetails | | MCP Tool | catalog\_asset\_details | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Query Parameters** | Parameter | Required | Description | | ------------------ | ----------- | ------------------------------------------------------------------------------- | | fullyQualifiedName | Conditional | Fully Qualified Name of the asset. Cannot be combined with objectId/objectType. | | objectId | Conditional | Internal OvalEdge object identifier. | | objectType | Conditional | Asset type corresponding to objectId. | #### **Object Resolution Rules** Use exactly one of the following: 1. fullyQualifiedName OR 2. objectId + objectType #### **Supported Object Types** * oetable * oecolumn * oefile * oefilecolumn * glossary * oetag * oechart * chartchild #### **Example Request** ``` GET /api/v1/mcp/object-details? objectId=12345& objectType=oetable ``` #### **Example Response** ```json { "ok": true, "message": null, "data": { "objectId": 12345, "objectType": "oetable", "objectName": "CUSTOMERS", "fullyQualifiedName": "Snowflake.SALES.CUSTOMERS", "businessDescription": "Customer master table", "technicalDescription": "Stores customer profile data", "owner": "Data Engineering", "steward": "John Smith" } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | ------------------------- | | 200 | Object found | | 400 | Invalid object identifier | | 404 | Object not found | | 500 | Internal server error | Notes * Either Fully Qualified Name or Object ID/Object Type must be provided. * Mixing both lookup modes is not supported. ### Data Sources | Field | Value | | --------------- | ------------------------------------------------------------------------------------------------------------------------------ | | API Name | Get Data Sources | | API Description | Retrieves the list of data source connections available to the authenticated user. Results are returned in a paginated format. | | Method | GET | | Endpoint URL | /api/v1/mcp/data-sources | | Method Name | McpApi.getDataSources → McpApiService.getDataSources | | MCP Tool | search\_catalog\_assets | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Query Parameters** | Parameter | Required | Default | Description | | --------- | -------- | ------- | -------------------------- | | page | No | 1 | Page number | | limit | No | 20 | Number of records per page | #### **Example Request** ``` GET /api/v1/mcp/data-sources?page=1&limit=20 ``` #### **Example Response** ```json { "ok": true, "data": { "page": 1, "limit": 20, "total": 58, "connections": [ { "connectionId": 101, "connectionName": "Snowflake Production", "serverType": "Snowflake" } ] } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | --------------------- | | 200 | Success | | 401 | Authentication failed | | 500 | Internal server error | Notes * Only connections accessible to the authenticated user are returned. * Supports pagination. ### Column Profile | Field | Value | | --------------- | ------------------------------------------------------------------------------------------------------------- | | API Name | Get Column Profile | | API Description | Retrieves profiling statistics for a table or file object, including data distribution and profiling metrics. | | Method | GET | | Endpoint URL | /api/v1/mcp/column-profile | | Method Name | McpApi.getColumnProfile → McpApiService.getColumnProfile | | MCP Tool | column\_profile\_statistics | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Query Parameters** | Parameter | Required | Description | | ---------- | -------- | --------------------------------- | | objectId | Yes | OvalEdge object identifier | | objectType | Yes | Supported values: oetable, oefile | #### **Example Request** ``` GET /api/v1/mcp/column-profile? objectId=12345& objectType=oetable ``` #### **Example Response** ```json { "ok": true, "data": { "columns": [ { "columnName": "EMAIL", "dataType": "VARCHAR", "nullPercentage": 0.5, "distinctValues": 50231 } ] } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | ------------------- | | 200 | Success | | 400 | Invalid object type | | 404 | Object not found | Notes * Applicable only to tables and files. * Returns the latest available profiling information. ### Entity Relationships | Field | Value | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Get Entity Relationships | | API Description | Retrieves relationship information for a table, including column relationships and pattern-based relationships discovered within the catalog. | | Method | GET | | Endpoint URL | /api/v1/mcp/entity-relationships | | Method Name | McpApi.getEntityRelationships → McpApiService.getEntityRelationships | | MCP Tool | table\_entity\_relationships | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Query Parameters** | Parameter | Required | Description | | --------- | -------- | ----------------------- | | objectId | Yes | Table object identifier | #### **Example Request** ``` GET /api/v1/mcp/entity-relationships? objectId=12345 ``` #### **Example Response** ```json { "ok": true, "data": { "relationships": [ { "sourceColumn": "CUSTOMER_ID", "targetTable": "ORDERS", "targetColumn": "CUSTOMER_ID", "relationshipType": "Foreign Key" } ] } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | --------------- | | 200 | Success | | 404 | Table not found | Notes * Supported only for table assets. * Includes explicit and inferred relationships. ### Lineage | Field | Value | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Get Lineage | | API Description | Retrieves upstream and downstream lineage for a table or file asset. The response includes connected assets up to the requested lineage depth. | | Method | GET | | Endpoint URL | /api/v1/mcp/lineage | | Method Name | McpApi.getLineage → McpApiService.getLineage | | MCP Tool | asset\_lineage | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Query Parameters** | Parameter | Required | Default | Description | | ---------- | -------- | ------- | ------------------------------------ | | objectId | Yes | — | OvalEdge object identifier | | objectType | Yes | — | oetable or oefile | | depth | No | 2 | Number of lineage levels to retrieve | #### **Example Request** ``` GET /api/v1/mcp/lineage? objectId=12345& objectType=oetable& depth=2 ``` #### **Example Response** ```json { "ok": true, "data": { "objectId": 12345, "upstream": [], "downstream": [], "depth": 2 } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | --------------- | | 200 | Success | | 400 | Invalid request | | 404 | Asset not found | Notes * Supports table and file assets. * The server may limit the maximum lineage depth. * Returns upstream and downstream lineage visible to the authenticated user. ### Glossary Terms (Lookup) | Field | Value | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Lookup Glossary Terms | | API Description | Retrieves details of a glossary term by either its object ID or term name. Returns business metadata, definitions, categories, and other glossary attributes accessible to the authenticated user. | | Method | GET | | Endpoint URL | /api/v1/mcp/glossary-terms | | Method Name | McpApi.getGlossaryTerms → McpApiService.getGlossaryTerms | | MCP Tool | lookup\_glossary\_term | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Query Parameters** | Parameter | Required | Description | | --------- | ----------- | ---------------------------- | | objectId | Conditional | Internal glossary object ID. | | termName | Conditional | Name of the glossary term. | #### **Use only one lookup method** * objectId OR * termName #### **Example Request (Term Name)** ``` GET /api/v1/mcp/glossary-terms?termName=Revenue ``` #### **Example Request (Object ID)** ``` GET /api/v1/mcp/glossary-terms?objectId=100 ``` #### **Example Response** ```json { "ok": true, "message": null, "data": { "termId": 100, "termName": "Revenue", "businessDefinition": "Income generated from business operations.", "domain": "Finance", "categories": [ "Financial Metrics" ], "status": "Published" } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | ------------------------------------ | | 200 | Glossary term retrieved successfully | | 400 | Invalid request | | 404 | Glossary term not found | | 500 | Internal server error | Notes * Specify either objectId or termName. * Results respect the user's glossary permissions. * Supports lookup of published glossary terms. ### Create Glossary Term | Field | Value | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Create Glossary Term | | API Description | Creates a new glossary term within the specified glossary domain. Supports optional descriptions, definitions, categories, and draft publishing options. | | Method | POST | | Endpoint URL | /api/v1/mcp/glossary-terms | | Method Name | McpApi.createGlossaryTerm → McpApiService.createGlossaryTerm | | MCP Tool | create\_glossary\_term | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Request Body** ``` { "termName": "Example Term", "domainId": 1, "description": "Short description", "definition": "Full business definition", "category1Id": null, "category2Id": null, "publish": false } ``` #### **Request Parameters** | Parameter | Required | Description | | ----------- | -------- | ----------------------------------------------------------------- | | termName | Yes | Name of the glossary term. | | domainId | Yes | Target glossary domain ID. | | description | No | Short description. | | definition | No | Detailed business definition. | | category1Id | No | Primary category. | | category2Id | No | Secondary category. | | Publish | No | Creates the term as published or draft. Default is Draft (false). | #### **Aliases** | Alias | Equivalent Field | | -------------- | ---------------- | | name | termName | | globalDomainId | domainId | #### **Example Response** ```json { "ok": true, "message": null, "data": { "termId": 456, "termName": "Example Term", "domain": "Finance" } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | ---------------------------------- | | 200 | Glossary term created successfully | | 400 | Validation failed | | 403 | Permission denied | | 409 | Duplicate glossary term | | 500 | Internal server error | Notes * domainId is mandatory. * The authenticated user must have permission to create glossary terms. * Draft publishing is supported. ### Tags (Lookup) | Field | Value | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | API Name | Lookup Tags | | API Description | Retrieves tag details by tag name or object ID. Returns tag metadata and hierarchy information available to the authenticated user. | | Method | GET | | Endpoint URL | /api/v1/mcp/tags | | Method Name | McpApi.getTags → McpApiService.getTags | | MCP Tool | lookup\_tags | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Query Parameters** | Parameter | Required | Description | | --------- | ----------- | ------------------------ | | objectId | Conditional | Internal tag identifier. | | tagName | Conditional | Name of the tag. | #### **Lookup Rules** Specify either: * objectId OR * tagName #### **Example Request** ``` GET /api/v1/mcp/tags?tagName=PII ``` #### **Example Response** ```json { "ok": true, "message": null, "data": { "tagId": 25, "tagName": "PII", "description": "Personally Identifiable Information", "parentTag": "Sensitive Data" } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | --------------- | | 200 | Success | | 400 | Invalid request | | 404 | Tag not found | Notes * Either objectId or tagName must be supplied. * Results respect security permissions. ### Create Tag | Field | Value | | --------------- | ----------------------------------------------------------------------------------------------------- | | API Name | Create Tag | | API Description | Creates a new catalog tag. Supports optional parent tag hierarchy and secure master tag associations. | | Method | POST | | Endpoint URL | /api/v1/mcp/tags | | Method Name | McpApi.createTag → McpApiService.createTag | | MCP Tool | create\_tag | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Request Body** ``` { "tagName": "New Tag", "description": "Optional description", "parentTagId": null, "masterTagId": null } ``` #### **Request Parameters** | Parameter | Required | Description | | ----------- | -------- | ---------------------------------- | | tagName | Yes | Tag name. | | description | No | Tag description. | | parentTagId | No | Parent tag ID. | | masterTagId | No | Master tag ID used in secure mode. | #### **Aliases** | Alias | Equivalent Field | | ----- | ---------------- | | name | tagName | #### **Example Response** ```json { "ok": true, "message": null, "data": { "tagId": 123, "tagName": "New Tag", "status": "created" } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | ------------------------ | | 200 | Tag created successfully | | 400 | Validation failed | | 403 | Permission denied | | 409 | Duplicate tag | Notes * Parent and master tag relationships are optional. * Users require permission to create tags. * Secure mode supports master tag associations. ### Search Platform Documentation | Field | Value | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Search Platform Documentation | | API Description | Searches indexed OvalEdge product documentation using natural language queries. Returns the most relevant documentation content based on keyword and semantic search. | | Method | GET | | Endpoint URL | /api/v1/mcp/search-platform-docs | | Method Name | McpApi.searchPlatformDocs → McpApiService.searchPlatformDocs | | MCP Tool | search\_platform\_docs | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Query Parameters** | | Required | Default | Description | | ------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------- | | query | Yes | — | Search query. | | limit | No | 10 | Maximum number of results. | | numCandidates | No | 128 | Number of candidate documents evaluated during semantic search. Must be greater than or equal to the limit. | #### **Example Request** ``` GET /api/v1/mcp/search-platform-docs? query=how to configure lineage& limit=10 ``` #### **Example Response** ```json { "ok": true, "data": { "results": [ { "title": "Configure Lineage", "summary": "Steps for configuring lineage...", "url": "https://..." } ] } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | --------------------- | | 200 | Success | | 400 | Invalid request | | 500 | Internal server error | Notes * Performs keyword and semantic document search. * Returns ranked documentation results. * The maximum value for numCandidates is server-controlled. ### Source System Access | Field | Value | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Get Source System Access | | API Description | Retrieves native source system access permissions harvested through RDAM for supported platforms such as Redshift, Snowflake, and Tableau. Returns object-level or user-level grants based on the specified query direction. This API retrieves source system permissions and does not return OvalEdge catalog access permissions. | | Method | GET | | Endpoint URL | /api/v1/mcp/source-system-access | | Method Name | McpApi.getSourceSystemAccess → McpApiService.getSourceSystemAccess | | MCP Tool | source\_system\_access | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Query Parameters** | Parameter | Required | Default | Description | | ----------------- | ----------- | ------- | --------------------------------------------------------------------------------------------------------------------- | | sourceSystem | Conditional | — | Native platform. Supported values are redshift, snowflake, and tableau. Only one value is allowed per request. | | queryDirection | Yes | — | Specifies the query mode. Supported values are user\_to\_objects, object\_to\_users, and browse. | | username | Conditional | — | Source system user name. Required when queryDirection=user\_to\_objects. | | objectPath | Conditional | — | RDAM object path. Required for object\_to\_users queries. | | objectName | No | — | Object name used with objectPath to resolve the requested object. | | objectType | Conditional | — | Object level within the source system. | | connectionId | Conditional | — | OvalEdge connection identifier. Required for browse queries and recommended for other query types. | | includeColumns | No | false | Returns column-level grants for Redshift. | | resolveAllMatches | No | false | Returns all matching objects when multiple matches are found. | | scopeMode | No | exact | Specifies whether to return access for the requested object only (exact) or include descendant objects (descendants). | #### **Supported Source Systems** * Redshift * Snowflake * Tableau #### **Supported Object Types** * database * schema * table * column * project * report #### **Required Parameters by Query Direction** | Query Direction | Required Parameters | | ----------------- | ------------------------ | | browse | connectionId, objectType | | user\_to\_objects | username | | object\_to\_users | objectPath, objectType | #### **Example Request** ``` GET /api/v1/mcp/source-system-access? sourceSystem=redshift& queryDirection=user_to_objects& username=svc_analytics& connectionId=1000 ``` #### **Example Response** ```json { "ok": true, "message": "", "data": { "sourceSystem": "redshift", "queryDirection": "user_to_objects", "username": "svc_analytics", "objectType": "table", "grants": [ { "objectPath": "prod_db.public.orders", "objectLevel": "table", "privileges": [ "SELECT" ], "grantMechanism": "role", "principalName": "svc_analytics" } ], "summary": { "totalGrants": 1 } } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | ------------------------------ | | 200 | Request completed successfully | | 400 | Invalid request parameters | | 401 | Authentication failed | | 403 | Permission denied | | 500 | Internal server error | Notes * Retrieves native source system permissions only. * Does not return OvalEdge catalog access permissions. * Supports Redshift, Snowflake, and Tableau RDAM metadata. * Results are filtered based on the authenticated user's permissions. ### Update Asset Descriptions | Field | Value | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Update Asset Descriptions | | API Description | Updates business, technical, detailed, domain, tag, or master tag descriptions for supported OvalEdge catalog and governance assets. The API validates object type and supported description fields, enforces RBAC, governance restrictions, glossary draft rules, and supports dry-run execution. All updates are audited with OE-MCP as the source. | | Method | POST | | Endpoint URL | /api/v1/mcp/update-asset-descriptions | | Method Name | McpApi.updateAssetDescriptions → McpApiService.updateAssetDescriptions | | MCP Tool | update\_asset\_descriptions | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Request Body** ```json { "target": { "objectType": "oetable", "objectId": 12345 }, "descriptions": { "businessDescription": "Business-friendly summary", "technicalDescription": "Technical notes", "detailedDescription": "Detailed description" }, "options": { "dryRun": false, "failOnBlockedField": false, "idempotencyKey": "UUID" }, "clientContext": { "prompt": "Update business description", "reason": "Documentation improvement" } } ``` #### **Required Parameters** | Parameter | Description | | ----------------- | ------------------------------ | | target.objectType | Supported asset type | | target.objectId | OvalEdge object identifier | | descriptions | At least one description field | #### **Optional Parameters** | Parameter | Description | | ------------------ | ------------------------------------ | | options.dryRun | Validates request without updating | | failOnBlockedField | Stops update when a field is blocked | | idempotencyKey | Prevents duplicate requests | | clientContext | Audit information | #### **Supported Description Fields** | Object Type | Supported Fields | | -------------- | ------------------------------------------- | | Catalog Assets | Business Description, Technical Description | | Glossary | Business Description, Detailed Description | | Data Product | Business Description, Detailed Description | | Global Domain | Domain Description | | Tag | Tag Description | | Master Tag | Master Tag Description | #### **Example Response** ```json { "ok": true, "data": { "status": "success", "updatedFields": [ "businessDescription" ], "approval": { "workflowTriggered": false }, "audit": { "source": "OE-MCP" } } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | -------------------------- | | 200 | Success or Partial Success | | 400 | Validation Error | | 404 | Object Not Found | | 409 | Governance Restriction | Notes * Supports dry-run validation. * Enforces governance restrictions. * Updates are audited. ### Update CDE Associations | Field | Value | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Update CDE Associations | | API Description | Updates Critical Data Element (CDE) status for one or more catalog assets. Supports marking assets as CDE, removing CDE designation, or resetting CDE status. Optional category and justification values can also be updated. | | Method | POST | | Endpoint URL | /api/v1/mcp/update-cde-associations | | Method Name | McpApi.updateCdeAssociations → McpApiService.updateCdeAssociations | | MCP Tool | update\_cde\_associations | | Authentication | Bearer API Token | #### **Request Body** ```json { "targets": [ { "objectType": "oetable", "objectId": 12345 } ], "action": "Yes", "cdeCategory": "Finance", "cdeJustification": "Regulatory Requirement" } ``` #### **Required Parameters** | Parameter | Description | | --------- | --------------------------- | | targets | One or more catalog objects | | action | Yes, No, or None | #### **Optional Parameters** | Parameter | Description | | ---------------- | ---------------------- | | cdeCategory | CDE Category | | cdeJustification | Business justification | | dryRun | Validation only | | idempotencyKey | Duplicate protection | #### **Supported Actions** * Yes * No * None #### **Supported Object Types** * Schema * Table * Column * File * File Column * API * Query * Chart #### **Example Response** ```json { "ok": true, "data": { "status": "success", "governanceSummary": { "requested": 2, "updated": 2 } } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | --------------- | | 200 | Success | | 400 | Invalid Request | Notes * Supports bulk updates. * Each target is evaluated independently. * Partial success is supported. * Audit records are generated. ### Update Custom Field Values | Field | Value | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Update Custom Field Values | | API Description | Updates editable custom field values for supported catalog assets. Only custom fields configured as Editable through API can be modified. | | Method | POST | | Endpoint URL | /api/v1/mcp/update-custom-field-values | | Method Name | McpApi.updateCustomFieldValues → McpApiService.updateCustomFieldValues | | MCP Tool | update\_custom\_field\_value | | Authentication | Bearer API Token | #### **Supported Custom Field Types** * Text * Number * Code * Date **Example Request** ```json { "objectId": 12345, "objectType": "oetable", "fieldName": "Business Owner", "value": "Finance Team" } ``` #### **Example Response** ```json { "ok": true, "data": { "fieldId": 789, "updatedValue": "Finance Team", "status": "success" } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | -------------------- | | 200 | Success | | 400 | Invalid Custom Field | | 403 | Permission Denied | Notes * Only API-editable custom fields can be updated. * Validation occurs before saving. * Changes are audited. ### Get User Object Access | Field | Value | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Get User Object Access | | API Description | Retrieves OvalEdge catalog access permissions for catalog objects. The API supports querying either the effective permissions of a user on a specific object or the users and roles that have access to a specified object. This API returns OvalEdge catalog permissions and does not retrieve native source system permissions. | | Method | GET | | Endpoint URL | /api/v1/mcp/get-user-object-access | | Method Name | McpApi.getUserObjectAccess → McpApiService.getUserObjectAccess → McpCatalogObjectAccessReadService.resolve | | MCP Tool | get\_user\_object\_access | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Query Parameters** | Parameter | Required | Description | | ------------------ | ----------- | ----------------------------------------------------------------- | | queryDirection | Yes | Supported values are user\_to\_object and object\_to\_principals. | | username | Conditional | Required when queryDirection=user\_to\_object. | | objectId | Conditional | Internal OvalEdge object identifier. | | objectType | Conditional | Catalog object type. | | fullyQualifiedName | Conditional | Fully Qualified Name used to resolve the object. | | objectName | Conditional | Object name used with object type. | | resolveAllMatches | No | Returns all matching objects when multiple matches exist. | #### **Object Resolution Methods** Specify one of the following: 1. objectId + objectType 2. fullyQualifiedName 3. objectName + objectType #### **Supported Object Types** * connection * schema * table * column * file * file folder * domain * chart * chart child * API * API column * query * code * glossary * global domain * tag * master tag * story * data domain * data product **Example Request** ``` GET /api/v1/mcp/get-user-object-access? queryDirection=user_to_object& username=jdoe& objectId=12345& objectType=oetable ``` #### **Example Response** ```json { "ok": true, "data": { "queryDirection": "user_to_object", "objectId": 12345, "objectType": "oetable", "effectiveAccess": { "username": "jdoe", "metadataPermission": "Read-Write", "dataPermission": "Read", "hasAccess": true } } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | ------------------------------ | | 200 | Request completed successfully | | 400 | Invalid request parameters | | 403 | Permission denied | | 404 | Object or user not found | | 500 | Internal server error | Notes * Returns effective OvalEdge catalog permissions. * Supports user-to-object and object-to-principals queries. * Results include inherited and role-based permissions. * Native source system permissions are available through the Source System Access API. ### Assess CDE DQ | Field | Value | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Assess CDE DQ (DQ Rule Recommendation) | | API Description | Evaluates Critical Data Elements (CDEs) and other supported catalog assets to recommend appropriate Data Quality Rules. The API returns business metadata, recommended DQ functions, reusable rules, recommended implementation workflow, and existing rule associations. This API performs assessment only and does not create or associate Data Quality Rules. | | Method | POST | | Endpoint URL | /api/v1/mcp/dq-intelligence/assess-cde | | Method Name | McpApi.assessCdeDq → McpApiService.assessCdeDq → McpService.assessCdeDq | | MCP Tool | assess\_cde\_dq | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Request Body** ```json { "objects": [ { "objectId": 12345, "objectType": "oecolumn" } ], "discoverCdeColumns": false, "limit": 50, "descriptionTermName": "Customer", "descriptionCustomFieldName": "Business Definition" } ``` #### **Required Parameters** | Parameter | Required | Description | | -------------------------- | ----------- | --------------------------------------------------------------- | | objects | Conditional | List of catalog objects to assess. | | discoverCdeColumns | Conditional | Discovers CDE columns when no objects are specified. | | limit | No | Maximum number of objects to evaluate. | | descriptionTermName | No | Uses the specified glossary term description during assessment. | | descriptionTermName | No | Uses the specified glossary term description during assessment. | | descriptionCustomFieldName | No | Uses the specified custom field value during assessment. | #### **Supported Object Types** * Table * Column * File * File Column #### **Example Response** ```json { "ok": true, "data": { "assessedCount": 1, "rows": [ { "objectId": 12345, "tableColumnName": "SALES.CUSTOMERS.EMAIL", "criticalDataElement": "Yes", "recommendedFunction": "Non-Null Validation", "recommendedWorkflow": "function_based", "recommendedRule": "Non-Null Check - Customer Email", "associatedToDqRule": false } ] } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | ------------------------------------------ | | 200 | Assessment completed successfully | | 400 | Invalid request or unsupported object type | | 401 | Authentication failed | | 403 | Permission denied | | 500 | Internal server error | Notes * Supports explicit object assessment or automatic discovery of CDE columns. * Returns recommendations only and does not modify Data Quality Rules. * Identifies reusable rules when available. * Indicates whether the recommended rule is already associated with the object. * Recommended workflows include function\_based and custom\_sql implementations. ### Lookup Datastory | Field | Value | | --------------- | ------------------------------------------------------------------------------------------------------- | | API Name | Lookup Datastory | | API Description | Retrieves a Datastory by its name and content. Returns the associated Story Zone and audit information. | | Method | GET | | Endpoint URL | /api/v1/mcp/lookup-datastory | | Method Name | McpApi.lookupDatastory → McpApiService.lookupDatastory | | MCP Tool | lookup\_datastory | | Authentication | Bearer API Token | #### **Required Parameters** | Parameter | Description | | ------------- | --------------------- | | Story Name | Name of the Datastory | | Story Content | Datastory content | #### **Optional Parameters** | Parameter | Description | | ---------- | --------------------- | | Story Zone | Filters by Story Zone | #### **Example Response** ```json { "ok": true, "data": { "story": { "name": "Customer Journey", "zone": "Marketing" } } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | --------------- | | 200 | Success | | 404 | Story Not Found | ### Metadata Changes Between Crawls | Field | Value | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Metadata Changes Between Crawls | | API Description | Returns metadata differences detected between two crawl executions, including added, removed, and modified schemas, tables, and columns. | | Method | POST | | Endpoint URL | /api/v1/mcp/metadata-changes-between-crawls | | Method Name | McpApi.metadataChangesBetweenCrawls → McpApiService.metadataChangesBetweenCrawls | | MCP Tool | metadata\_changes\_between\_crawls | | Authentication | Bearer API Token | #### **Required Parameters** * Schemas * Tables * Table Columns #### **Example Response** ```json { "ok": true, "data": { "changes": [ { "schema": "Sales", "table": "Orders", "column": "Order_Date", "changeType": "modified" } ] } } ``` #### **HTTP Status Codes** | Code | Description | | ---- | --------------- | | 200 | Success | | 400 | Invalid Request | ### Update Governance Roles | Field | Value | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Update Governance Roles | | API Description | Governed write API that assigns or updates governance responsibilities (Owner, Steward, Custodian, Governance Role 4, Governance Role 5, and Governance Role 6) on supported OvalEdge assets. Catalog objects are validated using Elasticsearch metadata where applicable, while non-catalog objects such as DQ Rules, Schemes, Policies, and DAGs are validated using domain DAO validation. The API enforces RBAC permissions and glossary propagation rules. Partial updates are supported and return a partial\_success status when some role assignments are applied, and others are blocked. | | Method | POST | | Endpoint URL | /api/v1/mcp/update-governance-roles | | Method Name | McpApi.updateGovernanceRoles → McpApiService.updateGovernanceRoles | | MCP Tool | update\_governance\_roles | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Request Body** ```json { "target": { "objectType": "oetable", "objectId": 9834 }, "roleUpdates": { "owner": "rohit.anand@ovaledge.com", "steward": "vinod.merugu@ovaledge.com" }, "options": { "dryRun": false, "cascade": true, "idempotencyKey": "mcp-gov-roles-9834-001" }, "clientContext": { "prompt": "Set owner and steward on Customer table", "reason": "MCP-assisted governance assignment" } } ``` #### **Request Parameters** | Parameter | Type | Required | Description | | ---------------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | target | Object | Yes | Asset to update. | | target.objectType | String | Yes | OvalEdge object type (for example, oetable, oecolumn, glossary, or dqrule). | | target.objectId | Integer | Yes | Internal OvalEdge object identifier. Value must be greater than 0. | | roleUpdates | Object (Map) | Yes | Non-empty map of governance role keys and corresponding user or team identifiers. | | options | Object | No | Execution options. | | options.dryRun | Boolean | No | Validates the request without persisting changes. | | options.idempotencyKey | String | No | Client-generated key used to prevent duplicate requests during retries. | | options.cascade | Boolean | No | Cascades governance role assignments to supported child objects. When omitted, the server may automatically cascade updates for supported object types such as schemas, tables, files, charts, and APIs. | | clientContext | Object | No | Audit information associated with the request. | | clientContext.prompt | String | No | Original user or agent prompt. | | clientContext.reason | String | No | Reason for updating the governance roles. | #### **Supported Governance Role Keys** | Client Key | Canonical Role | | ---------------------------------------------- | --------------- | | owner | owner | | steward | steward | | custodian | custodian | | governance\_role\_4, governancerole4, govrole4 | governancerole4 | | governance\_role\_5, governancerole5, govrole5 | governancerole5 | | governance\_role\_6, governancerole6, govrole6 | governancerole6 | #### **Example Request** ```json { "target": { "objectType": "oetable", "objectId": 9834 }, "roleUpdates": { "owner": "rohit.anand@ovaledge.com", "steward": "vinod.merugu@ovaledge.com" }, "options": { "dryRun": false, "cascade": true, "idempotencyKey": "mcp-gov-roles-9834-001" }, "clientContext": { "prompt": "Set owner and steward on Customer table", "reason": "MCP-assisted governance assignment" } } ``` #### **Response Body** **Success Response (HTTP 200)** ```json { "ok": true, "message": null, "data": { "status": "success", "reasonCode": null, "target": { "objectType": "oetable", "objectId": 9834, "redirectUrl": "https:///#nav/table?..." }, "updatedRoles": [ "owner", "steward" ], "blockedRoles": [], "message": null, "approval": null, "audit": { "source": "OE-MCP", "auditId": null } } } ``` #### **Response Fields** | Field | Type | Description | | ------------------ | --------- | -------------------------------------------------------------------------------------------- | | status | String | Update status. Supported values are success, partial\_success, and blocked. | | reasonCode | String | Reason returned when the request is partially or fully blocked. | | target.objectType | String | Object type specified in the request. | | target.objectId | Integer | Object identifier specified in the request. | | target.redirectUrl | String | Absolute URL for opening the updated asset in the OvalEdge application. | | updatedRoles | String\[] | Governance roles that were successfully updated or would be updated during a dry run. | | blockedRoles | String\[] | Governance roles that could not be updated because of permission or governance restrictions. | | message | String | Optional message describing the update result. | | approval | Object | Optional approval workflow information, including workflow status and identifier. | | audit.source | String | Audit source. Always returns OE-MCP. | | audit.auditId | Long | Audit identifier when available. | #### **Status Values** | Status | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------ | | success | All requested governance role assignments were applied successfully or already matched the requested values. | | partial\_success | Some governance role assignments were applied, while others were blocked. | | blocked | None of the requested governance role assignments could be applied. | #### **Reason Codes** | Reason Code | Description | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | GLOSSARY\_PROPAGATED\_GOVERNANCE\_ROLE | Governance role is inherited from a glossary term through Copy Role to Catalog and cannot be updated directly. | | GOVERNANCE\_ROLE\_UNAUTHORIZED | The authenticated user does not have permission to update the requested governance role. | | GOVERNANCE\_ROLE\_NOT\_SUPPORTED\_FOR\_OBJECT | The requested governance role is not supported for the specified object type. | #### **HTTP Status Codes** | Code | Description | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 200 | Governance roles updated successfully. The response may indicate success, partial\_success, or blocked. | | 400 | Validation error, such as missing target, invalid object type, invalid governance role, blank user or team, disabled role, steward-only validation failure, or license validation failure. | | 404 | Target object was not found. | | 500 | Unexpected server error occurred while processing the request. | Notes * Supports updating one or more governance roles in a single request. * RBAC permissions and glossary propagation rules are enforced before applying updates. * Supports dry-run validation without persisting changes. * Cascade updates are supported for applicable object types. * All successful updates are audited with OE-MCP as the audit source. * Partial updates are supported when only a subset of the requested governance role assignments can be applied. ### Lookup DQ Rule | Field | Value | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Lookup DQ Rule | | API Description | Retrieves Data Quality (DQ) rules using either the rule ID or the rule name. When searching by rule name, the API first performs an exact match and then a partial match if no exact match is found. The response includes rule details, steward information, and governance guidance for subsequent governance updates. DQ rules are not searchable through the search\_catalog\_assets API. | | Method | GET | | Endpoint URL | /api/v1/mcp/lookup-dq-rules | | Method Name | McpApi.lookupDqRules → McpApiService.lookupDqRules | | MCP Tool | lookup\_dq\_rule | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Query Parameters** | Parameter | Required | Default | Description | | --------- | ----------- | ------- | --------------------------------------------------------------------------------------------------------- | | objectId | Conditional | — | Internal Data Quality Rule identifier (dqruleid). Use when the exact rule ID is known. | | ruleName | Conditional | — | Name of the Data Quality Rule. Performs an exact match first, followed by a partial match when necessary. | | limit | No | 20 | Maximum number of matching rules returned when searching by rule name. The server maximum is 100. | Required: Specify exactly one of the following: * objectId * ruleName Do not specify both parameters in the same request. #### **Example Requests** ``` GET /api/v1/mcp/lookup-dq-rules?ruleName=Null%20Data%20Density&limit=20 ``` ``` GET /api/v1/mcp/lookup-dq-rules?objectId=42 ``` #### **Response Body** **Success Response (HTTP 200)** ```json { "ok": true, "message": null, "data": [ { "objectId": 42, "objectType": "dqrule", "objectName": "Null Data Density Check", "steward": "jdoe", "redirectUrl": "https://.../nav/...", "governanceNote": "Only steward may be updated via update_governance_roles on dqrule." } ] } ``` #### **Response Fields** | Field | Type | Description | | -------------- | ------- | -------------------------------------------------------------- | | objectId | Integer | Internal Data Quality Rule identifier. | | objectType | String | Always returns dqrule. | | objectName | String | Name of the Data Quality Rule. | | steward | String | Steward assigned to the Data Quality Rule. | | redirectUrl | String | Absolute URL for opening the rule in the OvalEdge application. | | governanceNote | String | Guidance for governance role updates applicable to the rule. | #### **HTTP Status Codes** | Code | Description | | ---- | ----------------------------------------------------------------------------- | | 200 | Data Quality Rule retrieved successfully. | | 400 | Both objectId and ruleName were specified, or neither parameter was provided. | | 404 | Data Quality Rule not found. | | 500 | Unexpected server error. | Notes * Retrieves Data Quality Rules only. * Data Quality Rules are not returned by the Search Catalog Assets API. * Use Assess CDE DQ to obtain DQ rule recommendations. * Use Associate DQ Rule Objects to associate catalog objects after resolving the DQ Rule ID. ### Associate DQ Rule Objects | Field | Value | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Associate DQ Rule Objects | | API Description | Governed write API that associates one or more catalog objects with an existing Data Quality Rule. Each object is validated against the rule function before association. Published (ACTIVE) rules are temporarily converted to Draft during the association process and restored to Published after the update completes. All operations are audited with OE-MCP as the audit source. | | Method | POST | | Endpoint URL | /api/v1/mcp/dq-intelligence/associate-rule-objects | | Method Name | McpApi.associateDqRuleObjects → McpApiService.associateDqRuleObjects → McpDqRuleWriteService.associate | | MCP Tool | associate\_dq\_rule\_objects | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Request Body (application/json)** ```json { "dqruleId": 42, "objects": [ { "objectId": 12345, "objectType": "oecolumn" }, { "objectId": 67890, "objectType": "oetable" } ], "skipAlreadyAssociated": true } ``` #### **Request Parameters** | Parameter | Required | Default | Description | | --------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------- | | dqruleId | Yes | — | Existing Data Quality Rule identifier obtained from Lookup DQ Rule or Assess CDE DQ. | | objects | Yes | — | Non-empty collection of catalog objects to associate. | | skipAlreadyAssociated | No | true | When enabled, objects that are already associated with the rule are skipped and reported as already associated. | #### **Example Requests** ```json { "dqruleId": 42, "objects": [ { "objectId": 12345, "objectType": "oecolumn" }, { "objectId": 67890, "objectType": "oetable" } ], "skipAlreadyAssociated": true } ``` #### **Response Body** **Success Response (HTTP 200)** ```json { "ok": true, "message": null, "data": { "dqruleId": 42, "associatedCount": 1, "skippedCount": 1, "failedCount": 0, "statusMessage": "1 associated, 1 skipped, 0 failed out of 2 object(s).", "rows": [ { "objectId": 12345, "objectType": "oecolumn", "status": "associated", "message": null, "dqRuleRedirectUrl": "https://.../nav/..." }, { "objectId": 67890, "objectType": "oetable", "status": "skipped", "message": "Object data type or connector is not supported." } ], "audit": { "source": "OE-MCP" } } } ``` #### **Response Fields** | Field | Type | Description | | --------------- | ------- | --------------------------------------------- | | dqruleId | Integer | Data Quality Rule identifier. | | associatedCount | Integer | Number of successfully associated objects. | | skippedCount | Integer | Number of skipped objects. | | failedCount | Integer | Number of objects that failed association. | | statusMessage | String | Summary of the association results. | | rows | Array | Association status for each requested object. | | audit.source | String | Audit source. Always returns OE-MCP. | #### **Row Status Values** | Status | Description | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | | associated | Object was successfully associated with the Data Quality Rule. Includes already-associated objects when skipAlreadyAssociated=true. | | skipped | Object was skipped because of validation failure, unsupported object type, or policy restriction. | | failed | Association failed because of a backend processing error. | #### **HTTP Status Codes** | Code | Description | | ---- | ---------------------------------------------------------------------------------------- | | 200 | Request completed successfully. Individual object failures are reported in the response. | | 400 | Invalid request, missing Data Quality Rule, or validation failure. | | 500 | Unexpected server error. | #### **Confirmation Workflow** Before updating Data Quality Rule associations, the MCP server returns a confirmation preview when write\_confirmed\_by\_user is not provided. 1. Initial request returns a confirmation preview. 2. User approves the operation. 3. The request is resubmitted with write\_confirmed\_by\_user=true and the provided confirmationToken. 4. The association operation is executed. Notes * Supports associating multiple catalog objects in a single request. * Published Data Quality Rules are temporarily converted to Draft during association and restored to Published after completion. * Use Assess CDE DQ to identify recommended Data Quality Rules before association. * Use Lookup DQ Rule when the Data Quality Rule name or identifier is already known. * All successful operations are audited with OE-MCP as the audit source. ### Create DQ Rules | Field | Value | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Create DQ Rules | | API Description | Governed write API that evaluates Critical Data Elements (CDEs) and other supported catalog objects to either associate them with an existing recommended Data Quality Rule or automatically create new Data Quality Rules when sufficient metadata and business criteria are available. Automatic rule creation is supported only for objects with Critical Data Element (CDE) status set to Yes. All operations are audited with OE-MCP as the audit source. | | Method | POST | | Endpoint URL | /api/v1/mcp/dq-intelligence/create-rules | | Method Name | McpApi.createDqRules → McpApiService.createDqRules → McpDqRuleWriteService.createRules | | MCP Tool | create\_dq\_rules | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Request Body (application/json)** ```json { "objects": [ { "objectId": 12345, "objectType": "oecolumn" } ], "discoverCdeColumns": false, "limit": 50, "preferExistingRule": true, "skipDuplicateFunctionOnObject": true, "descriptionTermName": "Customer", "descriptionCustomFieldName": "Business Definition", "supplementalCriteriaText": "Success criteria: equal to 300" } ``` #### **Request Parameters** | Parameter | Required | Default | Description | | ----------------------------- | ----------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | objects | Conditional | Empty | Catalog objects to evaluate. Required unless discoverCdeColumns is true. | | discoverCdeColumns | Conditional | false | Automatically discovers CDE columns when no objects are provided. | | limit | No | 50 | Maximum number of objects to process. Server maximum is 100. | | preferExistingRule | No | true | Associates objects with an existing recommended rule when available. When set to false, a new rule is created even if a matching rule exists. | | skipDuplicateFunctionOnObject | No | true | Skips rule creation when the object already has a Data Quality Rule with the same function type. | | descriptionTermName | No | — | Uses the specified glossary term description during rule generation. | | descriptionCustomFieldName | No | — | Uses the specified custom field value during rule generation. | | supplementalCriteriaText | No | — | Additional business criteria supplied by the user when sufficient metadata is unavailable. | #### **Criteria Evaluation Order** Rule generation evaluates business criteria in the following order: 1. Catalog metadata 2. supplementalCriteriaText 3. Default Data Quality function behavior **Example Requests** ```json { "objects": [ { "objectId": 12345, "objectType": "oecolumn" } ], "preferExistingRule": true } ``` #### **Response Body** **Success Response (HTTP 200)** ```json { "ok": true, "message": null, "data": { "createdCount": 1, "associatedCount": 0, "skippedCount": 0, "failedCount": 0, "rows": [ { "objectId": 12345, "objectType": "oecolumn", "status": "created", "dqruleId": 10303, "ruleName": "char_column_tcdensitypercentage", "recommendedFunction": "Data Density Percentage", "objectAssociated": true, "objectRedirectUrl": "https://.../nav/...", "dqRuleRedirectUrl": "https://.../nav/..." } ], "audit": { "source": "OE-MCP" } } } ``` #### **Response Fields** | Field | Type | Description | | --------------- | ------- | ------------------------------------------------- | | createdCount | Integer | Number of Data Quality Rules created. | | associatedCount | Integer | Number of objects associated with existing rules. | | skippedCount | Integer | Number of skipped objects. | | failedCount | Integer | Number of failed operations. | | rows | Array | Processing results for each requested object. | | audit.source | String | Audit source. Always returns OE-MCP. | #### **Row Status Values** | Status | Description | | ------------------------- | -------------------------------------------------------------------------------------------------- | | created | A new Data Quality Rule was created and associated with the object. | | associated | Object was associated with an existing recommended Data Quality Rule. | | skipped | Object was skipped because of duplicate policies, prerequisite failures, or existing associations. | | criteria\_missing | Insufficient business metadata was available to create a rule. | | function\_not\_identified | No suitable Data Quality function could be determined. | | failed | Rule creation or association failed. | #### **HTTP Status Codes** | Code | Description | | ---- | --------------------------------------------------------------------------------------- | | 200 | Request completed successfully. Individual object results are returned in the response. | | 400 | Validation error or invalid request. | | 500 | Unexpected server error. | #### **Confirmation Workflow** Before creating or associating Data Quality Rules, the MCP server returns a confirmation preview when write\_confirmed\_by\_user is not specified. 1. Initial request returns a preview. 2. User confirms the operation. 3. The request is resubmitted with write\_confirmed\_by\_user=true and the confirmationToken. 4. The Data Quality Rule is created or associated. Notes * Objects must have Critical Data Element (CDE) status set to Yes for automatic rule creation. * Existing rules can be reused or new rules can be created based on the preferExistingRule setting. * All successful operations are audited with OE-MCP. ### Generate DQ Queries | Field | Value | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Generate DQ Queries | | API Description | Read-only API that generates custom SQL queries required for creating Data Quality Rules when the recommended implementation workflow is custom\_sql. The API generates rule, statistics, and failed-values queries for a single catalog object and can recommend reuse of existing code objects instead of generating new SQL. | | Method | POST | | Endpoint URL | /api/v1/mcp/dq-intelligence/generate-queries | | Method Name | McpApi.generateDqQueries → McpApiService.generateDqQueries → McpDqSqlQueryService.generateQueries | | MCP Tool | generate\_dq\_queries | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Request Body (application/json)** ```json { "objectId": 12345, "objectType": "oecolumn", "businessRule": "Customer email should not be null", "businessDescription": "Customer email address", "descriptionTermName": "Customer", "descriptionCustomFieldName": "Business Definition" } ``` #### **Request Parameters** | Parameter | Required | Description | | -------------------------- | -------- | -------------------------------------------------------------- | | objectId | Yes | Catalog object identifier. | | objectType | Yes | Supported values: oetable, oecolumn, oefile, and oefilecolumn. | | businessRule | No | Overrides the catalog business rule. | | businessDescription | No | Overrides the catalog business description. | | descriptionTermName | No | Uses the specified glossary term description. | | descriptionCustomFieldName | No | Uses the specified custom field description. | #### **Example Requests** ```json { "objectId": 12345, "objectType": "oecolumn" } ``` #### **Response Body** **Success Response (HTTP 200)** ```json { "ok": true, "message": null, "data": { "status": "generated", "ruleQuery": "SELECT ...", "statsQuery": "SELECT ...", "failedValuesQuery": "SELECT ...", "recommendedFunction": "Custom SQL", "recommendedWorkflow": "custom_sql", "reuseExistingCode": false, "matchingCodeObjects": [], "objectRedirectUrl": "https://.../nav/..." } } ``` #### **Response Fields** | Field | Type | Description | | ------------------- | ------- | ----------------------------------------------------------- | | status | String | Result of SQL generation. | | ruleQuery | String | Generated SQL query for rule validation. | | statsQuery | String | Generated SQL query for statistics calculation. | | failedValuesQuery | String | Generated SQL query for retrieving failed records. | | recommendedFunction | String | Recommended Data Quality function. | | recommendedWorkflow | String | Recommended implementation workflow. | | reuseExistingCode | Boolean | Indicates whether an existing code object should be reused. | | matchingCodeObjects | Array | Matching reusable code objects. | | objectRedirectUrl | String | Link to the catalog object. | #### **Status Values** | Status | Agent Action | | ------------------------- | ----------------------------------------------------------------------- | | generated | Proceed to Validate DQ Queries. | | code\_found | Review the recommended reuse action. | | function\_based | Use Create DQ Rules or Associate DQ Rule Objects instead of custom SQL. | | function\_not\_identified | Clarify business rules or run Assess CDE DQ first. | | cross\_schema\_blocked | Cross-schema custom SQL rules are not supported. | | insufficient\_context | Additional metadata is required before SQL generation. | #### **Recommended Reuse Actions** * associate\_existing\_dqr * create\_from\_code * already\_associated #### **HTTP Status Codes** | Code | Description | | ---- | -------------------------------------- | | 200 | SQL generation completed successfully. | | 400 | Validation error. | | 500 | Unexpected server error. | Notes * Applicable only when the recommended workflow is custom\_sql. * Function-based Data Quality Rules should use Create DQ Rules instead. * Generated SQL should be validated using Validate DQ Queries before creating a custom SQL Data Quality Rule. * Existing code objects may be reused when applicable. * The API does not create or associate Data Quality Rules; it generates SQL statements only. ### Validate DQ Queries | Field | Value | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | API Name | Validate DQ Queries | | API Description | Executes the generated Data Quality SQL queries against the target data source to verify that the queries are valid before creating a custom SQL Data Quality Rule. The API validates the Rule, Statistics, and Failed Values queries using Query Sheet execution semantics and returns whether the rule can be created. | | Method | POST | | Endpoint URL | /api/v1/mcp/dq-intelligence/validate-queries | | Method Name | McpApi.validateDqQueries → McpApiService.validateDqQueries → McpDqSqlQueryValidator.validate | | MCP Tool | validate\_dq\_queries | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Request Body (application/json)** ```json { "connectionId": 1000, "schemaId": 200, "ruleQuery": "SELECT COUNT(*) FROM ...", "statsQuery": "SELECT COUNT(*) FROM ...", "failedValuesQuery": "SELECT * FROM ... WHERE ..." } ``` #### **Request Parameters** | Parameter | Required | Description | | ----------------- | -------- | --------------------------------------------------------- | | connectionId | Yes | Connection identifier returned by Generate DQ Queries. | | schemaId | Yes | Schema identifier returned by Generate DQ Queries. | | ruleQuery | Yes | SQL query used to evaluate the Data Quality Rule. | | statsQuery | Yes | SQL query used to calculate Data Quality statistics. | | failedValuesQuery | Yes | SQL query used to retrieve records that violate the rule. | #### **Example Requests** ```json { "connectionId": 1000, "schemaId": 200, "ruleQuery": "SELECT COUNT(*) FROM CUSTOMER WHERE EMAIL IS NULL", "statsQuery": "SELECT COUNT(*) FROM CUSTOMER", "failedValuesQuery": "SELECT * FROM CUSTOMER WHERE EMAIL IS NULL" } ``` #### **Response Body** **Success Response (HTTP 200)** ```json { "ok": true, "message": null, "data": { "ruleQueryValid": true, "canCreateRule": true, "results": [ { "queryType": "rule", "valid": true, "message": null }, { "queryType": "stats", "valid": true, "message": null }, { "queryType": "failed_values", "valid": true, "message": null } ] } } ``` #### **Response Fields** | Field | Type | Description | | -------------- | ------- | ------------------------------------------------------------------ | | ruleQueryValid | Boolean | Indicates whether the Rule SQL query executed successfully. | | canCreateRule | Boolean | Indicates whether the custom SQL Data Quality Rule can be created. | | results | Array | Validation result for each submitted SQL query. | #### **Query Validation Results** | Field | Description | | --------- | --------------------------------------------------------------- | | queryType | Type of query being validated (rule, stats, or failed\_values). | | valid | Indicates whether the query executed successfully. | | message | Validation message or execution error, when applicable. | #### **HTTP Status Codes** | Code | Description | | ---- | ------------------------------------------------------------ | | 200 | Validation completed successfully. | | 400 | Missing or invalid SQL queries, connection ID, or schema ID. | | 500 | Unexpected server error. | #### **Confirmation Workflow** Before executing SQL statements against the target connection, the MCP server requires user confirmation. 1. Initial request returns a confirmation preview. 2. User approves execution. 3. The request is resubmitted with write\_confirmed\_by\_user=true and the confirmationToken. 4. SQL validation is executed. Notes * Executes SQL statements against the source connection. * Uses Query Sheet execution semantics. * Only SELECT statements are supported. * Continue to Create SQL DQ Rule only when canCreateRule=true. * Intended for validating custom SQL Data Quality Rules only. ### Create SQL DQ Rule | Field | Value | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Name | Create SQL DQ Rule | | API Description | Governed write API that creates a draft Custom SQL Data Quality Rule using validated SQL queries or an existing SQL code object. The API creates the Data Quality Rule, generates the required code objects when necessary, associates the specified catalog objects, and records the operation with OE-MCP as the audit source. | | Method | POST | | Endpoint URL | /api/v1/mcp/dq-intelligence/create-sql-rule | | Method Name | McpApi.createSqlDqRule → McpApiService.createSqlDqRule → McpDqSqlRuleWriteService.createSqlRule | | MCP Tool | create\_sql\_dq\_rule | | Authentication | Bearer API Token (@OERole(object="api")) | #### **Request Body (application/json)** ```json { "objectId": 12345, "objectType": "oecolumn", "ruleName": "MCP Email Format Check", "purpose": "Validate email format on CDE column", "recommendedFunction": "Custom SQL", "ruleQuery": "SELECT ...", "statsQuery": "SELECT ...", "failedValuesQuery": "SELECT ...", "connectionId": 1000, "schemaId": 200, "codeObjectId": null, "additionalObjects": [ { "objectId": 67890, "objectType": "oetable" } ] } ``` #### **Request Parameters** | Parameter | Required | Description | | ------------------- | ----------- | ------------------------------------------------------------------- | | objectId | Yes | Primary catalog object identifier. | | objectType | Yes | Type of the primary catalog object. | | ruleName | Yes | Name of the Data Quality Rule. | | ruleQuery | Conditional | Required when codeObjectId is not provided. | | statsQuery | Conditional | Required when codeObjectId is not provided. | | failedValuesQuery | Conditional | Required when codeObjectId is not provided. | | connectionId | No | Connection identifier returned by Generate DQ Queries. | | schemaId | No | Schema identifier returned by Generate DQ Queries. | | purpose | No | Business purpose of the Data Quality Rule. | | recommendedFunction | No | Recommended function returned by previous assessment APIs. | | codeObjectId | No | Existing SQL code object to reuse instead of generating new SQL. | | additionalObjects | No | Additional catalog objects to associate with the Data Quality Rule. | #### **SQL Requirements** Provide one of the following: * codeObjectId OR * ruleQuery * statsQuery * failedValuesQuery #### **Example Requests** ```json { "objectId": 12345, "objectType": "oecolumn", "ruleName": "MCP Email Format Check", "ruleQuery": "SELECT ...", "statsQuery": "SELECT ...", "failedValuesQuery": "SELECT ..." } ``` #### **Response Body** **Success Response (HTTP 200)** ```json { "ok": true, "message": null, "data": { "status": "created", "dqruleId": 88, "ruleName": "MCP Email Format Check", "ruleCodeObjectId": 501, "statsCodeObjectId": 502, "failedValuesCodeObjectId": 503, "objectRedirectUrl": "https://.../nav/...", "dqRuleRedirectUrl": "https://.../nav/...", "ruleCodeRedirectUrl": "https://.../nav/...", "audit": { "source": "OE-MCP" } } } ``` #### **Response Fields** | Field | Type | Description | | ------------------------ | ------- | ----------------------------------------------- | | status | String | Status of the create operation. | | dqruleId | Integer | Newly created Data Quality Rule identifier. | | ruleName | String | Name of the created Data Quality Rule. | | ruleCodeObjectId | Integer | Generated SQL Rule code object identifier. | | statsCodeObjectId | Integer | Generated Statistics code object identifier. | | failedValuesCodeObjectId | Integer | Generated Failed Values code object identifier. | | objectRedirectUrl | String | URL for the associated catalog object. | | dqRuleRedirectUrl | String | URL for the created Data Quality Rule. | | ruleCodeRedirectUrl | String | URL for the generated SQL code object. | | audit.source | String | Audit source. Always returns OE-MCP. | #### **Status Values** | Status | Description | | ---------------------- | --------------------------------------------------------------------------------------- | | created | Custom SQL Data Quality Rule and supporting SQL code objects were successfully created. | | failed | Backend error occurred during rule creation. | | rule\_query\_invalid | Rule SQL failed validation during creation. | | cross\_schema\_blocked | Cross-schema dependent SQL rules are not supported. | #### **HTTP Status Codes** | Code | Description | | ---- | -------------------------------------------------- | | 200 | Custom SQL Data Quality Rule created successfully. | | 400 | Validation error or invalid SQL definition. | | 500 | Unexpected server error. | #### **Confirmation Workflow** Before creating a Custom SQL Data Quality Rule, the MCP server requires explicit user confirmation. 1. Initial request returns a confirmation preview. 2. User approves the operation. 3. The request is resubmitted with write\_confirmed\_by\_user=true and the confirmationToken. 4. The Data Quality Rule is created. Notes * Creates draft Custom SQL Data Quality Rules. * Supports reuse of existing SQL code objects through codeObjectId. * Supports associating additional catalog objects during rule creation. * Cross-schema dependent SQL rules are not supported. * Use Validate DQ Queries before creating a Custom SQL Data Quality Rule. * All successful operations are audited with OE-MCP as the audit source. *** Copyright © 2026, OvalEdge LLC, Peachtree Corners, GA, USA --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ovaledge.com/release8.2/mcp-server/ovaledge-mcp-api-reference-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.