> For the complete documentation index, see [llms.txt](https://docs.elimity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elimity.com/mcp-reference-manual/step-by-step-deployment-guide.md). # Step-by-step deployment guide {% hint style="info" %} 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. {% endhint %} ## 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](https://oauth.net/2/grant-types/authorization-code/)). 2. To authenticate requests from the MCP server to Elimity Insights (via the [token exchange flow](https://oauth.net/2/token-exchange/)). The diagram below shows how these two flows fit into the full request path: ```mermaid sequenceDiagram participant C as MCP-Client participant CI as MCP-Client-idp participant S as MCP-Server participant SI as MCP-Server-idp participant EI as Elimity-Insights C->>CI: 1. SSO Dance CI->>S: 2. SSO Dance S->>C: 3. SSO Dance C->>S: 4. HTTP Request with access token S->>SI: 5. Exchange access token SI->>S: 6. New access token for Elimity Insights S->>EI: 7. HTTP request with exchanged token ``` 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](https://auth0.com/) 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. ```mermaid graph LR ElimityIDP["Your identity provider (SAML, OIDC, ...)"] --> |Users log in to the web application| ElimityInsights[Elimity Insights] MCPIDP["MCP identity provider"] --> |MCP clients authenticate| ElimityInsights[Elimity Insights] ``` ### 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](https://auth0.com/docs/get-started/auth0-overview/create-applications/regular-web-apps). Here are some specific attention points: 1. Enable [the Resource Parameter Compatibility profile](https://auth0.com/ai/docs/mcp/guides/resource-param-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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp#h_3d1a65aded)): 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](https://auth0.com/docs/secure/call-apis-on-users-behalf/on-behalf-of-token-exchange#prerequisites). Again we list some special attention points: 1. Make sure you [create a new API](https://auth0.com/docs/get-started/auth0-overview/set-up-apis) 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: ```json { "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 OptionValue TypeDefault ValueDecription
authorizationServersarray[string]Authorization server(s) trusted to issue access tokens for the MCP server.
baseUrlstringPublic URL of this MCP server's /mcp endpoint. Also used as the OAuth resource identifier that client tokens must be used for.
insightsBaseUrlstringBase URL of the Elimity Insights instance this MCP server calls on behalf of the user.
jwtValidationAudiencestring

Expected aud

claim on incoming access tokens. Must match the API identifier configured for the MCP client application.

jwtValidationIssuerstringExpected iss claim on incoming access tokens. Must match your authorization server's issuer URL.
jwtValidationJwksUristringJWKS endpoint used to fetch the public keys for verifying incoming access token signatures.
tokenExchangeAudiencestringAudience requested when exchanging the incoming token for a new one to call Elimity Insights.
tokenExchangeClientIdstringClient ID of the application this MCP server uses to authenticate itself when performing the token exchange.
tokenExchangeClientSecretstringClient secret paired with tokenExchangeClientId for the token exchange request.
tokenExchangeDomainstringAuthorization 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](/reference-manual/server-configuration.md). `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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.elimity.com/mcp-reference-manual/step-by-step-deployment-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.