Set Up the MDM MCP Server

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

For an overview of the server, its tools, and how to use them, see MCP Server in MDM.

Prerequisites

A running MDM instance.
Administrator access to your MDM Keycloak realm.
An MCP-capable client, such as Claude Code, Cursor, or OpenCode.

Setup overview

Complete the following steps in order:

Configure Keycloak: Create the mcp client scope, add an audience mapper, and register the public client used by MCP clients.
Configure the MCP Server: Enable the server and configure the authentication settings.
Configure the MDM model: Add entity and column descriptions so agents can reason about your model.
Connect a client: Register the MCP Server in your AI client.

Step 1: Configure Keycloak

The MCP Server relies on Keycloak for authentication and token issuing. In your Keycloak realm, configure the following.

Create the MCP client scope

In the Keycloak Admin Console, go to Client scopes.
Select Create client scope.
Configure the scope as follows:
- Name: mcp
- Description: MCP Server access
- Type: None
- Protocol: OpenID Connect
- Include in token scope: Enable. This distinguishes MCP tokens from those of other clients.
- Display on consent screen: Enable.
  - Consent screen text: Access MDM MCP Server.

Add an audience mapper

To ensure tokens carry the correct audience claim, add an audience mapper to the mcp scope.

In the Keycloak Admin Console, go to Client scopes.
Select the mcp scope.
On the Mappers tab, select Configure a new mapper and choose Audience.
Configure the mapper as follows:
- Name: mcp-audience
- Included Custom Audience: urn:ataccama:mdm:mcp-server.
  
  Must match the value of ataccama.one.mdm.mcp.server.audience in the MDM Server application properties.
- Add to ID token: Disable.
- Add to access token: Enable.

Register the client

Register a public OpenID Connect client (for example, mdm-mcp-client) that MCP clients use to authenticate. This lets you control which redirect URIs are allowed.

In the Keycloak Admin Console, go to Clients.
Select Create client.
Configure the client as follows:
- Client type: OpenID Connect.
- Client ID: mdm-mcp-client.
- Client authentication: Disable (public client).
- Authentication flow:
  - Standard flow (Authorization Code): Enable.
  - Direct access grants: Disable.
  - Implicit flow: Disable.
Set Valid redirect URIs to match your client callback paths:
- Local clients: http://127.0.0.1/. Keycloak accepts any port for loopback addresses per RFC 8252, and matches any callback path.
- Remote web-based clients: Use an exact HTTPS callback, for example https://mcp-client.example.com/oauth/callback.
Set Valid post logout redirect URIs to + (same as redirect URIs).
Set Web origins to +. Required for browser-integrated clients such as Cursor.
On the Advanced tab, set Proof Key for Code Exchange Code Challenge Method (PKCE) to S256.
On the Client scopes tab, select Add client scope, choose mcp, and set the type to Default.

With the Default type, the mcp audience is included in the token even if the client does not request the scope explicitly.

Token and session lifetimes

By default, a Keycloak realm session expires after 30 minutes of inactivity (SSO Session Idle), after which users need to authenticate again. To avoid frequent logins from CLI and IDE clients, you can increase the following lifetimes on the client:

Access Token Lifetime: 8h.
Offline Session Idle: 7 days. This also requires enabling offline_access on the client and setting ataccama.one.mdm.mcp.server.scopes=offline_access.

Step 2: Configure the MCP Server

Enable and configure the server using the following MDM Server application properties:

# Enable the MDM MCP Server endpoint
ataccama.one.mdm.mcp.server.enabled=true
# Keycloak issuer URI used for JWT validation
ataccama.one.mdm.mcp.server.issuer-uri=${spring.security.oauth2.resourceserver.jwt.issuer-uri}
# Audience claim required in the client access token
ataccama.one.mdm.mcp.server.audience=urn:ataccama:mdm:mcp-server
# Optional scopes advertised to clients (for example, offline access). Turned off by default
# ataccama.one.mdm.mcp.server.scopes=offline_access
# Name of the MCP Server used during client discovery
spring.ai.mcp.server.name=mdm-mcp
# Endpoint path for streamable HTTP messages
spring.ai.mcp.server.streamable-http.mcp-endpoint=/mcp

The audience value must match the audience mapper you configured in Keycloak.

Enable autonomous resolution tools

In addition to reading data, explaining the matching logic, and creating related tasks and drafts, agents can also reject matching proposals or publish drafts on their own. To learn more and review the security implications, see Autonomous resolution tools.

Each tool has its own setting, and a tool that isn’t enabled is also absent from the server’s tool listing. In Ataccama Cloud deployments, both tools 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 property reference, see MDM Server Application Properties.

If enabled, each call a tool makes is still limited by the permissions of the connected user. To separate human and agent actions in the audit trail, give each agent its own MDM user account, and grant it the permissions matching its role: view permissions to explore data and explain matching, task and workflow permissions to prepare tasks and drafts, and the reject and publish permissions to make final decisions. See Configuring Permissions.

Step 3: Configure the MDM model (nme-model.xml)

Agents rely on the labels and descriptions of your entities and columns to understand your model and select correct fields for filters and output. They have no other knowledge of your schema or of technical abbreviations, so make sure these descriptions are complete and specific. For example, The 10-digit National Provider Identifier (NPI) of the facility.

The getEntity tool returns the labels and descriptions configured for each entity and column.

For details about how to update entity descriptions, see Creating an Instance Layer Model and Creating a Master Data Layer Model.

Step 4: Connect a client

Clients connect to the /mcp endpoint of the MCP Server and authenticate against Keycloak using the client ID you registered (for example, mdm-mcp-client). The MCP endpoint is available on the MDM Server port.

Local testing deployments: By default, the MCP URL is http://localhost:8051/mcp.
Cloud and self-managed deployments: Use the MDM server host, for example mdm-server-<host>/mcp or mdm-server.<host>/mcp.

To find the server URL, open the Swagger UI from the MDM Web App Admin Center.

Copy the Swagger UI URL and keep only the base, removing /swagger-ui/index.html at the end. Then append /mcp.

Swagger UI in the MDM Web App Admin Center

The following examples use the default local deployment URL as a placeholder. Replace it with the URL of your MDM server as needed.

Claude Code

claude mcp add --transport http --client-id mdm-mcp-client mdm-mcp http://localhost:8051/mcp

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "mdm-mcp": {
      "url": "http://localhost:8051/mcp",
      "auth": {
        "CLIENT_ID": "mdm-mcp-client"
      }
    }
  }
}

OpenCode (opencode.json)

{
  "mcp": {
    "mdm-mcp": {
      "type": "remote",
      "url": "http://localhost:8051/mcp",
      "oauth": {
        "clientId": "mdm-mcp-client"
      }
    }
  }
}

After you add the server, the client opens a browser to complete authorization:

If you’re already logged in: Confirm access to the MCP Server.
If you’re not logged in: Log in with your MDM credentials.

The MCP Server is now ready to use.

Was this page useful?