--- title: Turbine MCP Servers slug: turbine-user-guide/turbine-mcp-servers docTags: createdAt: 2026-10-21T03:48:24.470Z --- :::hint{type="note"} **New Turbine User Guide topic for 26.5.0** — Publish under **Hero AI**. Empty page, create, list, and edit were captured on a 26.5 tenant. Client steps use the product **JSON Configuration** block, not a public connector catalog. ::: Create a Turbine MCP server so an **AI client outside Turbine** can call selected tenant components as tools. ## When to Use Turbine MCP Servers Use Turbine MCP when Cursor, Claude, or another MCP client must run **selected components** in this tenant. | **Situation** | **Use this topic** | | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | You build or review work in Cursor and want the client to call allowed Turbine components | Yes. Create a server, add those components as tools, then connect Cursor. | | You use Claude or another MCP client the same way | Yes. Use the product **JSON Configuration** block for that client. | | Companion or a Hero AI Native Action should call a remote MCP | No. Use [External MCP Servers](External%20MCP%20Servers.md), then allow tools on Companion or on the action **Tools** tab. | ## Example Uses The client always calls a **component**. It does not call a playbook or an application directly. Build the component for the job you want, then publish that component on the Turbine MCP server. | **Goal** | **What you publish** | **What the client does** | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Run a playbook | A component that emits (or otherwise starts) that playbook | Calls the component. The playbook runs in Turbine under the same role-based access control as a normal component run. | | Work a case-management application | Components that create, update, or search records on that application | Calls those components from Cursor, Claude, or another connected client. The rest of the tenant stays unpublished. | | Combine MCP tools with existing APIs | A component whose playbook uses connectors or HTTP actions. Add [External MCP](External%20MCP%20Servers.md) tools on a Hero AI Native Action in the same playbook when the run must also call a remote MCP server. | Calls that one component. Turbine runs the playbook, which can mix connector, HTTP, and External MCP steps. There is no separate bridging setting. | ## How Turbine MCP Helps | **Benefit** | **How it helps** | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Stay in the external client | Cursor or Claude can call the components you publish. You do not have to open Turbine for each of those steps. | | Publish only what you allow | You pick the components that become tools. The client does not receive the rest of the tenant. | | Control access with a tenant URL and token | Clients authenticate with a Swimlane personal access token in the **Private-Token** header. You can copy or regenerate the MCP URL when the endpoint must change. | | Publish out without importing remote tools | Turbine MCP does not add tools to Companion or to Native Action **External Tools**. Those lists use External MCP. | ## Quick Path | **Step** | **Action** | | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | 1 | Open **HERO AI** > **Turbine MCP Servers** and create a server. Add at least one component as a tool. | | 2 | Copy **JSON Configuration**. Create a personal access token from your user profile. | | 3 | Paste the snippet in Cursor or Claude. Replace the token placeholder. See [Connect an AI Client](docId:1GuWPaTvmLDeuHgPxq14r). | | 4 | Connect the server in the client. Ask it to list tools or to run one published component. | ## Choose Your Path | **Goal** | **Where to go** | | -------------------------------------------------- | -------------------------------------------------------------- | | Decide whether Turbine MCP is the right path | [When to Use Turbine MCP Servers](docId:1GuWPaTvmLDeuHgPxq14r) | | See example uses (playbook, case management, APIs) | [Example Uses](docId:1GuWPaTvmLDeuHgPxq14r) | | Complete the first run | [Quick Path](docId:1GuWPaTvmLDeuHgPxq14r) | | Create a Turbine MCP server | [Create a Turbine MCP Server](docId:1GuWPaTvmLDeuHgPxq14r) | | Name and length limits | [Name and Field Limits](docId:1GuWPaTvmLDeuHgPxq14r) | | Select components to publish | [Add Tools](docId:1GuWPaTvmLDeuHgPxq14r) | | Review assigned tools before create | [Review Tools](docId:1GuWPaTvmLDeuHgPxq14r) | | Review or enable a server | [Manage Turbine MCP Servers](docId:1GuWPaTvmLDeuHgPxq14r) | | Edit settings or tools | [Edit a Turbine MCP Server](docId:1GuWPaTvmLDeuHgPxq14r) | | Delete a server | [Delete a Turbine MCP Server](docId:1GuWPaTvmLDeuHgPxq14r) | | Connect Cursor | [Connect Cursor](docId:1GuWPaTvmLDeuHgPxq14r) | | Connect Claude Desktop or Claude CLI | [Connect Claude](docId:1GuWPaTvmLDeuHgPxq14r) | | Connect Gemini CLI | [Connect Gemini CLI](docId:1GuWPaTvmLDeuHgPxq14r) | | Connect ChatGPT or Codex | [Connect ChatGPT or Codex](docId:1GuWPaTvmLDeuHgPxq14r) | | Connect GitHub Copilot in Visual Studio Code | [Connect GitHub Copilot](docId:1GuWPaTvmLDeuHgPxq14r) | | Connect another AI client | [Connect Another AI Client](docId:1GuWPaTvmLDeuHgPxq14r) | | Copy or regenerate the URL | [Copy or Regenerate the MCP URL](docId:1GuWPaTvmLDeuHgPxq14r) | | Register a remote MCP server instead | [External MCP Servers](External%20MCP%20Servers.md) | ## Prerequisites - A role that can administer Hero AI - **Turbine MCP Servers** visible under **HERO AI** in the **ADMINISTRATOR** rail - Components you will publish as tools - A Swimlane personal access token for the client **Private-Token** header If the Server capability is off, **Turbine MCP Servers** is missing from the rail. ## Open Turbine MCP Servers 1. In the left navigation, open **HERO AI**. 2. Open **Turbine MCP Servers**. When no servers exist, the heading is **Turbine MCP Servers**. The empty state reads **Start by creating your first Turbine MCP server**. The header action is **Create New Server**. The empty-state control is **Add New Server**. Both open the same wizard. Empty-state body: :::BlockQuote A Turbine MCP server publishes components from this tenant as tools that external AI clients can call. Create a server to choose which components to expose and how those clients authenticate. ::: ## Manage Turbine MCP Servers After at least one server exists, the page lists servers. The header still has **Search** and **Create New Server**. **Status** filters **All**, **Enabled**, or **Disabled**. Columns are **Name**, **Description**, **Enabled**, and **Tools**. Expand a row to see the assigned tool names. The name cell also shows **Added ago by **. Use the **Enabled** toggle to turn the server on or off without opening edit. The row menu has **Edit Server** and **Delete Server**. If every assigned component was deleted, the product states **This server only references deleted components, so enablement cannot be changed with the current API. Delete the server to take it offline, or re-add tools and try again.** ## Create a Turbine MCP Server 1. Select **Create New Server** (or **Add New Server** on the empty page). 2. On **Configure Server**, under **MCP Settings**, enter **MCP Server Name**. 3. Enter **Description** if you want it. 4. Copy **MCP Server URL**, or select **Regenerate URL** if you need a new path. 5. Under **MCP Setup**, copy the **JSON Configuration**. 6. Select **Next**. 7. On **Add Tools**, select at least one component, then select **Next**. 8. On **Review Tools**, confirm the assigned tools, then select **Create Server**. **Next** stays unavailable until **MCP Server Name** is valid and the URL has been generated. After you enter a name, the **JSON Configuration** key matches that name. The wizard steps are **Configure Server**, **Add Tools**, and **Review Tools**. Footer buttons on **Configure Server** are **Cancel** and **Next**. On **Add Tools**, the footer is **Cancel**, **Back**, and **Next**. On **Review Tools**, the footer is **Cancel**, **Back**, and **Create Server**. **MCP Server URL** is generated. You do not type it. The path looks like: `https://{hostname}/account/{accountId}/tenant/{tenantId}/server/external/{serverId}` ## Name and Field Limits These rules come from the create and edit forms. The same name rules apply to [External MCP Servers](docId\:wtnSkvjA7nAmCbc1mpLZg). | **Field** | **What you must enter** | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **MCP Server Name** | Required. 20 characters or fewer. Letters, numbers, underscores, hyphens, and periods only. No spaces. Consecutive underscores are allowed. Must be unique among Turbine MCP servers in the tenant (case does not matter). Leading and trailing spaces are removed. | | Reserved names | You cannot use **default**, **aisoc**, **marketplace**, **native-actions**, **documentation**, **orchestration**, **swimlane**, **tenant**, **validation**, **flow-fs**, **plan-validation**, or **utils** (any capitalization). | | **Description** | Optional. 2000 characters or fewer. | | **MCP Server URL** | Generated. You cannot type or paste a URL. Regenerating the path invalidates any URL you already shared. | The JSON preview uses the key swimlane only while the name is empty. You cannot save **swimlane** as the server name. After you enter a valid name, that name becomes the JSON key. :::Iframe{code=""} ::: ## Add Tools The heading is **Available Tools** plus the component count (for example, **Available Tools 12**). The subtitle is **Select from available components to include in this server**. Columns are **Tools**, **Description**, and **Interface**. **Interface** can be a dash when the component has no interface name. 1. Use **Search** if the list is long. 2. Select one or more components. You can select more than one. 3. Confirm the footer count, ** selected / total**. 4. Select **Next**. Footer buttons on **Add Tools** are **Cancel**, **Back**, and **Next**. **Next** stays unavailable until at least one tool is selected. The footer count shows ** selected / total**. After you select tools, the footer count updates (for example, **2 selected / 85 total**) and **Next** is available. | **What you see** | **Meaning** | | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Loading components…** | The tenant component list is loading. | | Load error plus **Retry** | The catalog did not load. Select **Retry**. | | **No components are available in this tenant. Create components in Solution Builder to expose them as tools.** | There is nothing to publish yet. | | **No components match your search. Adjust filters or create components in Solution Builder.** | The search returned no rows. | | Naming banner and highlighted rows | **One or more selected tools have MCP names that external clients cannot use. Fix the highlighted rows or rename those components in Solution Builder.** The create tooltip is **Fix MCP tool name issues before creating**. | There is no limit on how many components you can add to one server. You must select at least one. Prefer only the tools the client needs. ## Review Tools **Review Tools** lists the components you selected. Columns are **Tools**, **Description**, and **Interface**. Each **Tools** cell shows the component display name and the advertised client name under it. Empty copy is **No tools are assigned. Go back to Add Tools to select components.** 1. Confirm each assigned tool name and description. 2. Use the row menu if you need to remove a tool. 3. If a row warns that some clients may reject the advertised name, shorten the server name or the component name. 4. Select **Create Server**. Footer buttons are **Cancel**, **Back**, and **Create Server**. While the save runs, the primary button reads **Creating…**. **Back** returns to **Add Tools**. ### Advertised Tool Names Clients see a name derived from the Solution Builder component display name: lowercase, spaces become underscores, other characters are removed. That advertised name must be 1–128 characters and unique on the server. Empty names and duplicates block **Create Server**. Rename the component in Solution Builder to fix them. Some clients call the tool as mcp\_\_\_\_. If that full name exceeds 128 characters, the row warns that some clients may reject the tool. Shorten the server name or the component name. :::Iframe{code=""} ::: After you create the server, connect a client, or open **Edit Server** to change settings and tools. ## Edit a Turbine MCP Server 1. Open the row menu and select **Edit Server**. 2. The dialog title is **Edit Turbine MCP Server**. Tabs are **Settings** and **Tools**. 3. Change the fields you need. 4. Select **Save**, or select **Close**. ### Settings The heading is **MCP Settings**. The subtitle is **Edit a Swimlane Turbine MCP server**. You can change **MCP Server Name** and **Description**. **MCP Server URL** stays generated. Use **Copy URL**. There is no **Regenerate URL** on edit. **MCP Setup** still shows **JSON Configuration**. The JSON key matches the current server name. Footer buttons are **Close** and **Save**. ### Tools Columns are **Tools**, **Description**, and **Interface**. Each row shows the component display name and the advertised client name under it (`mcp__{server-name}__{tool-name}`). **Interface** can be a dash when the component has no interface name. Select **Edit Tools** to change which components the server publishes. The info control next to **Edit Tools** is titled **MCP Tools**. The help text is: :::BlockQuote Any changes made to tools and other configurations to this server require a client side refresh or reconnection. ::: If no tools are assigned, the page states **No tools are assigned. Use Edit Tools to select components.** If **Search** matches nothing, it states **No assigned tools match your search.** Footer buttons are **Close** and **Save**. ## Connect an AI Client Copy the **JSON Configuration** from **MCP Setup**. Every client uses the same generated **MCP Server URL** and a Swimlane personal access token in the **Private-Token** header. The copied snippet includes `"type": "http"` so HTTP clients such as Claude Desktop and Claude CLI can accept it. Cursor, ChatGPT, and Gemini CLI also use this snippet. Swimlane is not listed in public MCP catalogs. Do not put the token in the URL. Create a token from your user profile. See [Customize Your User Profile](https://docs.swimlane.com/customize-your-user-profile). If **MCP Server Name** is empty, the JSON preview key is `swimlane`. After you enter a valid name, the key matches that name. You cannot save the reserved name **swimlane**. ```json { "mcpServers": { "swimlane": { "type": "http", "url": "https://{hostname}/account/{accountId}/tenant/{tenantId}/server/external/{serverId}", "headers": { "Private-Token": "YOUR_PERSONAL_ACCESS_TOKEN" } } } } ``` **MCP Setup** on the wizard: 1. Copy the JSON snippet. 2. Open your AI client's MCP configuration settings or file. 3. Paste the snippet and replace `YOUR_PERSONAL_ACCESS_TOKEN` with your personal access token. | **Client** | **Where to paste** | | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | **Cursor** | **Settings** > **Tools & MCP** > **Add Custom MCP**, or the project `mcp.json` file. Paste under `mcpServers`. | | **Claude Desktop** | On macOS, `~/Library/Application Support/Claude/claude_desktop_config.json`. Paste the snippet. Do not use **Browse**. | | **Claude CLI / Claude Code** | Claude MCP settings (for example `~/.claude/settings.json`), then confirm with `/mcp`. | | **Gemini CLI** | Gemini MCP config file (for example `mcp_config.json` under the Gemini user directory). Paste under `mcpServers`. | | **ChatGPT or Codex** | **Plugins** > MCP servers. Enter the URL, then add a **Private-Token** header. Do not rely on the Bearer token field alone. | | **GitHub Copilot** (Visual Studio Code) | Workspace `.vscode/mcp.json`. Map the copied entry under `servers` (not `mcpServers`). Keep `"type": "http"`. | Menu names and file paths can change in those products. Always keep the generated URL, "type": "http" when the client has a type field, and the **Private-Token** header. :::Iframe{code=""} ::: ## Connect Cursor Cursor accepts the copied snippet under `mcpServers` with `url` and **Private-Token**. `"type": "http"` can stay in the file. 1. Create the Turbine MCP server and copy **JSON Configuration**. 2. In Cursor, open **Settings**, then **Tools & MCP**, and select **Add Custom MCP**, or open the project `mcp.json` file. 3. Paste the snippet under `mcpServers`. 4. Replace `YOUR_PERSONAL_ACCESS_TOKEN` with your personal access token. 5. Save. 6. On **Tools & MCP**, connect the Swimlane entry. Ask the client to list the tools on the server, or to run one component you published. ## Connect Claude Claude Desktop and Claude CLI do not list Swimlane under **Browse**. They require an HTTP MCP server entry. The Turbine **JSON Configuration** already includes `"type": "http"` for those clients. 1. Create the Turbine MCP server and copy **JSON Configuration**. 2. Open Claude Desktop `claude_desktop_config.json` (on macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`), or Claude Code settings (for example `~/.claude/settings.json`). 3. Paste the snippet under `mcpServers`. Do not remove `"type": "http"`. 4. Replace `YOUR_PERSONAL_ACCESS_TOKEN` with your personal access token. 5. Save and restart Claude Desktop if the client requires it. 6. In Claude Code, confirm the server is connected (`/mcp`). Ask the client to list the tools on the server, or to run one component you published. :::hint{type="note"} If Claude rejects the configuration, confirm the snippet still has `"type": "http"`. Do not replace the HTTP entry with an `npx` or `mcp-remote` command unless you are using a workaround outside this release. Cursor and Gemini CLI can connect with the same copied JSON. ::: ## Connect Gemini CLI 1. Create the Turbine MCP server and copy **JSON Configuration**. 2. Open the Gemini MCP config file (for example `mcp_config.json` in the Gemini user directory). 3. Paste the server object under `mcpServers`. 4. Replace `YOUR_PERSONAL_ACCESS_TOKEN` with your personal access token. 5. Save and reconnect. Gemini CLI can use `url` from the copied snippet. If the file already has a `serverUrl` field, keep it equal to the same generated URL. ## Connect ChatGPT or Codex ChatGPT and Codex use a form, not a pasted `mcpServers` file. 1. Create the Turbine MCP server and copy **JSON Configuration**. 2. In ChatGPT, open **Plugins**, then MCP servers. 3. Add or update the server. Paste the generated URL in the URL field. 4. Leave the Bearer token field unused, or empty, unless the client also sends **Private-Token**. 5. Add a header named **Private-Token** and paste your personal access token as the value. 6. Save. Ask ChatGPT or Codex to list tools or to run one published component. ## Connect GitHub Copilot GitHub Copilot in Visual Studio Code stores MCP servers under `servers`, not `mcpServers`. 1. Create the Turbine MCP server and copy **JSON Configuration**. 2. Open the workspace `.vscode/mcp.json` file, or use **Add Server**. 3. Place the server object under `servers`. Keep `"type": "http"`, the URL, and the **Private-Token** header. 4. Replace `YOUR_PERSONAL_ACCESS_TOKEN` with your personal access token. 5. Save and start the server. Ask Copilot to list tools or to run one published component. ## Connect Another AI Client Use this path when the client accepts a streamable HTTP MCP URL and custom headers. 1. Copy **JSON Configuration**. 2. Keep `"type": "http"` if the client has a type field. 3. Map `url` to the client HTTP MCP field. 4. Map `headers.Private-Token` to a custom header. Do not use a Bearer token field unless the client can send **Private-Token**. 5. Save and reconnect. 6. Ask the client to list the tools on the server. If the client supports only OAuth catalog connectors, it cannot call a Turbine MCP server in this release. ## Copy or Regenerate the MCP URL On create, use **Copy URL** or **Regenerate URL**. The copy toast is **Share only with authorized clients. Regenerating the URL requires those clients to update their MCP configuration.** Regenerating invalidates any URL you already shared. On edit, use **Copy URL**. The edit dialog does not regenerate the URL. The copy toast is **Share only with authorized clients.** ## Delete a Turbine MCP Server 1. Open the row menu and select **Delete Server**. 2. Read **Delete Turbine MCP Server**. 3. The message is **There may be external AI clients that are using tools from this server. If you delete it, they will no longer have access to them. Are you sure you want to continue?** 4. Select **Delete**, or select **Cancel**. ## What You See After Setup | **Where** | **What you see** | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Turbine list | The server is listed with a tool count. Expand the row to see assigned tool names. | | Cursor or Claude | After you connect, the client lists advertised names such as `mcp__{server-name}__{tool-name}`. Ask the client to list tools or to run one component you published. | | Companion and Native Action | Those pages do not gain tools from this server. Use External MCP for inbound remote tools. | ## Limits | **Limit** | **What it means** | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | At least one component | You must publish one or more components. There is no maximum count. Prefer only what the client needs. | | Advertised name 1–128 characters | The client name comes from the component display name. Empty or duplicate names block create. Some clients reject a full `mcp__{server}__{tool}` name over 128 characters. | | No catalog OAuth | Clients that support only OAuth catalog connectors cannot call a Turbine MCP server in this release. | | Edit does not regenerate the URL | Use **Regenerate URL** only on create. Regenerating invalidates URLs you already shared. | ## Security - Do not put the personal access token in the URL. Use the **Private-Token** header. - Treat **JSON Configuration** as a secret after you insert the token. - Publish only the components the client needs. - Regenerating the URL requires every client to update its configuration. ## Troubleshoot Turbine MCP | **What you see** | **What to do** | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **Turbine MCP Servers** is missing | The Server capability is off. Ask an administrator to enable it. | | No components to add | Create components in Solution Builder first. | | Highlighted MCP name rows | Fix reserved, empty, or duplicate advertised names. Rename the component or shorten the server name. | | Enablement cannot be changed | The server only references deleted components. Delete the server or add tools again. | | The client does not connect | Confirm the token, the **Private-Token** header, and that you did not paste a Bearer-only field. Restart the client if it requires it. | | Claude has no Swimlane browse entry | Expected. Use a custom MCP configuration. See [Connect Claude](docId:1GuWPaTvmLDeuHgPxq14r). | | Claude Desktop or Claude CLI rejects the JSON | Confirm the copied snippet includes `"type": "http"`. Do not remove that field when you paste. | | GitHub Copilot does not load the server | Confirm the entry is under `servers` in `.vscode/mcp.json`, not under `mcpServers`. | | ChatGPT or Codex cannot call tools | Confirm the URL is the generated MCP URL and that **Private-Token** is a custom header. The Bearer token field is not enough. | ## See Also - [External MCP Servers](docId\:wtnSkvjA7nAmCbc1mpLZg) - [Hero AI Companion Configuration](Hero%20AI%20Companion%20Configuration.md) - [Hero AI Companion](docId\:crQKFVnGpCz_wJ8xtHDs7) - [Hero AI](docId\:swZ8uETVmVoOJwGm_xNK-)