---
title: "Custom MCP Server"
description: "Integration of custom MCP servers for extended functionality"
canonical_url: "https://meingpt.com/en/docs/integrations/custom-mcp-server"
language: en
---

# Custom MCP Server

With Custom MCP Servers, you can integrate your own functionalities into meinGPT. Connect your server via URL and extend the capabilities of your assistants.

For internal or on-premise targets, use the cross-cutting pattern [On-Premise Connections](/en/docs/integrations/connections-cloud-on-prem).

**For compliance and regulatory needs:** whether Custom MCP Servers are allowed at all in your organization is a central decision your workspace admin makes under **Settings → Tool Management** (the "Custom MCP" switch). If that capability is disabled there, you can still create and save your own MCP server connection under *Settings → Connectors*, but it will be removed server-side from every chat and cannot execute. See [Tool Access Policy](/en/docs/admin-guide/tool-access-policy) for the full precedence model.

## Server Configuration

To integrate a Custom MCP Server, you need a URL endpoint. There are two transport options:

### HTTP Streaming (Recommended)
```
https://your-server.com/mcp
```
This method uses HTTP streaming for efficient real-time communication.

### Server-Sent Events (SSE)
```
https://your-server.com/sse
```
Alternative method using Server-Sent Events for communication.

## Server Integration

There are two ways to add a Custom MCP Server:

Open **Settings → Connectors**, go to the **Custom MCP servers** section, and click **Add MCP server**. Servers added this way are available across all your assistants.

Open an assistant's tool configuration and switch to the **Custom MCP** tab. Servers added this way are bound to that assistant.

Both paths lead to the same form with the fields **Name**, **URL**, **Headers**, **Authorization**, and the **Signed user identity** toggle. For the URL, your server's endpoint is enough, usually at `/mcp`; SSE endpoints (`/sse`) work as well.

## Authentication Options

Custom MCP Servers support three independent authentication mechanisms: static headers, authorization (OAuth), and JWT Identity Forwarding. You can combine them, but see the "Precedence" section below if more than one targets the same header.

### Static Headers

In the MCP server configuration, add one or more custom HTTP headers (for example `Authorization: Bearer <your-token>`) under **Headers**. Use this for servers protected by a static API key, or by a static token at the edge (e.g. a WAF or reverse proxy in front of your MCP endpoint).

### Authorization

The **Authorization** field in the MCP server configuration offers three modes:

- **None** – no sign-in, or the headers above already carry the credential.
- **OAuth: register automatically (DCR)** – meinGPT registers itself with the server; everyone signs in with their own account. Works with most servers.
- **OAuth: my own client** – for servers without automatic registration. Register meinGPT once in their admin console (client ID, client secret, authorization endpoint, token endpoint, token endpoint authentication); everyone then signs in with their own account.

### Setting up a manual OAuth client

Choosing **OAuth: my own client** reveals additional fields. Their values come from the target system's admin console, where you register meinGPT once as an OAuth application.

**The redirect URL to enter there is:**

```
https://<your-meinGPT-address>/oauth/callback
```

On meinGPT Cloud that is `https://app.meingpt.com/oauth/callback`. If you run meinGPT under your own domain, use that address with the same path. Without an exactly matching redirect URL, the server aborts the sign-in.

Then fill in these fields in meinGPT:

| Field | Meaning |
| --- | --- |
| **Client ID** | The ID of the application you created in the target system. Required. |
| **Client secret** | The matching secret. Required – except for **Public client**. When editing later, leave the field blank to keep the stored secret. |
| **Authorization endpoint** | Where meinGPT sends you to sign in, e.g. `https://your-server.com/oauth/authorize`. Must be `https`. |
| **Token endpoint** | Where meinGPT exchanges the code for a token, e.g. `https://your-server.com/oauth/token`. Must be `https`. |
| **Token endpoint authentication** | How meinGPT identifies itself at the token endpoint: **Client secret (body)** (default), **Client secret (Basic header)**, or **Public client (no authentication)**. The target system's documentation says which applies; when in doubt, try the default first. |
| **Scope (optional)** | Space-separated scopes for meinGPT to request. Leave blank to let the server decide – you only need this for servers that don't negotiate a scope themselves (OpenProject, for example, requires `mcp`). |

If the server publishes its OAuth metadata, meinGPT reads the endpoints when you open the form and prefills them. You'll see the note "Endpoints below were read from the server" and only need to add the client ID and secret. If it says "This server can register meinGPT on its own" instead, you don't need a manual client – use **OAuth: register automatically (DCR)**.

The credentials belong to this one connector, not to the URL. Two people can add the same server with different OAuth applications without overwriting each other.

Selecting an OAuth mode alone does not open an authorization window. As with other connectors (see [Enabling connectors](/en/docs/integrations/connectors#enabling-connectors)), the OAuth flow only starts once meinGPT actually needs to use the server - for example when you send a message in a chat with the assistant that causes it to call the tool. You'll then see a prompt in the chat with a **Connect** button; only clicking it opens the MCP server's authorization page. Alternatively, you can trigger the connection manually without a chat: open **Settings → Connectors**, find the connector, and click **Connect** there. For a full worked example with screenshots, see [Connect to n8n MCP](/en/docs/integrations/connect-n8n-mcp#6-connect-tool).

Error "OAuth is disabled for this MCP URL": authorization applies per person and per individual connector instance, not globally to the MCP URL. If you see this error on your own connection attempt even though OAuth works for someone else (e.g. the person who created the connector), authorization on your own connection is (still) set to **None**. Open the connector configuration under **Settings → Connectors**, choose **OAuth: register automatically (DCR)** or **OAuth: my own client**, and connect again. If no configuration is available to you there, add the Custom MCP Server yourself with the same connection details (URL, headers if any) and choose an OAuth mode explicitly while doing so.

### Precedence

If you configure both a static `Authorization` header and set authorization to an OAuth mode for the same server, and the connection succeeds, **OAuth takes over the `Authorization` header** — your static value is not sent. The two options are not mutually exclusive in the configuration UI, so avoid setting both for the same server unless you intend OAuth to take priority once connected. JWT Identity Forwarding is unaffected by this, since it is sent in a separate `X-meinGPT-JWT` header (see below).

The form points this out right away: as soon as a header is named `Authorization` (case doesn't matter) and authorization is not set to **None**, a red note appears under that header row — "OAuth sets this header itself. This value will be ignored." You can still save; the note blocks nothing, because the same header is legitimate again the moment you switch back to **None**. When you see it, you have a choice: set authorization to **None** to authenticate with the header, or delete the header and let OAuth do the work.

## Making a server available to colleagues

A custom MCP server initially belongs to you alone: it appears under **Settings → Connectors** in your account, and nobody else sees it. There is no sharing switch on the server itself – the path runs through an assistant.

How the connection behaves for your colleagues after that depends on the authentication type:

- **Static header (fixed token / API key):** The connection acts as one shared, central connection. As soon as you add the server with a static header to an assistant, every authorized user of that same assistant automatically uses that token too — with no separate setup or sign-in. You effectively provide the shared "service account" for everyone. Note: everyone then acts with that token's permissions, so scope it as narrowly as possible.
- **OAuth:** Here each person authenticates individually, as described in the flow below.
- **JWT Identity Forwarding:** Attaches automatically to every request for whoever is using the assistant — there is no separate setup, sign-in, or Connect step for this mechanism. It works independently of and alongside the other two: enabling it doesn't change whether a personal OAuth sign-in is also required.

Open an assistant's tool configuration and enable your MCP server there.

Share the assistant with a team or the whole organization (see [Assistants](/en/docs/platform/assistants)). The server becomes reachable along with the assistant.

On the first tool call in a chat, a **Connect** button appears. Each person goes through the OAuth flow with their **own** account in the target system and sees only what they are allowed to see there. Your sign-in is not handed on.

With OAuth, in addition: once connected, the server also shows up for your colleagues under **Settings → Connectors**, marked with a **Shared** badge. Those entries are read-only: URL, headers, and authorization can't be changed and the entry can't be deleted – only **Disconnect** is available, which revokes that person's own sign-in. Configuration and deletion stay with whoever created the server.

The same holds for a manual OAuth client: the single stored client ID and secret are meinGPT's registration with the target system – they are not a user account and grant no data access on their own. Everyone using the assistant still signs in personally.

If the server's **Authorization** is set to **None**, step 3 above does not apply: there is no personal sign-in for a "Connected"/"Not connected" status to attach to. Once the server is reachable through the assistant, everyone with access to the assistant can use it — with the same static credentials, if any are configured. If such a server still shows problems, that's not a missing personal sign-in but a reachability or configuration issue with the server itself (see "Warning 'Some tools could not be loaded'" below).

## Example: connecting OpenProject

OpenProject offers an MCP server but no automatic client registration – a typical case for the manual OAuth client. OpenProject's MCP server is an Enterprise add-on and has to be enabled there.

Go to **Administration → Authentication → OAuth applications** and create a new application. Enter `https://app.meingpt.com/oauth/callback` as the **Redirect URL** (or your own meinGPT address with that path), select the **mcp** scope, and mark the application as **Confidential**. Note down the **Client ID** and **Client secret** – the secret is shown only once.

Open **Settings → Connectors → Custom MCP servers → Add MCP server**. For the URL, enter `https://your-openproject-instance.com/mcp`.

Set **Authorization** to **OAuth: my own client** and fill in:

- **Client ID** and **Client secret** from step 1
- **Authorization endpoint**: `https://your-openproject-instance.com/oauth/authorize`
- **Token endpoint**: `https://your-openproject-instance.com/oauth/token`
- **Token endpoint authentication**: **Client secret (body)**
- **Scope**: `mcp`

Save.

Click **Connect** on the connector's row, sign in to OpenProject, and confirm the access. You can then attach the server to an assistant and ask about work packages in chat. OpenProject currently exposes read-only tools over MCP.

## Signed user identity (optional)

The cross-cutting concept is documented here: [JWT Identity Forwarding](/en/docs/integrations/jwt-identity-forwarding).

For custom MCP servers, you can enable the **Signed user identity** toggle in the MCP configuration. When enabled, meinGPT sends this additional header on each request:

```http
X-meinGPT-JWT: <signed-jwt-token>
```

The token includes claims such as:
- `sub` (user ID)
- `email`
- `username`
- `aud` (organization ID)
- `organizationName`
- `role`
- `teams`

To verify this token on your server, use the central guide [JWT Identity Forwarding](/en/docs/integrations/jwt-identity-forwarding) or [Security & Authentication Proxy](/en/docs/integrations/custom-ai-apps/security-auth-proxy).

## Best Practices

- **Security**: Use HTTPS for all server connections
- **Monitoring**: Monitor server performance and availability
- **Error Handling**: Implement fallback options for server outages
- **Documentation**: Document server-specific functions and parameters

## Troubleshooting

### Warning "Some tools could not be loaded"

If this warning appears under a chat response, at least one of the Custom MCP servers active for that chat could not be reached when the request started – that's a different failure than a failed tool call (see below): the server or its authorization already failed before any call was made, so there is no tool-call tile in the chat to expand.

meinGPT currently doesn't show which server was affected or why – that can currently only be traced in the backend logs. Check first yourself:

- **Connection status**: Open **Settings → Connectors** and see whether the affected server is still shown as "Connected". For OAuth servers (registered automatically or with your own client), meinGPT automatically deletes the stored credentials once a token has expired and can't be refreshed (for example because the server doesn't issue a refresh token, or the refresh itself fails) – the server then shows as "Not connected" again, and clicking **Connect** signs you back in.
- **Reachability**: Is the MCP URL reachable from meinGPT (no internal hostname without [On-Premise Connections](/en/docs/integrations/connections-cloud-on-prem), no expired TLS certificate)?
- **For a manual OAuth client**: Do the token endpoint, token endpoint authentication, and scope still match the target system's admin console? Was the client registration revoked there in the meantime, or the secret rotated?

If this doesn't resolve it, contact support with your organization name, the name of the affected Custom MCP server, and the approximate time – more detailed error messages are currently only visible in the backend logs, not in the user interface.

If a remote MCP server rejects a request with a 401/403 or an authentication-related error, first confirm which auth mechanism actually sent the request: open **Settings → Connectors** and check the connector's status. If it shows "Connected", **OAuth is active and overrides any static `Authorization` header** you configured (see "Precedence" above) - set **Authorization** to **None** in the connector configuration if you intend to authenticate with your static header instead, then reconnect.

If a tool call fails, click the corresponding tool call tile in the chat to expand it. This shows the request that was sent, along with the response or raw error message from your MCP server - the fastest way to identify why a call failed without having to search your own server logs.

## Next Steps

- [Learn more about Assistants](/en/docs/platform/assistants)
- [Explore Make Integration](/en/docs/integrations/make-integration)
- [Discover Database Integration](/en/docs/integrations/connectors/mcp-database)