Ataccama ONE Agentic ONE Desktop ONE DQ&C ONE MDM ONE RDM ONE Runtime Server
latest (17.2.0) 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
Downloads

MCP Server in MDM

This article describes the MDM MCP Server which exposes MDM metadata, records, matching proposals, 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.

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 lets AI agents work with MDM metadata, records, matching proposals, and tasks under the same permissions as human users.

The server is part of the MDM Server and is available in all deployment types (Ataccama Cloud, Custom Ataccama Cloud, self-managed). Tool calls are tracked in the MDM monitoring metrics.

AI agents don’t change master data directly. Any changes an agent proposes are captured in tasks and drafts, which follow the usual publishing and approval workflows.

Optionally, agents can also reject matching proposals and publish tasks on their own. See Autonomous resolution tools.

Because the MCP Server exposes raw metadata and master 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

Clients authenticate using the OAuth 2.0 Authorization Code grant with PKCE against a public OpenID Connect client registered 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 App.

In other words, the MCP Server reuses the existing MDM Web Application permissions. 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.

  • Rejecting a matching proposal requires the same reject permission on the proposal entity needed in the MDM Web App.

  • Resolving a task requires the publish permission on the task’s current workflow step. If publishing is allowed only from an approval step that the agent cannot reach, the agent can prepare changes but not publish them.

Agent actions are recorded in the same locations as other users' actions:

  • Audit log: Matching proposal rejections.

  • Task history: Task comments, draft operations, transitions, and resolutions.

We recommend giving agents their own user accounts so that the audit trail clearly separates human and agent actions. For more information about the underlying permission model, see Configuring Permissions and MDM Web App Permissions.

Data privacy considerations

When an agent reads or searches records, 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.

What agents can do

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. Everything an agent does runs under the permissions of the connected user (see Permissions), and the full list of tools with their parameters is what your MCP client shows after connecting.

Agents can:

The following sections describe each capability and show how natural language requests map to sequences of tool calls.

Explore the model and the data

Agents can discover the MDM model (entity names, columns, data types, relationships, and the labels and descriptions you maintain in the model) and read and search instance and master records, including related records. Column and row permissions apply to everything returned to the agent.

Look up a record and several of its attributes

User request: 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 request: 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 request: 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 request: 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.

Explain matching

Agents can read matching proposals and the matching configuration they come from, and explain why a proposal was created and why automated matching did not merge the records. For how key rules, matching rules, and proposal rules work, see How the Matching Step Works.

Explain why two records were not merged

User request: Party records 12345 and 67890 were flagged as a possible duplicate. Explain why the automated matching rules did not merge them, which rule came closest, and which test failed. Then recommend whether to merge or reject them.

The agent workflow:

  1. Calls getEntity on the party instance entity to find its matching ID.

  2. Calls getMatchingConfiguration to read the matching rules, proposal rules, and their tests.

  3. Calls getRecord for both records and reads their stored matching columns.

  4. Evaluates the tests of the closest matching rule against the stored values and names the test that failed.

  5. Explains which proposal rule matched and recommends merging or rejecting, with the reasoning.

No changes are made, so this works for any user who can view the data.

Browse tasks and drafts

Agents can browse workflow tasks and the drafts attached to them, and review the changes a task proposes before it is published.

Review a pending change

User request: 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.

Create and manage tasks

Agents can follow the same workflow a data steward does in the MDM Web App: create a task, record the proposed changes in a draft, and move the task through the workflow steps. The task description says what the agent proposes, and the first task comment says why, so you can see the agent’s reasoning in the task detail. For details about these actions, see Resolve Tasks.

In a draft, the agent can record only matching operations: merges, splits, and rematches.

It can, however, comment on, reassign, and move any task through the workflow, including record change tasks created in the MDM Web App, as well as create tasks of any type. The changes recorded in a draft are applied only when the task is published, either through the MDM Web App or by the agent where enabled (see Autonomous resolution tools).

A record can be part of only one pending matching operation in a draft, and a draft can hold only one split or rematch of instance records per matching. To accept several split proposals, use one task per proposal.

Create a manual match task for records the rules never compared

User request: Create a manual match task for party masters 76065 and 76066. Compare both records first and explain your decision in the task comment, then submit the task for approval. Don’t publish anything.

The agent workflow:

  1. Calls getRecord for both master records and compares them.

  2. Calls getMatchingConfiguration to find out why the records were never compared, for example, because data errors affected the matching keys.

  3. Calls createTaskWithDraft with type MANUAL_MATCH, a description of the merge, and a comment with the reasoning.

  4. Calls updateDraft to add a mergeMasters change with the chosen survivor.

  5. Calls listTaskWorkflows to find the transition to the approval step and calls transitionTask to submit the task.

The result is a manual match task in the MDM Web App, with the agent’s explanation in the task comment. The task is then published in the MDM Web App, so no autonomous resolution tools are needed.

Autonomous resolution tools

Optionally, an agent can also make final decisions without a human in the loop: reject matching proposals, and publish the changes recorded in a draft to master data. Each capability has its own setting, and a capability that isn’t enabled is also absent from the server’s tool listing. In Ataccama Cloud deployments, both are turned on. In self-managed deployments, enable them in the MDM Server application properties:

# Allow agents to reject matching proposals
ataccama.one.mdm.mcp.tools.proposal-rejection.enabled=true
# Allow agents to publish task drafts of any type and resolve tasks
ataccama.one.mdm.mcp.tools.task-resolution.enabled=true

For the full setup, see Enable autonomous resolution tools.

Even when enabled, each call runs under the caller’s own permissions (see Permissions). Without these capabilities, the same requests still work: the agent prepares the tasks and drafts, and the decisions are made in the MDM Web App.

Reject matching proposals

Rejecting a matching proposal is the final decision that the proposed merge or split is wrong, and it can’t be undone, same as in the MDM Web App. The agent must give its reasoning, which is recorded in the audit log and corresponds to the comment left when rejecting a proposal in the MDM Web App. Accepting a proposal goes through a task instead.

Rejected proposals are no longer listed as open but can be read on request.

Publish drafted changes

Publishing a task applies the operations recorded in its draft to master data. This applies to tasks of any type, including record change tasks originally drafted in the MDM Web App, so it is the only way an agent can change master data outside matching.

Publishing requires the publish permission on the task’s current workflow step, so it typically works only from an approval step.

If publishing fails, the error is recorded in the task history, and the task and its draft stay editable, so the agent can fix the draft and publish again.

Publishing a matching proposal task resolves the proposals the task was created from, and they are removed from the matching proposals listing. A previously rejected proposal for the same pair of master records is removed as well, and the rejection comment remains in the audit log.

Triage the matching proposal queue

User request: Go through all open matching proposals on the party entity. Reject the ones that are clearly not duplicates and explain why in the audit comment. For clear duplicates, create a merge task with your explanation, record the merge in the draft, and publish it. If you’re not sure, prepare the task and the draft and submit it for approval. Base your decisions on the matching rules and the record values, and report what you did with each proposal.

This request requires both capabilities to be enabled.

The agent workflow:

  1. Calls findMatchProposals to list the open proposals and getMatchingConfiguration to read the rules.

  2. Calls getMatchProposal for each proposal to compare the records.

  3. Sorts each proposal into one of three outcomes:

    • Clearly not a duplicate: Calls rejectMatchProposals with the reasoning as the audit comment.

    • Clearly a duplicate: Calls createTaskWithDraft with type MATCHING_PROPOSAL, updateDraft with the mergeMasters change, and resolveTask to publish the merge.

    • Uncertain: Calls createTaskWithDraft and updateDraft, then transitionTask to submit the task for approval. You then need to review and publish the task in the MDM Web App.

  4. Reports the decision and the explanation for each proposal.

Rejections are recorded in the audit log, and tasks with their comments, drafts, and history in the task detail in the MDM Web App.

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, such as 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 add a resource to the context of your request, reference it with an at sign (@) 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).

Was this page useful?