Introduction

The M42 Professional MCP server exposes platform data and actions to AI clients through the Model Context Protocol (MCP). An external AI client, such as Claude Code or an agent built in Microsoft Copilot Studio, connects to the server over OAuth 2.0. After that, the client can query templates and data cards, and create and update data cards, in natural language, without custom integrations or API scripting.

For example, support staff who work on tickets can ask questions in natural language in Microsoft Teams when the agent is built in Microsoft Copilot Studio.

The setup involves three systems: M42 Professional (the MCP server), Secure Access, which is the OAuth 2.0 identity provider based on Keycloak, and the AI client. This guide has three parts. The general setup covers the steps that are the same for every client: the M42 Professional side and the Secure Access side. Each client section then covers the steps for that client, including the registration of the client's callback URL in Secure Access. Troubleshooting, the data policy note, and related resources follow.

This guide covers external clients only. The built-in AI agents of M42 Professional do not need this setup. For the tool reference and the server settings, see MCP Server.

How the connection works

AI client (Claude Code or Microsoft Copilot Studio)
        |
        |  1. The user signs in through Secure Access (browser window)
        v
Secure Access (Keycloak)      <-- the client's callback URL is registered here
        |
        |  2. Secure Access issues an access token
        v
M42 Professional MCP server  (https://<your-m42pro-tenant>/itsm/mcp)
        |
        |  3. M42 Professional checks the token and identifies the  user
        v
MCP tools: list_templates, describe_template, list_datacards,
           create_datacard, update_datacard
        |
        |  4. Results are returned to the AI client
        v
AI client answers the user

Prerequisites

General setup (all clients)

Complete these three steps once for the tenant and the client you connect. The client-specific sections below refer back to them.

Step 1 — Create the MCP client scopes and the audience mapper

In the Keycloak admin console of Secure Access, create three client scopes with these names: mcp:read, mcp:create, and mcp:update. M42 Professional checks the scope names in the access token, so they must match exactly.

Create a mapper of audience type mcp-audience and add it to the scopes. The mapper adds the MCP server URL, https://<your-m42pro-tenant>/itsm/mcp, to the audience of the access token. M42 Professional accepts only tokens that carry this audience.

M42 Professional accepts a token that carries at least one of the three scopes. When you add the scopes to the client, set the type of each scope to Default, so that every token of the client carries that access. The scopes then do not depend on what the client requests.

Step 2 — Create the OAuth client

In the Keycloak admin console, go to Clients and select Create client. Use these settings:

After you create the client:

1. Open the Credentials tab and note the Client secret. You enter it in the client's settings (client-specific).
2. Open the Client scopes tab and add mcp:read, mcp:create, and mcp:update to the client with the type Default.
3. Leave Valid redirect URIs empty for now. You add the callback URL of the client in its own section.

Step 3 — Configure the M42 Professional settings (optional but recommended)

The MCP server is enabled by default. Adjust the settings in the M42 Professional Admin UI under System Settings, in the MCP server property group.

Setting names, defaults, and availability can change between M42 Professional versions. The values on this page apply to M42 Professional 2026.2.

Access control

Content filtering

Performance

Client-specific setup: Claude Code

Complete the general setup first. Then follow these steps to connect Claude Code.

• The user must exist in M42 Professional. M42 Professional resolves the username in the access token to a user.
• The tenant's Apache must allow /itsm/mcp through. Until it does, requests do not reach M42 Professional.

Step 1 — Register the callback URL in Secure Access

In the Keycloak admin console of Secure Access, go to Clients, select the client you created in general step 2, and open Settings.

1. In Valid redirect URIs, add http://localhost:8080/callback. Claude Code uses a local callback URL of the form http://localhost:PORT/callback and picks a random port unless you fix it. The next step fixes the port to 8080, so that it matches this entry. You can use another free port, as long as the redirect URI and the command use the same one.
2. In Web origins, add +.
3. Save.

The URL must be an exact match. Keycloak is case-sensitive and does not tolerate trailing slash differences or any other variation.

Step 2 — Add the server to Claude Code

Run this command in a terminal, and replace the placeholders with your values. Use the client ID from general step 2.

claude mcp add --transport http --client-id <your-client-id> --client-secret --callback-port 8080 <your-custom-mcp-name> https://<your-m42pro-tenant>/itsm/mcp

Claude Code asks for the client secret and hides what you type. Enter the client secret from general step 2. You can set the client secret only when you add the server. To change it, remove the server with claude mcp remove <your-custom-mcp-name> and add it again.

The options of the claude mcp add command are described in the Claude Code documentation.

Step 3 — Sign in and consent

In Claude Code, run /mcp and select the server to start the sign-in. Claude Code opens a browser window for the Secure Access sign-in and consent screen. Sign in with the M42 Professional user account. M42 Professional advertises the read, create, and update scopes together, so a sign-in can grant all three. A write-capable sign-in is still limited to the permissions of that user.

Client-specific setup: Microsoft Copilot Studio

Complete the general setup first. Then follow these steps to add the server to a Copilot Studio agent.

Step 1 — Add the MCP server in Copilot Studio

Follow the official Microsoft guide for the Copilot Studio UI steps: Connect your agent to an existing MCP server — Microsoft Learn

Use Option 1: MCP onboarding wizard (recommended). The tables below tell you which values to enter for M42 Professional.

Enter these server details:

Enter these OAuth 2.0 manual settings:

Do not enter or override the Redirect URL or Callback URL field manually. Copilot Studio generates this value. Overriding it causes a redirect URI mismatch.

After you select Create, Copilot Studio displays a callback URL (also called the redirect URL). Copy this URL for the next step.

Step 2 — Register the callback URL in Secure Access

If you skip this step, or do it incorrectly, the sign-in fails with Invalid parameter: redirect_uri.

In the Keycloak admin console of Secure Access, go to Clients, select m42pro-mcp-copilot (or the client ID you chose), and open Settings.

1. In Valid redirect URIs, paste the exact callback URL copied from Copilot Studio.
2. In Web origins, add +.
3. Save.

The URL must be an exact match. Keycloak is case-sensitive and does not tolerate trailing slash differences or any other variation.

Step 3 — Complete the connection in Copilot Studio

Continue in Microsoft Learn: Create a new connection and add the MCP server to your agent

Select Create a new connection. When prompted, sign in with an M42 Professional user account, and then select Add to agent.

The agent then has access to the tools of the M42 Professional MCP server: list_templates, describe_template, list_datacards, create_datacard, and update_datacard. The create and update tools work only when the sign-in grants the matching write scope. For what each tool does, see MCP Server.

Troubleshooting

General (all clients)

Claude Code

Microsoft Copilot Studio

Data policy note

Access to MCP servers in Copilot Studio goes through Power Platform connectors. If your organization has a data loss prevention (DLP) policy that restricts connectors, it also applies to the M42 Professional MCP connection.

See: Configure a data policy — Microsoft Learn

Related resources