Skip to content

MCP Gateway: Expose Workflows as MCP tools

MCP tools are defined as routes within a service. Each route is associated with a workflow that runs when an agent submits a tool request through the Model Context Protocol. Authentication settings determine which clients can invoke MCP tools and how they are authorized.

Here’s an overview of how to expose workflows as MCP services in Conductor:

  1. Create workflows that represent the actions your AI agents will perform
  2. Create an application with permission to execute the workflows. This is the service account layer.
  3. Configure authentication settings for the MCP service.
  4. Define an MCP service.
  5. Define and test routes.
  6. Connect the service with AI agents as an MCP tool.

5-minute path

Create the workflow, create an application with Execute permission on it, configure authentication, define a service, add a route with a clear tool description, test it, then connect the MCP endpoint to your AI agent.

Step 1: Create workflows that define tool behavior

The MCP Gateway allows you to expose Conductor workflows as APIs that can be called by an MCP tool. Before defining any MCP routes, ensure that the workflows implementing your endpoint logic are already created.

You can create workflows using the Conductor UI, APIs, or SDKs.

Step 2: Create an application in Orkes Conductor

An application in Orkes Conductor serves as the identity that the MCP Gateway uses when executing workflows on behalf of the AI agent.

To create an application:

  1. Go to Access Control > Applications, and select + Create application.
  2. Enter a name for the application.
  3. (Optional) Enable the required Application role based on how the service wants to interact with the application.
  4. In Permissions, select + Add permission.

  5. In the Workflow tab, select the workflow created in Step 1 and enable EXECUTE permission.

  6. Save the application.

Step 3: Configure authentication settings

Authentication controls how external agent systems connect to your MCP tools. You can configure these settings at the cluster level and reuse them across multiple services in the MCP Gateway.

To configure authentication settings:

  1. Go to APIs > Authentication from the left navigation menu on your Conductor cluster.
  2. Select + New authentication.
  3. Configure the following parameters:
Parameter Description Required/Optional
ID A unique identifier for the authentication configuration. This cannot be renamed once saved. Required.
Authentication Type The type of authentication to use. Supported values:
  • API Key–Enforces basic authentication using an API key.
  • No Authentication–No authentication is enforced, and the API will be accessible to anyone.
 Required.
API Key The API key for authentication. A random key is generated by default. You can also select Generate to create one instantly. Copy and store the key securely for future authentication. Required if Authentication Type is API Key.
Application Select the application created in Step 2, which generates an access key and JWT token. The MCP Gateway will use this token to authenticate with the Conductor. The service using this authentication will inherit the application’s permissions. Required.
  1. Select Save.

Step 4: Define an MCP service

A service is a logical container for MCP endpoints, referred to as routes. Routes within a service inherit common settings, including the base path, authentication configuration, and CORS (Cross-Origin Resource Sharing) policies. Each route maps to a workflow that the MCP Gateway invokes when the endpoint is called. You must create a service before you can add routes to it.

To define a service:

  1. Go to APIs > Services from the left navigation menu on your Conductor cluster.
  2. Select + New service.
  3. Configure the following parameters:
Parameter Description Required/Optional
Basic information
Service ID A unique identifier for the service. Use lowercase letters and hyphens, as this value is used in the API URLs. This cannot be renamed once saved. Required.
Display Name A user-friendly name for the service. Required.
Service Enabled Determines whether the service is active. Enabled by default. Switch it off if you do not want to activate the service immediately. Required.
MCP Enabled Determines whether the MCP is active for this service. Enabled by default. Switch it off if you don’t want to activate the MCP service immediately. Required.
API Configuration
Base Path The base path for all routes in the service. The path must start with a forward slash (for example,` /api/v1/users`). Including `api` in the path is optional. This cannot be renamed once saved. Required.
Auth Config The authentication configuration to use for this service. Select the configuration created in the previous step, or select + Create New Auth Config from the dropdown, and configure the authentication settings. Required.
CORS Configuration
Allowed Origins The origins (URLs) that can access this service. Press Enter after each URL to add multiple origins. Use * to allow all origins. Required.
Allowed Methods The HTTP methods that can be used in cross-origin requests. Supported values:
  • GET
  • POST
  • PUT
  • DELETE
  • PATCH
  • OPTIONS
 Required.
Allowed Headers The HTTP headers that can be sent in requests from allowed origins. Press Enter after each header to add multiple headers. Use * to allow all headers. Required.
Additional Information
Description A description of the service. Optional.
  1. Select Save.

Step 5: Define and test a route

Each endpoint in a service is defined as a route, and every route maps to a Conductor workflow that implements the endpoint’s logic.

To create a route within a service:

  1. Go to the Services and select the + button next to the service created.
  2. Configure the following parameters:
Parameter Description Required/Optional
Route Definition
HTTP Method The HTTP method for the route. Supported methods:
  • GET
  • POST
  • PUT
  • DELETE
  • PATCH
 Required.
Path The path for the request.
  • Must start with a forward slash. For example, `/update`.
  • Use {} for path parameters. For example, `/update/{userId}`.
 Required.
Description Use this field to describe the purpose and behavior of the route. When the route is exposed as an MCP tool, this description is provided to AI models to help them understand when and how to use the endpoint. Include details such as what the route does, expected inputs, output format, and typical use cases to ensure the model can invoke the route accurately. Optional.
Workflow Configuration
Workflow Name The workflow to be triggered by the route. Required.
Version The version of the workflow to use. If unspecified, the latest version will be used. Required.
Wait Until Tasks The task to wait for before returning a response. The API will return the output of this task, instead of the workflow output. This is useful if the workflow contains tasks that take a long time to complete, but a response from the API is required before the connection times out. Optional.
Timeout (seconds) The duration in seconds to wait before returning a response. Optional.
Schema
Input Schema The input schema for the request.
  • If you’ve created a schema in Conductor, select the schema and version to be used as the input schema for the request.
  • If not, enter your schema directly in the Code tab.
 Optional.
Output Schema The output schema for the request.
  • If you’ve created a schema in Conductor, select the schema and version to be used as the output schema for the request.
  • If not, enter your schema directly in the Code tab.
 Optional.
Query Parameters
Parameter Name The query parameter that can be accepted by the endpoint. Can contain only letters, numbers, underscores, and hyphens. Enable Required if the parameters are mandatory. Optional.
Transformation Scripts
Pre-request Script A JavaScript function to transform the incoming request payload before passing it to the workflow. The returned object becomes the workflow input. Use `$.fieldName` to access input fields. Example 
(function () {
return $.value1 + $.value2;
})();
Optional.
Test Pre-request Script Test the input processing script. To test the payload:
  1. In Test Payload, enter the values.
  2. Select Test Pre-request Script.
  3. In Test Result, verify the result to ensure the script is working.
 N/A
Post-response Script A JavaScript function to transform the final workflow output before it is returned in the API response. The returned object is sent as the API response. Use `$.fieldName` to access output fields. Example 
    (function () {
    return $.result * 2;
    })();
Optional.
Test Post-response Script Test the output processing script. To test the payload:
  1. In Test Payload, enter the values.
  2. Select Test Postresponse Script.
  3. In Test Result, verify the result to ensure the script is working.
 N/A
Cache Configuration
Cache Key Enables caching for a route. When caching is enabled, Conductor stores responses for repeated requests and returns the cached result for matching inputs until the entry expires. Optional.
TTL (Time To Live) in Seconds Set how long the cached value remains valid. Optional.
Rate Limit Configuration
Rate Limit Key Key used to identify the rate limit scope for this route. Can be [passed as a variable](/content/developer-guides/passing-inputs-to-task-in-conductor). Optional.
Concurrent Execution Limit Maximum number of concurrent executions allowed for this route. Optional.
  1. Select Save.

Test a route

You can test route behavior directly from the Conductor UI before exposing it as an MCP tool.

Run a test request

To test a route:

  1. Go to the APIs > Services, and select the service.
  2. In Routes, select the play icon next to the route to test.
  3. In Path Parameters, enter any required parameters for the endpoint.
  4. (If Authentication is using an API key) Replace *** with the API key copied in Step 3.
  5. In Body, enter the request payload as expected by the workflow.
  6. Select Test Route.
  7. Review the Response to verify the route works as expected.

Verify workflow execution

To confirm that the route triggered the workflow:

  1. Go to Executions > Workflow in your Conductor cluster and verify that the workflow is completed successfully.

  2. Select the Workflow ID to view the complete execution, including the workflow input and output.

View endpoint details

To get the cURL command:

  1. Go to APIs > Services, and select your service.
  2. Select a route to open its details.
  3. You can get the cURL command for the actual endpoint here.

To view the OpenAPI documentation for the endpoint:

  1. Go to APIs > Services, and select the service.
  2. In Metadata & Resources, select View API documentation.

Step 6: Connect the service with AI agents as an MCP tool

Next, you can connect this MCP service to your preferred AI tool as an MCP tool. You need the MCP endpoint URL for this.

To get the MCP tool endpoint:

  1. Go to APIs > Services, and select the service.
  2. In Configuration, copy the MCP Tool Remote Endpoint.

Use this as the MCP server endpoint when you configure your AI tool.

For example, you can use tools like Orkes MCP Workbench for testing and debugging your MCP endpoints before integrating them with an AI tool.

Verify using Orkes MCP Workbench

To test the endpoint in Orkes MCP Workbench:

  1. Access Orkes MCP Workbench.
  2. In Connections, select + Add.
  3. In URL, enter the MCP Tool Remote Endpoint copied from Conductor.

  4. In Type, select Streamable HTTP (Stateless).

  5. Leave authentication empty if the service uses no authentication. If the service requires authentication, provide the required key.

  6. Select Save, and then select Connect.

If the connection is successful, the tools exposed by the service become visible. In Select Tool, all available tools from the service are listed.

Each route in the service appears as an MCP tool. You can select a tool, provide input, and call it directly from the Inspector.

Each tool call triggers the workflow mapped to that route. This validation step helps ensure that your MCP service is correctly configured before connecting it to an AI agent.

Production notes

  • Write a specific, detailed route Description, since AI agents rely on it to decide when and how to invoke the tool.
  • Use API Key authentication for production services. No Authentication makes the endpoint callable by anyone with the URL.
  • Pin the route's Version once agents are using the tool, so a new workflow version doesn't silently change tool behavior.
  • Set a Rate Limit Key, Concurrent Execution Limit, and Timeout on routes, since agents may call or retry tools more aggressively than typical API clients.
  • Re-verify the tool in a workbench (such as Orkes MCP Workbench) after any route change, before relying on it in a live agent.

Examples

See an example of a ticket service called an MCP tool.

Monitor gateway metrics

Orkes Conductor's API and MCP Gateways provide built-in metrics at both service and route levels. These metrics help you monitor performance, identify usage trends, and troubleshoot issues in real time.

You can view metrics by selecting the Metrics tab from any service or route.

Performance metrics

Metric Description
Total Requests Total number of requests made to the service or route.
Request Rate Average number of requests per second.
Success Rate Percentage of successful workflow executions triggered by the service or route.
Avg Latency Average time (in milliseconds) taken to complete a request.

Statistics

The Statistics view provides detailed insights into request volume, latency patterns, and error trends for each service or route. Use this section to analyze performance behavior over time and identify issues that may need attention.

Requests

The Requests tab includes a line graph showing request volume over time. Use this view to monitor usage patterns, performance degradation, or abnormal error spikes across all routes in the service.

Latency

The Latency tab shows percentile-based response time distribution. Use this view to identify spikes or inconsistencies in performance.

  • P50 (median): Half the requests responded faster than this latency.
  • P95: 95% of requests completed faster than this latency.
  • P99: 99% of the requests are faster than this latency.

Errors

The Errors tab visualizes failure trends and error types.

  • Error Rate: Percentage of failed requests over time.
  • Error Breakdown: Types of errors returned (e.g., 400 Bad Request, 500 Internal Server Error) and their frequency.

Hover over the graph to inspect error events by timestamp. Use this to correlate API failures with recent deployments or configuration changes.