Step-by-step deployment guide

This guide is only relevant for customers deploying the Elimity Insights MCP server on-prem. For our SaaS customers we can perform most of this work behind the scenes.

1. Setting up an authorization server

The first step in deploying the Elimity Insights MCP server is setting up an OAuth2 authorization server. This server is needed for two reasons:

1. To authenticate requests from MCP clients (e.g. Claude, ChatGPT) to the MCP server (via the authorization code flow).

2. To authenticate requests from the MCP server to Elimity Insights (via the token exchange flow).

The diagram below shows how these two flows fit into the full request path:

In theory these two tasks could each be handled by a different authorization server, but in practice using one single authorization server for both is often the most simple solution. More specifically, we recommend Auth0 as they have good support for both flows but any OAuth2 authorization server meeting these requirements should work. In this guide we will use Auth0 as an example when describing setup steps for the authorization server.

Note: The authorization server used for MCP is independent from whichever identity provider Elimity Insights uses for its own web application logins (configured via oidcIssuer). This is illustrated below.

1.1 Setting up an application for the MCP client

As mentioned above, the MCP client authenticates to our MCP server by walking through an OAuth2 authorization code flow at the authorization server. To do this, the MCP client usually needs a client ID and client secret, which typically requires creating an application at the authorization server first. In the case of Auth0 we recommend registering a regular web application as described in their official documentation. Here are some specific attention points:

1. Enable the Resource Parameter Compatibility profile in your Auth0 tenant

2. Use the MCP server URL as identifier for the new API you create

3. Make sure the new application has 'User-Delegated API Access' to this API

In general make sure the application allows the authorization_code grant type and supports authentication with a client secret. Also take care to configure the correct callback URL, which depends on your MCP client. The table below lists some unauthoritative examples:

MCP client	Callback URL
ChatGPT	https://chatgpt.com/connector/oauth/{callback_id}
Claude	https://claude.ai/api/mcp/auth_callback

Securely note down the newly created application's client ID and secret.

1.2 Setting up the MCP client

With the client ID and secret from step 1.1 you can now set up the MCP client. The exact setup steps are client-specific, please consult your AI tool's official documentation for detailed information. As an example we mention some attention points when performing this setup in a Claude organization (based their official documentation):

1. SaaS customers should use the MCP server URL as communicated by their Elimity account manager; it typically resembles https://mcp.example.elimity.com/mcp

2. Use the 'Advanced settings' to enter your aforementioned client ID and secret

3. Leave 'register one automatically' unchecked

1.3 Setting up an application for the MCP server

The final setup step related to MCP authorization is making sure the MCP server can exchange the token it receives from the MCP client for a different token to authenticate itself against Elimity Insights. Here we'll also need a client ID and secret and thus typically a new application at the authorization server. In the case of Auth0, we recommend setting up an API and a custom client as described in their official documentation. Again we list some special attention points:

1. Make sure you create a new API for the MCP server first

2. Only from there you can create the new 'Custom API client' application

3. You need to grant this application 'User-Delegated API Access' for the API corresponding with the MCP client application you set up in step 1.1

More generally you should make sure the application allows the urn:ietf:params:oauth:grant-type:token-exchange grant type and supports authentication with a client secret. Of course the application should also recognise the tokens issued for the (other) application from step 1.1, which might require complex configuration if you're using two different authorization servers.

Securely note down the newly created application's client ID and secret.

2. Configuring the MCP server

Having performed the necessary authorization setup we can now start configuring the MCP server itself. To do this, mount a JSON configuration file at /app/config/config.json with the properties listed below. The following snippet provides a good starting point:

{
  "authorizationServers": ["https://example.eu.auth0.com"],
  "baseUrl": "https://mcp.elimity.example.com",
  "insightsBaseUrl": "https://elimity.example.com",
  "jwtValidationAudience": "https://mcp.elimity.example.com/mcp",
  "jwtValidationIssuer": "https://example.eu.auth0.com/",
  "jwtValidationJwksUri": "https://example.eu.auth0.com/.well-known/jwks.json",
  "tokenExchangeAudience": "example-mcp",
  "tokenExchangeClientId": "example-client-id",
  "tokenExchangeClientSecret": "example-client-secret",
  "tokenExchangeDomain": "example.eu.auth0.com"
}

The table below describes each supported configuration option in more detail:

Configuration Option	Value Type	Default Value	Decription
authorizationServers	array[string]		Authorization server(s) trusted to issue access tokens for the MCP server.
baseUrl	string		Public URL of this MCP server's /mcp endpoint. Also used as the OAuth resource identifier that client tokens must be used for.
insightsBaseUrl	string		Base URL of the Elimity Insights instance this MCP server calls on behalf of the user.
jwtValidationAudience	string		Expected aud claim on incoming access tokens. Must match the API identifier configured for the MCP client application.
jwtValidationIssuer	string		Expected iss claim on incoming access tokens. Must match your authorization server's issuer URL.
jwtValidationJwksUri	string		JWKS endpoint used to fetch the public keys for verifying incoming access token signatures.
tokenExchangeAudience	string		Audience requested when exchanging the incoming token for a new one to call Elimity Insights.
tokenExchangeClientId	string		Client ID of the application this MCP server uses to authenticate itself when performing the token exchange.
tokenExchangeClientSecret	string		Client secret paired with tokenExchangeClientId for the token exchange request.
tokenExchangeDomain	string		Authorization server domain the MCP server sends token exchange requests to.

Note: The values configured here must correspond to the mcpJwtValidation settings on the Elimity Insights server. tokenExchangeAudience must match Insights' mcpJwtValidation.audience, and the authorization server domain set in tokenExchangeDomain must match Insights' mcpJwtValidation.issuer. This is how Insights validates and accepts the token the MCP server presents on the user's behalf after the token exchange.