Getting Started

The Celonis MCP Server Asset provides a growing set of ready-to-use tools that AI agents can use to search for relevant information, get real-time process context, trigger actions in external systems, and write back decisions to Celonis. Delivered securely via the Model Context Protocol (MCP), this toolkit makes it easy to build sophisticated agents that leverage Process Intelligence.

Prerequisites

Before you begin, ensure you have the following:

  1. A Celonis account with access to MCP Server Asset enabled for your team
  2. An MCP-compatible client to connect to the MCP Server (e.g., Claude Desktop, Postman, etc.)
  3. Administrative access to your Celonis team to create OAuth clients or Application Keys

Step 1: Create and Configure Your MCP Server in Celonis

Before setting up authentication, you need to create and publish an MCP Server asset in Celonis:

  1. Log in to your Celonis account with access to MCP Server Asset
  2. Navigate to Studio and select your desired package
  3. Create an MCP Server Asset
    • Create a new asset with the type "MCP Server"
  4. Configure the MCP Server
    • Add the desired tools to your MCP Server
    • Configure the tools according to your needs
  5. Publish the Asset
    • Once configured, publish the asset
    • After publishing, a link for the published asset will appear at the top of the asset
    • This link is your MCP Server URL (format: https://[team].[realm].celonis.cloud/studio-copilot/api/v1/mcp-servers/mcp/[mcp-server-id] )
    • Save this URL - you will need it when connecting to the MCP Server from your client

A correctly setup MCP Server would look like this: MCP Server

Step 2: Set Up Authentication

The Celonis MCP Server supports two authentication methods. Choose the option that best fits your use case:

Option A: OAuth 2.0 Authentication (Recommended)

OAuth 2.0 is the recommended authentication method for production use. The MCP Server supports two OAuth grant types:

  • Client Credentials : Best for server-to-server communication and automated workflows
  • Authorization Code : Best for applications that act on behalf of users

Create an OAuth Client in your Celonis platform with the following requirements:

Using Client Credentials Grant Type:

  • Grant Type : Client Credentials
  • Authentication Method : Client Secret with one or both of the following:
    • Client secret basic
    • Client secret post
  • Scope : mcp-asset.tools:execute (under the MCP scope group)

Using Authorization Code Grant Type:

  • Grant Type : Authorization Code
  • Redirect URI : Configure with your application's redirect URI (e.g., https://oauth.pstmn.io/v1/callback with Postman)
  • Authentication Method : Client Secret with one or both of the following:
    • Client secret basic
    • Client secret post
  • Refresh Token : Enable if supported by your client
  • Scope : mcp-asset.tools:execute (under the MCP scope group)

After creating the OAuth Client, save your Client ID and Client Secret - you will need these to connect to the MCP Server.

Option B: Application Key Authentication

Application Keys provide a simpler authentication method but with fewer security features compared to OAuth. This method is suitable for testing and development purposes.

Create an Application Key in your Celonis platform. After creation, save your Application Key - you will need this to connect to the MCP Server.

Step 3: Grant Permissions to Your MCP Server Asset

After creating your OAuth Client or Application Key, you must grant it permissions to access your MCP Server asset. Grant the 'use' permission to your MCP Server asset for the OAuth Client or Application Key you created.

This step is crucial to allow your client to access the MCP Server. Without proper permissions, connection attempts will fail.

Step 4: Connect to the MCP Server

Now you're ready to connect to your MCP Server from your MCP-compatible client. The connection details you'll need depend on your authentication method:

Connection Information

You'll need the following information to connect:

  • MCP Server URL : The URL you saved in Step 1 (format: https://[team].[realm].celonis.cloud/studio-copilot/api/v1/mcp-servers/mcp/[mcp-server-id] )
  • Team URL : Your Celonis team URL (e.g., https://[team].[realm].celonis.cloud )

For OAuth 2.0 Authentication:

Client Credentials Grant Type:

  • Access Token URL : https://[team].[realm].celonis.cloud/oauth2/token
  • Client ID : Your OAuth Client ID
  • Client Secret : Your OAuth Client Secret
  • Scope : mcp-asset.tools:execute
  • Grant Type : client_credentials

Authorization Code Grant Type:

  • Grant Type : Authorization Code (With PKCE)
  • Redirect URI : The redirect URI you configured when creating the OAuth Client
  • Access Token URL : https://[team].[realm].celonis.cloud/oauth2/token
  • Authorization URL : https://[team].[realm].celonis.cloud/oauth2/authorize
  • Client ID : Your OAuth Client ID
  • Client Secret : Your OAuth Client Secret
  • Code Challenge Method : SHA-256
  • Scope : mcp-asset.tools:execute

For Application Key Authentication:

  • Authentication Type : Bearer [your-application-key]

Example: Connecting to the MCP Server from Postman with OAuth 2.0 and Authorization Code Grant Type:

  1. Go to File > New... and select "MCP Request".
  2. Select HTTP as the protocol to connect to the MCP Server (STDIO is used for local development).
  3. In the Authorization tab, select OAuth 2.0 and fill in the details as mentioned above.
    • Redirect URI: https://oauth.pstmn.io/v1/callback

A correctly configured MCP Request would look like this:

MCP Request

  1. Once you obtain the access token, use it to connect to the MCP Server by clicking the "Connect" button. You should now see a list of the tools you configured in your MCP Server asset:

MCP Tools List

  1. Fill in the required parameters for the tool you want to execute and click the "Run" button. You should see the result of the tool execution:

MCP Tool Execution Result

Troubleshooting

If you encounter any issues, please check the following:

  • Ensure your MCP Server asset is published and the MCP Server URL is correct
  • Verify that your OAuth Client or Application Key has been granted the 'use' permission for your MCP Server asset
  • Confirm your OAuth Client has the correct scope ( mcp-asset.tools:execute )
  • For OAuth 2.0, verify that the token URL and authorization URL match your team's realm
  • Check that your Client ID and Client Secret are correct and haven't been regenerated