--- url: 'https://docs.workato.com/en/airo/mcp.md' description: >- Connect any MCP-compatible AI client to your Workato workspace using OAuth 2.0 or an API token, and manage your automation projects using natural language. --- # AIRO MCP server {: #airo-mcp-server :} The AIRO MCP server exposes Workato AIRO's full platform capabilities to MCP-compatible AI clients, including Claude Code, Claude Desktop, Cursor, ChatGPT, and Codex CLI. This enables you to build recipes, manage Genies, create MCP servers, and manage data table schema directly from your AI development environment using natural language. ![AIRO as an MCP server](/images/airo/airo-mcp.gif)*AIRO as an MCP server* ## How it works {: #how-it-works :} The AIRO MCP server supports two authentication methods: * **OAuth 2.0**: Recommended for interactive clients. Your MCP client opens a browser window the first time you connect. The window displays Workato's authorization screen, which lists the permissions requested by the client. Click **Authorize** to complete the connection. Refer to [Connect using OAuth 2.0](#connect-using-oauth-2-0) for the setup steps. * **API token**: Recommended for headless or configuration-driven setups. Pass a Workato API token as a bearer header. Refer to [Connect using an API token](#connect-using-an-api-token) for the setup steps. The server exposes tools organized into the following categories: | Category | What you can do | | -------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Recipes | Create, edit, search, and manage recipes, including step-level operations, field mapping, conditions, and connections | | Skills and MCP | Convert recipes to skills and create or manage MCP servers | | Custom connectors | Build, edit, and save custom connector SDK code | | Genies and knowledge bases | Create and configure Genies, manage knowledge bases, and assign knowledge sources | | Blueprints and assets | Work with blueprints, asset maps, and asset metadata | | Data | Create and manage data table schema | | Jobs and tests | Inspect job history and manage test cases | Use the `help` tool within your MCP client to get detailed information about any specific tool, including input schemas and usage guidance. The AIRO MCP server respects your Workato account permissions for OAuth 2.0 connections, or the permissions of the API client role for API token connections. All actions performed through the MCP server follow the same access controls as actions performed in the Workato platform. The [activity audit log](/en/features/activity-audit-log.md#airo-attribution) attributes actions that the AIRO MCP server takes on your behalf to your user account with a `(via AIRO)` label. ## Prerequisites {: #prerequisites :} You must have the following before you configure the AIRO MCP server: * A Workato account with AIRO access * An MCP-compatible client installed, such as Claude Code, Claude Desktop, Cursor, ChatGPT, or Codex CLI Some MCP client configurations use `npx`. These configurations require [Node.js](https://nodejs.org/) to be installed and available in your `PATH`. Run `node -v` in your terminal to verify your installation. API token authentication also requires a Workato API token. Refer to [Generate an API token](#generate-an-api-token) for instructions. ## Data center server URLs {: #data-center-urls :} The AIRO MCP server URL depends on the [data center](/en/datacenter/datacenter-overview.md) where your Workato workspace is hosted. Developer Sandbox workspaces always use the trial URL. Use the server URL that matches your workspace region: | Data center | AIRO MCP server URL | | -------------------------------------------------------------- | ---------------------------------------- | | US | `https://app.workato.com/airo_mcp` | | EU | `https://app.eu.workato.com/airo_mcp` | | JP | `https://app.jp.workato.com/airo_mcp` | | SG | `https://app.sg.workato.com/airo_mcp` | | AU | `https://app.au.workato.com/airo_mcp` | | IL | `https://app.il.workato.com/airo_mcp` | | KR | `https://app.kr.workato.com/airo_mcp` | | UK | `https://app.uk.workato.com/airo_mcp` | | Developer Sandbox | `https://app.trial.workato.com/airo_mcp` | {: .api-quick-reference :} The AIRO MCP server isn't available in the CN data center. Refer to [feature availability in the China data center](/en/datacenter/cn-data-center.md#feature-availability) for more information. ## Connect using OAuth 2.0 {: #connect-using-oauth-2-0 :} Complete the following steps to connect the AIRO MCP server to your MCP client using OAuth 2.0: ::: tip WORKSPACE AND ENVIRONMENT SCOPE OAuth 2.0 scopes each AIRO MCP server connection to the Workato workspace and environment active in your browser session. Sign in to the target workspace and environment before you start authorization. Repeat the authorization steps for a different workspace or environment, or create a separate connection for each workspace and environment you need to access at the same time. ::: ::::: tabs type:border-card :::: tab Claude Code id="claude-code-oauth" Open your terminal. Run the following command to add the AIRO MCP server: ```bash claude mcp add --transport http workato-airo-mcp-server https://YOUR_DATA_CENTER/airo_mcp ``` Run the following command to start a new Claude Code session and open the `/mcp` panel: ```bash claude /mcp ``` Use the arrow keys to select `workato-airo-mcp-server`, then press **Enter** to confirm. Press **Enter** on **Authenticate**. Click **Authorize** in the browser window that opens, then close the tab and return to Claude Code. Verify the connection by running `/mcp` again. `workato-airo-mcp-server` should appear with a connected status. Confirm the server responds by prompting Claude Code. For example, `List my Workato projects.` Refer to [Claude Code's MCP documentation](https://code.claude.com/docs/en/mcp#installing-mcp-servers) for more configuration options. :::: :::: tab Claude Desktop id="claude-desktop-oauth" Open Claude Desktop. Go to **Settings > Developer** and click **Edit Config** to open `claude_desktop_config.json`. You can also open the file directly: * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` * Windows: `%APPDATA%\Claude\claude_desktop_config.json` Add the following configuration: ```json { "mcpServers": { "workato-airo-mcp-server": { "command": "npx", "args": [ "mcp-remote", "https://YOUR_DATA_CENTER/airo_mcp", "--transport", "http-first" ] } } } ``` Save your changes, restart Claude Desktop, and start a new chat. Complete Workato authentication in the browser window that opens, then click **Authorize**. Check the MCP server status under **Settings > Developer** if the connection fails. Confirm the server responds by prompting Claude. For example, `List my Workato projects.` :::: :::: tab Cursor id="cursor-oauth" Open your Cursor MCP configuration file. Edit it directly for all projects, or use `.cursor/mcp.json` in a project root to scope the server to that project. * macOS and Linux: `~/.cursor/mcp.json` * Windows: `%USERPROFILE%\.cursor\mcp.json` You can also open the file from the **Customize** page in the Cursor desktop app by selecting **MCPs > + New**. Add the following configuration: ```json { "mcpServers": { "workato-airo-mcp-server": { "command": "npx", "args": [ "-y", "mcp-remote", "https://YOUR_DATA_CENTER/airo_mcp" ] } } } ``` Save your changes. Start a new chat with the Cursor agent. ::: warning START A NEW CHAT Start a new chat with your agent after saving changes. Cursor agents only have access to the tools and capabilities available when a chat begins. Agents can't detect or use MCP configurations, servers, or tools added after a chat starts. ::: Complete Workato authentication in the browser window that opens, then click **Authorize**. Verify the connection. On the **Customize** page, select **MCPs** and confirm that the server appears with its tools and resources. Prompt your Cursor agent to confirm that the server responds. For example, `List my Workato projects.` Refer to [Cursor's MCP documentation](https://cursor.com/docs/mcp#using-mcpjson) for more configuration options. :::: :::: tab ChatGPT id="chatgpt-oauth" ChatGPT requires **Developer mode** to connect to remote MCP servers. Developer mode grants ChatGPT read and write access to your AIRO tools. OpenAI classifies developer mode as an advanced feature with elevated risk, so refer to [their developer mode guide](https://developers.openai.com/api/docs/guides/developer-mode) for details before you enable it. Sign in to ChatGPT on the web with a Pro, Plus, Business, Enterprise, or Education account. Developer mode isn't available in the desktop or mobile apps. Go to **Settings > Security and login > Developer mode** and enable the **Developer mode** toggle. Go to [ChatGPT Plugins](https://chatgpt.com/plugins) and click **+** to add a new plugin. This button appears after you turn on developer mode. Enter `workato-airo-mcp-server` in the **Name** field. Optional. Enter a description for your MCP server in the **Description** field. Set the server URL to the following value in the **Connection** field: ```text https://YOUR_DATA_CENTER/airo_mcp ``` Use the **Authentication** drop-down menu to select **OAuth**. Select the **I understand and want to continue** checkbox, then click **Create**. Click **Sign in with workato-airo-mcp-server** in the dialog that appears. Complete Workato authentication in the browser window that opens, then click **Authorize**. Verify the connection by trying the app in a new conversation. Open a new chat in ChatGPT. Click the **+** button near the message composer, then select your app from the list of available tools to add it to the conversation context. Prompt the model to use the app. For example, `List my Workato projects.` :::: :::: tab Codex CLI id="codex-cli-oauth" Open your terminal. Add the AIRO MCP server: ```bash codex mcp add workato-airo-mcp-server \ --url https://YOUR_DATA_CENTER/airo_mcp ``` Codex may detect that the server supports OAuth and open the authorization flow automatically. If the browser doesn't open or the authorization flow doesn't start, run: ```bash codex mcp login workato-airo-mcp-server ``` Complete Workato authentication in the browser window that opens, then click **Authorize**. Verify that the server is configured: ```bash codex mcp list ``` The output should include `workato-airo-mcp-server`. Start a new Codex session so the MCP server and its tools are initialized: ```bash codex ``` Inside Codex, enter `/mcp` to inspect the active MCP servers. Confirm the server responds by prompting Codex. For example, `List my Workato projects.` Refer to [Codex's MCP documentation](https://developers.openai.com/codex/extend/mcp) for more configuration options. :::: ::::: ## Connect using an API token {: #connect-using-an-api-token :} API token authentication requires a Workato API token. ### Generate an API token {: #generate-an-api-token :} Complete the following steps to obtain an API token: Sign in to Workato. Go to **Workspace admin > API clients > Client roles**. Open an existing client role or [create a client role](/en/workato-api/api-clients.md#create-a-client-role). Enable the **AIRO MCP** feature for the role. ![The AIRO MCP feature enabled in the Project assets list of a client role](/images/airo/mcp/client-role.png)*Enable the AIRO MCP feature for the client role* Click **Save changes**. Assign this client role to an existing API client, or select the role when you [create a new API client](/en/workato-api/api-clients.md#create-an-api-client). Copy and securely store the API client token. ### Configure your MCP client {: #configure-your-mcp-client-with-an-api-token :} Complete the steps for your MCP client: ::::: tabs type:border-card :::: tab Claude Code id="claude-code-api-token" Open your terminal. Add the following line to your shell profile (`~/.zshrc`, `~/.bash_profile`, or equivalent), replacing `` with the token you generated: ```bash export WORKATO_API_TOKEN="" ``` Restart your terminal, or reload your profile: ```bash source ~/.zshrc # or your shell's profile file ``` Add the server, referencing the environment variable in the authorization header: ```bash claude mcp add --transport http workato-airo-mcp-server https://YOUR_DATA_CENTER/airo_mcp \ --header 'Authorization: Bearer ${WORKATO_API_TOKEN}' ``` Use single quotes around the header. This stores the literal `${WORKATO_API_TOKEN}` reference in your configuration, and Claude Code expands it when it connects. Run the following command to start a new Claude Code session and open the `/mcp` panel: ```bash claude /mcp ``` `workato-airo-mcp-server` should appear with a connected status. Confirm the server responds by prompting Claude Code. For example, `List my Workato projects.` Refer to [Claude Code's MCP documentation](https://code.claude.com/docs/en/mcp#installing-mcp-servers) for more configuration options. :::: :::: tab Claude Desktop id="claude-desktop-api-token" Open Claude Desktop. Go to **Settings > Developer** and click **Edit Config** to open `claude_desktop_config.json`. You can also open the file directly: * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` * Windows: `%APPDATA%\Claude\claude_desktop_config.json` Add the following configuration, replacing `` with the token you generated: ```json { "mcpServers": { "workato-airo-mcp-server": { "command": "npx", "args": [ "mcp-remote", "https://YOUR_DATA_CENTER/airo_mcp", "--transport", "http-first", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer " } } } } ``` Save your changes. Restart Claude Desktop and start a new chat. Check the MCP server status under **Settings > Developer** if the connection fails. Confirm the server responds by prompting Claude. For example, `List my Workato projects.` :::: :::: tab Cursor id="cursor-api-token" Open your Cursor MCP configuration file. Edit it directly for all projects, or use `.cursor/mcp.json` in a project root to scope the server to that project. * macOS and Linux: `~/.cursor/mcp.json` * Windows: `%USERPROFILE%\.cursor\mcp.json` You can also open the file from the **Customize** page in the Cursor desktop app by selecting **MCPs > + New**. Add the following configuration, replacing `` with the token you generated: ```json { "mcpServers": { "workato-airo-mcp-server": { "url": "https://YOUR_DATA_CENTER/airo_mcp", "headers": { "Authorization": "Bearer " } } } } ``` Save your changes. Verify the connection. On the **Customize** page, select **MCPs** and confirm that the server appears with its tools and resources. Start a new chat and prompt your Cursor agent to confirm that the server responds. For example, `List my Workato projects.` ::: warning START A NEW CHAT Start a new chat with your agent after saving changes. Cursor agents only have access to the tools and capabilities available when a chat begins. Agents can't detect or use MCP configurations, servers, or tools added after a chat starts. ::: Refer to [Cursor's MCP documentation](https://cursor.com/docs/mcp#using-mcpjson) for more configuration options. :::: :::: tab ChatGPT id="chatgpt-api-token" ChatGPT requires **Developer mode** to connect to remote MCP servers. Developer mode grants ChatGPT read and write access to your AIRO tools. OpenAI classifies developer mode as an advanced feature with elevated risk, so refer to [their developer mode guide](https://developers.openai.com/api/docs/guides/developer-mode) for details before you enable it. Sign in to ChatGPT on the web with a Pro, Plus, Business, Enterprise, or Education account. Developer mode isn't available in the desktop or mobile apps. Go to **Settings > Security and login > Developer mode** and enable the **Developer mode** toggle. Go to [ChatGPT Plugins](https://chatgpt.com/plugins) and click **+** to add a new plugin. This button appears after you turn on developer mode. Enter `workato-airo-mcp-server` in the **Name** field. Optional. Enter a description for your MCP server in the **Description** field. Set the server URL to the following value in the **Connection** field: ```text https://YOUR_DATA_CENTER/airo_mcp ``` Use the **Authentication** drop-down menu to select **Access token / API key**. Use the **Header scheme** drop-down menu to select **Bearer**. Select the **I understand and want to continue** checkbox, then click **Create**. Enter your API token in the **Enter access token or API key** field, then click **Connect**. Verify the connection by trying the app in a new conversation. Open a new chat in ChatGPT. Click the **+** button near the message composer, then select your app from the list of available tools to add it to the conversation context. Prompt the model to use the app. For example, `List my Workato projects.` :::: :::: tab Codex CLI id="codex-cli-api-token" Open your terminal. Add the following line to your shell profile (`~/.zshrc`, `~/.bashrc`, `~/.bash_profile`, or equivalent), replacing `` with your Workato API token: ```bash export WORKATO_API_TOKEN="" ``` Reload your shell profile: ```bash source ~/.zshrc # Replace with the profile file you edited ``` Optional. Confirm that the environment variable is available without displaying the token: ```bash test -n "$WORKATO_API_TOKEN" && echo "WORKATO_API_TOKEN is set" ``` Add the AIRO MCP server and reference the environment variable that contains the bearer token: ```bash codex mcp add workato-airo-mcp-server \ --url https://YOUR_DATA_CENTER/airo_mcp \ --bearer-token-env-var WORKATO_API_TOKEN ``` The `--bearer-token-env-var` option stores the environment variable's name in the Codex configuration, not the token itself. Verify that the server is configured: ```bash codex mcp list ``` The output should include `workato-airo-mcp-server`. Start a new Codex session so the newly configured MCP server is initialized: ```bash codex ``` Inside Codex, enter `/mcp` to inspect the active MCP servers. Confirm the server responds by prompting Codex. For example, `List my Workato projects.` Refer to [Codex's MCP documentation](https://developers.openai.com/codex/extend/mcp) for more configuration options. :::: ::::: ### Connect to multiple workspaces or environments {: #connect-to-multiple-workspaces-or-environments :} You can connect to multiple Workato workspaces or environments by adding a separate server entry to your MCP configuration for each connection. Use a unique server name and API token for every entry. Each API client is assigned to one [environment](/en/workato-api/api-clients.md#create-an-api-client) in workspaces with environments enabled. Its API token works only with that environment. For example, the following Claude Desktop configuration connects to the Development and Production environments in the same workspace: ```json { "mcpServers": { "workato-airo-mcp-server-dev": { "command": "npx", "args": [ "mcp-remote", "https://YOUR_DATA_CENTER/airo_mcp", "--transport", "http-first", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer " } }, "workato-airo-mcp-server-prod": { "command": "npx", "args": [ "mcp-remote", "https://YOUR_DATA_CENTER/airo_mcp", "--transport", "http-first", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer " } } } } ``` The other MCP clients use the same approach: repeat the setup steps with a distinct server name and token for each connection. ## Use cases {: #use-cases :} The following examples demonstrate common workflows with the AIRO MCP server. ### Build and test a recipe {: #build-and-test-a-recipe :} Use AIRO to create a multi-step recipe from a natural language description, then save and test it without leaving your development environment. ``` Create a recipe that syncs new Salesforce opportunities to Jira issues. Add an OpenAI step to summarize the opportunity before creating the Jira issue. Save the recipe and show me the test cases. ``` ### Create a genie with knowledge sources {: #create-a-genie-with-knowledge-sources :} Set up a genie and connect it to relevant knowledge bases so it can answer domain-specific questions. ``` Create a new genie called "Sales Intelligence" and assign the CRM knowledge base to it. ``` ### Build an MCP server {: #build-an-mcp-server :} Create an MCP server from your workspace assets so other AI clients can connect to your tools. ``` Build an MCP server called "Sales Tools" using the lead enrichment and deal scoring skills from the Sales Automation project. ``` ### Investigate job failures {: #investigate-job-failures :} Inspect recent job history to diagnose errors in production recipes. ``` List the last 10 jobs for recipe 1555928 and show me any errors. ``` ### Manage a data table {: #manage-a-data-table :} Create a data table and define its schema without leaving your development environment. ``` Create a data table to store approver thresholds by region. ``` ### Build a custom connector {: #build-a-custom-connector :} Build a connector for an API that isn't available as a platform connector, using your own development environment instead of the Workato SDK editor. ``` Build a connector for the National Weather Service API at https://www.weather.gov/documentation/services-web-api. Add an action that retrieves active weather alerts for a state or territory. ``` Refer to [Build custom connectors with AIRO MCP](/en/airo/build/custom-connectors.md) for the full workflow, including how saving and releasing changes work. ::: tip FEATURE AVAILABILITY Building custom connectors with AIRO MCP is currently available to select customers. Contact your Customer Success Representative to learn more. :::