# Celonis MCP Server Integration with Amazon Quick

This topic walks you through integrating the Celonis Agent Tools (MCP) Server with Amazon Quick. Once the integration is complete, you will have a Quick agent that can call Celonis MCP tools to query your knowledge models and retrieve process intelligence data.

## Available Celonis MCP tools

The Celonis Agent Tools asset provides the following tools that can be enabled for your agents in Amazon Quick:

Note
In this topic, we use `Get Knowledge Model`, `Load Data`, and `Search Data` as examples. Enable whichever tools best fit your use case.

| **Tool** | **Description** |
|  --- | --- |
| `Call Process Copilot` | Surface existing Process Copilots as tools |
| `Execute Orchestration` | Trigger new Orchestration Engine process instances |
| `Get Insights` | Used to answer a question like "How can I improve DPO?" and see Celonis-generated Insights |
| `Get Knowledge Model` | Used to get the knowledge model for the current asset |
| `Get Process Contexts from Orchestration Engine` | Retrieves Process Contexts from Orchestration Engine process instances |
| `Load Data` | Equips the LLM with data access for review and analysis. Ideal for summarizing or retrieving data before processing |
| `Resume Orchestration Execution` | Resume execution of an Orchestration Engine process instance |
| `Search Data` | Search all data instances available in the platform |
| `Trigger Action Flow` | Connect your Process Copilot to an existing Action Flow and instruct your Process Copilot when to surface this action to users |


## Prerequisites

Before you begin, ensure that you have:

* A Celonis account with access to Agent Tools (MCP) Asset enabled for your team;
* Administrative access to your Celonis team in order to create OAuth clients;
* An AWS account with permissions to configure Amazon Quick;
* A Celonis Knowledge Model published in Studio.


## Step 1: Create your Agent Tools asset

1. Open **Studio** and navigate to the Studio package containing your Knowledge Model.
2. Click **+ New asset → Agent Tools (MCP)**.

3. Configure the new MCP asset:
  * **Asset Name**: MCP Server (or your preferred name)
  * **Knowledge Model**: Select your target Knowledge Model
4. Click **Create**.

5. In the new asset, click **Add Tools**.
6. Select and configure tools based on your requirements. For this example, we used:
  * `load_data` - Retrieve specific columns and rows from knowledge model entities.
  * `get_knowledge_model` - Discover entities and columns in the knowledge model.
  * `search_data` - Run keyword searches across the knowledge model.
7. Use the toggle switches to enable the tools you want to use and then save the asset.



## Step 2: Set up authentication

The Celonis MCP Server supports two OAuth 2.0 grant types. Both types are also supported by Amazon Quick.

| **Grant Type** | **Use Case** |
|  --- | --- |
| Client Credentials (2LO) | Agents and automated workflows where no human login is required. |
| Authorization Code (3LO) | User-facing applications where MCP calls should respect the individual user's Celonis permissions. |


1. In the Celonis Platform, navigate to **Admin & Settings → Applications**.
2. Click **Add New Application → OAuth Client**.

3. Configure the OAuth client based on your preferred grant type:
**For Client Credentials (2LO):**
| **Setting** | **Value** |
|  --- | --- |
| Grant Type | `Client Credentials` |
| Authentication Method | `Client Secret Basic` and `Client Secret Post` |
| Scope | `mcp-asset.tools:execute` |
**For Authorization Code (3LO):**
| **Setting** | **Value** |
|  --- | --- |
| Grant Type | `Authorization Code` |
| Redirect URI | `https://us-east-1.quicksight.aws.amazon.com/sn/oauthcallback` |
| Authentication Method | `Client Secret Basic` and `Client Secret Post` |
| Refresh Token | Enabled |
| Scope | `mcp-asset.tools:execute` |
4. Click **Define Scopes**.

5. Expand the **mcp** scope group and select **mcp-asset.tools:execute**.

6. Click **Create**.
7. **Important**: Copy and securely store the credentials (displayed only once):
  * Client ID
  * Client Secret


### Grant permission to the Agent Tools asset

Warning
Without the **Use** permission assigned, token requests will succeed but the MCP Server rejects tool calls with an authorization error.

1. In the Celonis Studio, open the package containing your Agent Tools asset.
2. Click **Package Settings → Permissions**.

3. Search for the OAuth client application that you created above (e.g., "OAuthClientCelonis").
4. Grant the **Use** permission to your new OAuth client.

5. Click **Save**.


## Step 3: Deploy the MCP Server

1. Open the Agent Tools (MCP) asset in Celonis Studio.
2. Click **Create Version**.
3. Click **Deploy** to publish the MCP Server.

4. Once the deployment has finished, copy the **MCP Server URL**. It will have a format similar to this example:
`https://<team>.<realm>.celonis.cloud/studio-copilot/api/v1/mcp-servers/mcp/<server-id>`

5. Save this URL for the AWS configuration.


### Connection details summary

After completing the steps above, you should have the following values:

| **Value** | **Description** |
|  --- | --- |
| MCP Server URL | Displayed at the top of your published Agent Tools asset |
| Token URL | `https://<team>.<realm>.celonis.cloud/oauth2/token` |
| Client ID | From the OAuth client creation |
| Client Secret | From the OAuth client creation |


## Step 4: Create the Quick integration

1. In Amazon Quick, navigate to **Connectors → Create for your team**.
2. Select **Model Context Protocol** from the list of available integration types.

3. Click **Create Integration** and complete the following fields:
  * **Name:** A descriptive name for the integration (e.g., Celonis MCP).
  * **Description:** (Optional) A short description of what this integration provides.
  * **MCP Server Endpoint URL:** Paste the MCP Server URL copied from Celonis.
4. On the **Authenticate** tab, select the appropriate authentication method:
  * **Service Authentication** for Client Credentials (2LO)
  * **User Authentication** for Authorization Code (3LO)
5. Enter the following connection parameters:
**For Client Credentials:**
| **Parameter** | **Value** |
|  --- | --- |
| Grant Type | Client Credentials |
| Client ID | Your OAuth Client ID |
| Client Secret | Your OAuth Client Secret |
| Access Token URL | `https://<team>.<realm>.celonis.cloud/oauth2/token` |
**For Authorization Code (with PKCE):**
| **Parameter** | **Value** |
|  --- | --- |
| Grant Type | Authorization Code (with PKCE) |
| Client ID | Your OAuth Client ID |
| Client Secret | Your OAuth Client Secret |
| Access Token URL | `https://<team>.<realm>.celonis.cloud/oauth2/token` |
| Authorization URL | `https://<team>.<realm>.celonis.cloud/oauth2/authorize` |
| Redirect URI | `https://us-east-1.quicksight.aws.amazon.com/sn/oauthcallback` |
| Authentication Methods | Client Secret |
6. Click **Create and continue** to proceed.

7. Save the integration and wait for Quick to complete tool discovery.
8. Verify that Quick discovers the tools you enabled on the Agent Tools asset.



Note
If Quick reports that discovery found no tools, the most common cause is that the OAuth client does not have the **Use** permission on the Agent Tools asset. Return to [Step 2](#grant-permission-to-the-agent-tools-asset) above and verify that permission was granted.

## Step 5: Build a Quick agent

1. In Amazon Quick, navigate to **Chat agents** and click **+ (Create chat agent)**.
2. Paste a system prompt that instructs the agent how to use the Celonis tools. Example:



```
   You are an assistant that answers questions using data from Celonis.
   When a question involves process data, call get_knowledge_model to discover
   the relevant entities, then load_data to retrieve specific columns and rows.
   Cite the tool and the entity you used for each fact in your answer.
   Do not invent data that was not returned by a tool call.
```

1. Confirm that your Celonis MCP integration is selected in the **Actions** section.
2. Click **Launch chat agent**.
3. Test your agent by asking: *"What tools can you access in Celonis?"*
4. Confirm the agent responds with the list of tools you enabled and references the Celonis MCP integration.



## Conclusion

You have successfully connected your Celonis MCP Server to Amazon Quick. Quick users can now invoke Celonis process mining capabilities including data loading, knowledge model retrieval, and data search directly from their AI assistant without leaving the Quick interface.

For additional information on managing integrations in Quick, refer to the [Amazon Quick](https://docs.aws.amazon.com/quick/) documentation.

## Best Practices

### Security

* Store your OAuth Client ID and Client Secret securely. Do not share them in plain text or commit them to version control.
* Use a dedicated OAuth Client for each integration to limit the blast radius of a credential compromise.


### Configuration

* Always deploy the Celonis MCP Server before attempting to connect from Quick. Connections to undeployed servers will fail.
* Use the Discovery URL method when available to simplify token endpoint configuration.


### Scopes

* Ensure the scope `mcp-asset.tools:execute` is correctly appended to the Token URL. Missing or malformed scopes are a common source of authentication failures.


### Troubleshooting

| **Symptom** | **Likely cause** | **Resolution** |
|  --- | --- | --- |
| Authentication error from Celonis | Invalid credentials or missing scope | Verify Client ID, Client Secret, and scope `mcp-asset.tools:execute` |
| Tool discovery returns no tools | Missing `Use` permission | Grant the OAuth client `Use` permission on the Agent Tools asset package |
| Token exchange fails | Incorrect Token URL | Verify the URL matches `https://<team>.<realm>.celonis.cloud/oauth2/token` |
| Tool calls return authorization error | OAuth client lacks asset permission | Grant `Use` permission via **Package Settings → Permissions** in Celonis |
| MCP Server URL not found | Asset not deployed | Open the asset in Studio and click **Deploy** |