> ## Documentation Index
> Fetch the complete documentation index at: https://docs.germainux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enable the MCP Server

> Turn on the GermainUX MCP Server, choose how AI clients sign in, and control what they can do.

Components
[`Engine`](https://docs.germainux.com/deploy/germain-ux-engine)

Availability
2026.3 or later

This page is for GermainUX administrators. Once the MCP Server is on, each user connects their own AI client. See [Connect an AI Client](https://docs.germainux.com/integrations/mcp-server/connect-an-ai-client.md).

> [!NOTE]
>
> The MCP Server is **off by default**.

## How AI clients sign in

AI clients can sign in to the MCP Server in two ways. You can enable both, and the server tells them apart automatically.

| | **OAuth sign-in** (recommended) | **API key** |
| - | - | - |
| How a user connects | Adds the server URL to their AI client, then signs in with their normal GermainUX login and approves the client | Pastes an API key into the client's configuration as a bearer token |
| Login methods supported | All of them: form, LDAP, database and SSO | Not applicable |
| Expiry | Access tokens are short-lived and renew automatically | Depends on the API key |
| Works with | Claude, ChatGPT, Claude Code, Cursor, VS Code and other clients that support MCP OAuth | Clients that let you set a custom `Authorization` header |
| Server setup | One-time setup below. Needs a service restart. | Bearer authentication must be enabled |

## Turn on the MCP Server

**1. Open the MCP settings**

Open the configuration console and go to **Services → REST → MCP**.

**2. Enable it**

Click **Enable**.

![The germain.apm.services.rest.mcp configuration page with the Enable button highlighted](https://mintcdn.com/germain-ux/CECS6ywIQd1P2KNL/images/image-213.png?fit=max\&auto=format\&n=CECS6ywIQd1P2KNL\&q=85\&s=15a30da78b530e04703f16bf875b0051)

The MCP configuration with the Enable button highlighted

This takes effect immediately on every node, without a restart. Turning it off again takes the MCP endpoint offline straight away.

The endpoint URL is your GermainUX address followed by `/mcp`, for example `https://example.cloud.germainux.com/mcp`.

## Set up OAuth sign-in (recommended)

With OAuth, users connect by entering only the endpoint URL in their AI client. The client then opens a browser window where the user logs in to GermainUX and approves access.

**1. Open the OAuth server settings**

Go to **Services → REST → MCP → OAuth Server** and set **Enabled** to on.

**2. Set the issuer**

Set **Issuer** (`issuer`) to the address users reach GermainUX on, for example `https://example.cloud.germainux.com`. The MCP endpoint is then `<Issuer>/mcp`.

Leave **Login Page** (`loginPage`) and **Consent Page** (`consentPage`) at their defaults unless your workspace is served from a different address.

![OAuth server configuration with the Issuer field filled in](https://mintcdn.com/germain-ux/CECS6ywIQd1P2KNL/images/image-215.png?fit=max\&auto=format\&n=CECS6ywIQd1P2KNL\&q=85\&s=95e999cc8145bcae02ac3c1dada3f054)

The OAuth server configuration with the Issuer set

**3. Check which AI clients are allowed**

Claude, ChatGPT and clients that run on the user's machine are allowed by default. See [Allowed AI clients](#allowed-ai-clients).

**4. Restart the REST service**

OAuth settings are only read at startup.

> [!WARNING]
>
> If the OAuth settings are invalid (for example, a missing or malformed **Issuer**), the MCP Server stays offline. The rest of GermainUX starts normally. The service log explains what to fix.

### Allowed AI clients

GermainUX only issues tokens to clients you have allowed. The defaults cover Claude, ChatGPT and clients that run on the user's machine, so most installations don't need to change anything here.

| Setting | Default | What it allows |
| - | - | - |
| **Allow Loopback Redirects** (`allowLoopbackRedirects`) | On (`true`) | Clients that run on the user's machine, such as Claude Code, Cursor and VS Code. These clients receive their sign-in result on an `http://localhost` or `http://127.0.0.1` address. |
| **Allowed Client ID URLs** (`allowedClientIdUrls`) | `https://claude.ai/` `https://chatgpt.com/` | Hosted clients that identify themselves with a client metadata URL. Enter `https://` URL prefixes. |
| **Allowed Redirect URIs** (`allowedRedirectUris`) | `https://claude.ai/api/mcp/auth_callback` `https://chatgpt.com/connector_platform_oauth_redirect` | Hosted clients that register themselves automatically. Enter their exact callback URLs. |

To allow another hosted AI client, add its client metadata URL or callback URL to the matching list. To block one, remove its entries. For example, remove the `chatgpt.com` entries to stop ChatGPT from connecting. Turn off **Allow Loopback Redirects** to block clients that run on users' machines.

### Session lifetimes

> [accordion] Advanced: token and approval lifetimes
>
> Enter these values in seconds.
>
> | Setting | Default | Meaning |
> | - | - | - |
> | Access Token Time To Live (`accessTokenTimeToLive`) | 600 (10 minutes) | How long one access token is valid. Clients renew it automatically. |
> | Refresh Token Time To Live (`refreshTokenTimeToLive`) | 604800 (7 days) | A client that isn't used for this long has to sign in again. |
> | Consent Max Idle Time (`consentMaxIdleTime`) | 7776000 (90 days) | After this long without use, the user is asked to approve the client again. |
> | Registered Client Max Idle Time (`registeredClientMaxIdleTime`) | 2592000 (30 days) | A self-registered client that isn't used for this long has to register again. |

## Use API keys (alternative)

Use a GermainUX API key if your AI client can't use OAuth, or if you're connecting an automated agent.

**1. Enable bearer authentication**

Make sure bearer (API key) authentication is enabled in your authentication settings.

**2. Create an API key**

Create an API key for the user the AI client should act as from the GermainUX workspace.

![The API Key dialog with Name, Expires and permission options](https://mintcdn.com/germain-ux/CECS6ywIQd1P2KNL/images/image-216.png?fit=max\&auto=format\&n=CECS6ywIQd1P2KNL\&q=85\&s=8597d3f7264aaa0400cad998a8c6ff6e)

Creating an API key

**3. Hand it to the user**

Give the user the endpoint URL and the key. They add it to their client as an `Authorization: Bearer <key>` header.

> [!WARNING]
>
> API keys don't expire on the short OAuth schedule. Store them like passwords and rotate them regularly.

## What users can see and do

* Every tool call runs **as the signed-in user** (or the API key's user). That user's permissions, team-based visibility and data-masking settings apply exactly as they do in the workspace.
* Almost all tools only read data. The exception is `update_ux_profile_customizations`, which changes UX monitoring profile scripts. It requires the configuration-write permission, and its changes only apply to new sessions.
* `search_content` is only offered when a content indexer is configured.

## Limit which tools are offered

To hide tools from all AI clients, add their names to **Disabled Tools** under **Services → REST → MCP**. For example, add `update_ux_profile_customizations` to make the server strictly read-only. This takes effect immediately, without a restart.

See [Available Tools](https://docs.germainux.com/integrations/mcp-server.md#available-tools) for all tool names.

## Query limits

These limits protect GermainUX's query capacity for dashboards and alerting. They apply per server node and take effect immediately.

| Setting | Default | Meaning |
| - | - | - |
| Tool Deadline Seconds | 60 | A tool call that runs longer is cancelled, and the AI client is asked to narrow its query. |
| User Queries Per Minute | 300 | Maximum queries per user per minute |
| Client Queries Per Minute (`clientQueriesPerMinute`) | 600 | Maximum queries per AI client (across all its users) per minute |
| User Concurrent Queries | 2 | Queries one user can have running at once |
| Global Concurrent Queries (`globalConcurrentQueries`) | 8 | MCP queries running at once across all users |

When a limit is hit, the AI client gets a message explaining what to change or how long to wait. It can usually recover by itself.

## Monitor MCP usage

Every MCP tool call is recorded in the **Audit Log**. This includes calls that failed or were stopped by a [query limit](#query-limits).

**1. Open the Audit Log**

In the workspace, go to **System → Audit Log** and select the **MCP Tool Call** tab. You need the configuration-write permission to see this tab.

**2. Find the calls you're interested in**

The list shows each call's time, tool and user, for the selected time range. Use the search bar to filter by tool or user.

![Audit Log screen with the MCP Tool Call tab selected, listing tool calls by time, tool and user](https://mintcdn.com/germain-ux/CECS6ywIQd1P2KNL/images/image-217.png?fit=max\&auto=format\&n=CECS6ywIQd1P2KNL\&q=85\&s=e6433e0e1458d397fb643820868ffa8a)

MCP tool calls in the Audit Log

**3. Open a call for details**

Click a call to see:

* whether it succeeded or failed, and how long it took
* the AI client that made the call (for OAuth sign-in)
* the error, if it failed
* the arguments the AI client sent. For `run_scripted_query`, the script is shown separately as code.
* the result. Small results are shown in full. Larger ones are summarized, for example as a row count rather than the rows themselves.

![Audit Log details panel for an MCP tool call, showing status, duration, client, arguments and result](https://mintcdn.com/germain-ux/CECS6ywIQd1P2KNL/images/image-218.png?fit=max\&auto=format\&n=CECS6ywIQd1P2KNL\&q=85\&s=0f4fb9a49768281a15f054b99269c5a6)

Details of one MCP tool call

> [!TIP]
>
> Each call is also recorded as an `Audit:MCP Tool Call` fact, so you can analyze MCP usage like any other GermainUX data.

## Next steps

> [card] [Connect an AI Client](https://docs.germainux.com/integrations/mcp-server/connect-an-ai-client.md)
>
> Add GermainUX to Claude, ChatGPT, Cursor, VS Code and more.

> [card] [Example Prompts](https://docs.germainux.com/integrations/mcp-server/example-prompts.md)
>
> See what you can ask, and how the tools answer.

## Get Help

> [card] [Contact GermainUX Support](https://docs.germainux.com/getting-started/support.md)
>
> The GermainUX team helps you get up and running faster, empower your team, turn data into actionable insights, and optimize performance to deliver measurable business outcomes.

> [card] Can't Find What You Need?
>
> Search all GermainUX docs with **Ctrl + K**, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.