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.

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:

Both paths lead to the same form.

Fields in the form

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.

Which sign-in fits which server?

Whether a server supports OAuth and automatic registration is stated in its documentation or by its operator.

Static Headers

In the MCP server configuration, add one or more custom HTTP headers (for example Authorization: Bearer <your-token>) under Custom 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 below 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:

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), 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.

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.

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.

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.

Signed user identity (optional)

The cross-cutting concept is documented here: 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:

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 or Security & Authentication 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

Error "Invalid state parameter" or "OAuth flow expired" when connecting

When you click Connect, MeinGPT starts an authorization that is valid for 10 minutes and can be used only once. If signing in at the target system takes longer (for example because an administrator has to approve the app, MFA, or a tab left open), or if you open the return page a second time (reload, back button, reopening the link), MeinGPT rejects the sign-in with "Invalid state parameter" or "OAuth flow expired". The connection may nevertheless already have been saved, and no harm was done.

What to do:

1. Open Settings → Connectors and check whether the connector already shows as Connected. If it does, there is nothing more to do.
2. Otherwise close the old authorization window or tab.
3. Find the connector in Settings → Connectors and click Connect again (or send another chat request that uses the tool).
4. Finish signing in at the target system within 10 minutes, and leave the page alone until MeinGPT redirects you.

If the approval in the target system has to come from someone else, sort that out first and only then start the connection.

Warning "Some tools could not be loaded"

If this warning appears under a chat response, at least one connector active for that chat – a Custom MCP server or a ready-made connector such as Make – could not be loaded when the request started. That's a different failure than a failed tool call (see below): no tool was called yet, so there is no tool-call tile in the chat to expand.

The second line of the warning names the affected connector, for example "Failed tools: Make". The reason is not shown in the chat; it can currently only be traced in the backend logs. Check first yourself:

• Connection status: Open Settings → Connectors and see whether the affected connector 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 connector then shows as "Not connected" again, and clicking Connect signs you back in. If the requested scope is missing the piece needed for refresh tokens (often offline_access or a server-specific equivalent), this happens routinely – add that scope in the connector configuration. This state doesn't necessarily show up in chat as an error: the assistant simply stops calling the tool and falls back to something else instead (for example asking you to upload a file manually), rather than visibly flagging the expired connection.
• Reachability and speed: Is the MCP URL reachable from MeinGPT (no internal hostname without On-Premise Connections, no expired TLS certificate)? MeinGPT waits at most 30 seconds in total for the connection and the tool list; a slower server counts as failed.
• Size of the tool list: A server is skipped entirely if it advertises more than 100 tools, a tool list spread over more than 20 pages, tool definitions larger than 1 MB, tool definitions made up of more than 10,000 individual elements, or definitions nested deeper than 64 levels. Every single value in the definitions counts – objects, lists, texts, numbers – not just every tool: a parameter with a type and a description adds several elements. A few very elaborately described tools can therefore reach this limit although neither 100 tools nor 1 MB is exceeded. For depth, the tool list itself and each tool already count as levels. Across all active servers of a chat, tool definitions are also capped at 2 MB and 20,000 elements; a server that would exceed this is skipped. If the server lets you choose which tools or scenarios it exposes, reduce them to the ones you need.
• Rejected tools: If a single tool has a definition MeinGPT or the selected model can't process (for example an unsupported input schema or a tool name that appears twice), that tool is left out. The server's other tools still load, but the warning appears anyway.
• 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? Does the requested scope also cover tool listing (discovery), not just individual tool calls – a scope that's too narrow is one of the most common causes of this warning for manually configured servers.

Reconnecting does not fix the last three points. If you have already reconnected and the warning stays, the cause is usually not the sign-in. In that case contact support with your organization name, the connector name from the warning, and the approximate time of a chat where it appeared – the exact error is 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.

Large tool results: truncation and paging

If your MCP server returns a very large JSON payload (a long list of records, a big document, etc.), MeinGPT does not send the whole thing to the model. Each tool result is capped to a token budget (6,000 tokens by default, roughly 24,000 characters) before it reaches the model; the full response is still stored, and the model can retrieve the rest itself by calling the built-in expand_tool_result tool, page by page. This paging is separate from any pagination your own API already does (e.g. offset/limit parameters) — a model reading "page 2" from expand_tool_result is not the same as a second page of your API's own results, and mixing the two up is a common source of the assistant reporting wrong totals or seeing what looks like duplicate records.

MeinGPT also removes a small, fixed list of structural JSON keys (for example _links, _expandable) from every tool result before the model sees it, because in most connected systems those keys carry only navigation metadata, not domain data. If your server's API nests actual field values there — for example a HAL+JSON API where _links.status, _links.project, _links.type or _links.assignee hold the human-readable name of a reference field, not just a link — those values will not be visible to the assistant. If reference fields appear to go missing only for some records, or the assistant claims a status/assignee/project/type is unset when you can see it in the raw API response, this is worth ruling out: have your MCP server (or a projection step in front of it) return that data under a different key name than _links, e.g. flattened directly onto the record (status_name, assignee_name, ...).

To reduce truncation and token usage generally, keep tool responses focused: project down to the fields the assistant actually needs rather than returning the target system's full raw object. See Building MCP Tooling for guidance on shaping tool responses.

Next Steps

• JWT Identity Forwarding: the cross-cutting concept behind signed user identity
• Building MCP Tooling: develop your own MCP server with FastMCP instead of connecting an existing one
• Connecting to n8n MCP: a complete example of a Custom MCP Server with OAuth