Ataccama ONE Agentic ONE Desktop ONE DQ&C ONE MDM ONE RDM ONE Runtime Server
latest (17.1.0) 17.0.0 16.3.x 16.2.0 16.1.0 16.0.0 15.4.0 15.3.0 15.2.0 15.1.0 14.5.x 13.9.x 13.8.x 13.7.x 13.6.x 13.5.0 13.4.x 13.3.x 13.2.x
User Community Service Desk Downloads

MCP Server in MDM

This article introduces the MDM MCP Server, an experimental feature that exposes MDM metadata, records, and tasks to AI agents through the Model Context Protocol (MCP).

To enable and configure the MCP Server, see Set Up the MDM MCP Server.

The MDM MCP Server is an experimental feature. The protocol, tool definitions, configuration properties, and authentication mechanisms are subject to change in future releases.

We recommend using the MCP Server for research, development, sandbox testing, and internal proof-of-concept workflows. Do not deploy it in production environments without appropriate network isolation, rate limiting, and oversight.

About MDM MCP Server

The Model Context Protocol (MCP) is an open standard based on JSON-RPC 2.0 that lets AI clients—such as Claude Code, Cursor, and OpenCode—interact with external tools and data sources. The MDM MCP Server enables AI agents to query and interact with MDM metadata, records, and tasks programmatically, under the same security boundaries and permissions as human users.

The server is embedded directly in the MDM Server and is available in all deployment types (Ataccama Cloud, Custom Ataccama Cloud, self-managed).

The MCP Server operates in read-only mode and AI agents cannot modify entities directly. Any proposed changes are captured in tasks and drafts, which follow the usual publishing and approval workflows.

Because the MCP Server exposes raw metadata and golden record contents to connected AI clients, which might use external cloud model providers depending on your client configuration, exercise caution with personally identifiable information (PII) and other sensitive data. See Data privacy considerations.

Authentication

The MCP Server uses OAuth 2.0 authentication, with clients using the OAuth 2.0 Authorization Code grant with PKCE against a pre-registered public OpenID Connect client in Keycloak.

Every request to the server must meet the following requirements:

  • Bearer token: There is a valid JSON Web Token (JWT) in the Authorization: Bearer <token> header.

  • Audience and scope binding: The token contains the audience claim (aud) urn:ataccama:mdm:mcp-server and includes the mcp scope. This prevents a token issued for another client or service from being used to access the MCP Server.

  • Session binding: When a client establishes a session (identified by the X-MCP-Session-Id header), that session is bound to the user’s identity. If a different user attempts to use the same session ID, the server rejects the request with a 403 Forbidden response.

For the full Keycloak setup, see Configure Keycloak.

Permissions

Once connected, an agent operates as the authenticated user: it has the same access to entities, records, and tasks that the user has in the MDM web application, and no more. The MCP Server reuses the existing MDM Web Application permissions rather than introducing a separate model.

In practice, this means:

  • Agents can only see entities, records, and tasks the user is allowed to see.

  • Column and row permissions configured in MDM apply to data returned to the agent.

  • Workflow and task actions are limited to those permitted by the user’s roles.

For more information about the underlying permission model, see Configuring Permissions and MDM Web App Permissions.

Data privacy considerations

When an agent calls a data tool such as getRecord, getRecordWithRelation, or findRecords, record contents are retrieved from MDM and transmitted to the connected AI client. Depending on how that client is configured, the data might be sent to an external cloud model provider.

To reduce the risk of exposing PII and other sensitive data:

  • Review your column and row permissions. Use MDM column and row permissions to restrict sensitive columns so they are not returned to the agent.

  • Keep sensitive data out of prompts. Do not enter raw personal data, passwords, or secrets into natural language prompts or prompt templates.

  • Use private model endpoints. For sensitive data, configure your clients to use local, private, or corporate-hosted model endpoints rather than public cloud models.

Tools

Tools are the capabilities the server exposes to an AI agent. The agent decides when to call a tool, interprets the user’s request, and fills in the parameters.

Tools fall into these categories:

Data-intensive tools such as findRecords and findTasks can run synchronously or asynchronously, set through an optional execution option:

  • Synchronous: The query returns records directly. Best for fast queries.

  • Asynchronous: The server runs the query as a background job and returns a job ticket with a jobId, which the client polls or cancels.

  • Hybrid: The query runs synchronously up to a short timeout, then continues working in the background if it needs longer, avoiding client timeouts.

Metadata tools

These tools let the agent discover the MDM model (that is, entity names, columns, data types, and relationships) before running data queries.

Tool Description

listEntityIds

Lists lightweight identifiers for all entities the caller can access, across both the instance and master layers. Useful for basic discovery.

Returns a list of entities, each with its technical name, type (master or instance), and master view (for master entities).

listInstanceEntities

Lists instance-layer entities with their canonical technical names. Use it before the record tools to avoid casing or naming mismatches.

Returns a list of instance-layer entities with their technical names.

listMasterEntities

Lists master-layer (golden record) entities with their canonical technical names and associated master views.

Returns a list of master-layer entities with their technical names and master views.

getEntity

Retrieves the detailed metadata of a specific entity, including its attributes and relationships. Use it before writing a query to see which fields can be filtered or returned.

The labels and descriptions configured in your model are included in the response, which helps the agent choose the right fields.

  • Parameters: An entity reference (technical name, type (master or instance), and master view for master entities).

  • Returns: The entity’s metadata, including its attributes (technical name, data type, label, description) and relationships.

Data tools

These tools retrieve and search master and instance records.

Tool Description

getRecord

Retrieves a single record by its technical ID.

  • Parameters: An entity reference and the record ID.

  • Returns: The record’s data fields, mapped by their technical names.

getRecordWithRelation

Retrieves a record together with its related records in a single call, following the relationship paths you specify (for example, an author and that author’s company). The result can be narrowed with a JsonPath expression.

  • Parameters: An entity reference, the record ID, the relationship paths to follow, and an optional JsonPath filter.

  • Returns: The record and its related records as a nested structure, filtered by the JsonPath expression if one is provided.

findRecords

Searches for records using filter conditions, logical operators, and pagination.

  • Parameters: An entity reference, optional filter conditions, optional pagination (offset, limit, and whether to include a total count), and optional execution settings.

  • Returns: The matching records, mapped by technical field name, with an optional total count. When run asynchronously, it returns a job ticket instead.

By default, findRecords returns up to 30 records, up to a maximum of 1000 per request.

When building filters, follow these rules:

  • Use the canonical, case-sensitive field names returned by getEntity or the listing tools (for example, birth_date, not birthDate).

  • Join conditions with AND or OR (AND is the default).

  • Use only these operators: EQ, NE, GT, LT, GE, LE, CONTAINS, NOT_CONTAINS, BEGINS_WITH, NOT_BEGINS_WITH, ENDS_WITH, NOT_ENDS_WITH, IS_NULL, IS_NOT_NULL. Avoid SQL symbols and aliases such as =, LIKE, NEQ, GTE, or LTE.

  • Pass Boolean values as JSON Booleans (true/false), not as strings.

Task and draft tools

These tools browse and inspect workflow tasks and the draft changes attached to them.

Tool Description

findTasks

Lists workflow tasks, optionally filtered by ownership and by active or closed state.

  • Parameters: Optional filters for tasks assigned to the current user and for closed tasks, plus optional pagination and execution settings.

  • Returns: A list of task summaries, each with its ID, type, assignee, state, and creation time.

getTask

Retrieves the details of a specific task.

  • Parameters: The task ID, and optionally whether to look in closed tasks.

  • Returns: The task’s state, assignee, history, available workflow transitions, and the ID of any attached draft.

getDraft

Retrieves the proposed changes held in a draft, so they can be reviewed before the task is resolved.

  • Parameters: The draft ID, and optionally whether to look in closed tasks.

  • Returns: The proposed values associated with the task.

Administration tools

Tool Description

cancelJob

Cancels a running background job, such as an asynchronous search that is no longer needed.

  • Parameters: The job ID from a previous job ticket.

  • Returns: Confirmation that the job has been cancelled.

Resources and prompts

In addition to tools, the server can expose resources and prompts that you define in MDM Server application properties.

Resources are read-only text—instructions, schemas, or guidelines that the agent reads as context. For example, a party-search-strategy resource can tell the agent which view to search first.

Prompts are predefined instruction templates that let users trigger a complex query quickly, for example a search-party prompt.

Configuring resources

Resources are configured under the com.ataccama.mdm.mcp.resource.custom prefix.

com.ataccama.mdm.mcp.resource.custom.party-search-strategy.uri=mdm://instructions/custom/party-search-strategy
com.ataccama.mdm.mcp.resource.custom.party-search-strategy.name=party-search-strategy
com.ataccama.mdm.mcp.resource.custom.party-search-strategy.title=Party Search Strategy
com.ataccama.mdm.mcp.resource.custom.party-search-strategy.description=Information about default search and view configuration.
com.ataccama.mdm.mcp.resource.custom.party-search-strategy.text=By default, the 'masters' view is used for the 'party' entity. Search operations look up master records first, and if not found, search instance records.

Configuring prompts

Prompts are configured under the com.ataccama.mdm.mcp.prompt.prompt prefix.

com.ataccama.mdm.mcp.prompt.prompt.search-party.description=Search in master party entity
com.ataccama.mdm.mcp.prompt.prompt.search-party.prompt=Search in master party entity, use MCP tools, read definitions

Using resources and prompts in Claude Code

A connected client such as Claude Code can discover and use these capabilities:

  • /tools: Lists available programmatic tools.

  • /resources: Lists exposed custom resources.

  • /prompts: Lists available custom prompts.

To attach a resource as grounding context, reference it with @ followed by the resource name within your request, for example: Review @party-search-strategy and find the record for John Smith.

To run a prompt, use /prompts run <prompt-key> (for example, /prompts run search-party).

Example prompts

The following examples show how natural language questions could map to sequences of tool calls.

Look up a record and several of its attributes

User question: Find the product named "Aspirin 100mg" and tell me its product type, whether it’s a package product, and its validity dates.

The agent workflow:

  1. Calls listMasterEntities to identify the product entity and its master view

  2. Calls getEntity to resolve the exact column names for product type, package flag, and validity dates

  3. Runs findRecords with an EQ filter on the name.

  4. Reads the matching record and presents the requested fields in plain language.

Traverse a parent-to-child relationship

User question: Find the healthcare organization "City General Health" and list all medical facilities it operates.

The agent workflow:

  1. Runs findRecords on the hco entity to find the organization and its ID.

  2. Calls getEntity on the facility entity to find the foreign-key column that references the parent.

  3. Runs findRecords on facility filtered by that key.

  4. Lists the returned facilities.

User question: Show me the immediate child products of "Product Family A".

The agent workflow:

  1. Runs findRecords on product to get the parent’s ID.

  2. Queries the product-to-product relationship entity to retrieve the child IDs.

  3. Resolves child IDs back to product names with findRecords (or getRecord).

  4. Presents child entities as a list.

User question: Find the organization "Ataccma" [misspelled].

The agent workflow:

  1. Tries findRecords with an EQ filter, which returns no results.

  2. Retries the query with a CONTAINS or BEGINS_WITH filter on a partial form of the name.

  3. Identifies the closest match.

  4. Presents the closest match with a note about the spelling correction.

Review a pending change

User question: What change is being proposed in the open task for the person record "John Smith"?

The agent workflow:

  1. Calls findTasks (with fromClosed=false) to locate the active task.

  2. Calls getTask to read its state and the attached draftId.

  3. Calls getDraft to retrieve the proposed values.

  4. Compares the before and after states.

  5. Summarizes the pending modifications, for example in a table.

Was this page useful?