Turbine MCP Servers

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, 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 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.
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
See example uses (playbook, case management, APIs)	Example Uses
Complete the first run	Quick Path
Create a Turbine MCP server	Create a Turbine MCP Server
Name and length limits	Name and Field Limits
Select components to publish	Add Tools
Review assigned tools before create	Review Tools
Review or enable a server	Manage Turbine MCP Servers
Edit settings or tools	Edit a Turbine MCP Server
Delete a server	Delete a Turbine MCP Server
Connect Cursor	Connect Cursor
Connect Claude Desktop or Claude CLI	Connect Claude
Connect Gemini CLI	Connect Gemini CLI
Connect ChatGPT or Codex	Connect ChatGPT or Codex
Connect GitHub Copilot in Visual Studio Code	Connect GitHub Copilot
Connect another AI client	Connect Another AI Client
Copy or regenerate the URL	Copy or Regenerate the MCP URL
Register a remote MCP server instead	External MCP Servers

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

In the left navigation, open HERO AI.

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:

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

Select Create New Server (or Add New Server on the empty page).

On Configure Server, under MCP Settings, enter MCP Server Name.

Enter Description if you want it.

Copy MCP Server URL, or select Regenerate URL if you need a new path.

Under MCP Setup, copy the JSON Configuration.

Select Next.

On Add Tools, select at least one component, then select Next.

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.

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.

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.

Use Search if the list is long.

Select one or more components. You can select more than one.

Confirm the footer count, selected / total.

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.

Confirm each assigned tool name and description.

Use the row menu if you need to remove a tool.

If a row warns that some clients may reject the advertised name, shorten the server name or the component name.

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.

After you create the server, connect a client, or open Edit Server to change settings and tools.

Edit a Turbine MCP Server

Open the row menu and select Edit Server.

The dialog title is Edit Turbine MCP Server. Tabs are Settings and Tools.

Change the fields you need.

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:

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.

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.

{
  "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:

Copy the JSON snippet.

Open your AI client's MCP configuration settings or file.

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.

Connect Cursor

Cursor accepts the copied snippet under mcpServers with url and Private-Token. "type": "http" can stay in the file.

Create the Turbine MCP server and copy JSON Configuration.

In Cursor, open Settings, then Tools & MCP, and select Add Custom MCP, or open the project mcp.json file.

Paste the snippet under mcpServers.

Replace YOUR_PERSONAL_ACCESS_TOKEN with your personal access token.

Save.

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.

Create the Turbine MCP server and copy JSON Configuration.

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).

Paste the snippet under mcpServers. Do not remove "type": "http".

Replace YOUR_PERSONAL_ACCESS_TOKEN with your personal access token.

Save and restart Claude Desktop if the client requires it.

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.

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

Create the Turbine MCP server and copy JSON Configuration.

Open the Gemini MCP config file (for example mcp_config.json in the Gemini user directory).

Paste the server object under mcpServers.

Replace YOUR_PERSONAL_ACCESS_TOKEN with your personal access token.

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.

Create the Turbine MCP server and copy JSON Configuration.

In ChatGPT, open Plugins, then MCP servers.

Add or update the server. Paste the generated URL in the URL field.

Leave the Bearer token field unused, or empty, unless the client also sends Private-Token.

Add a header named Private-Token and paste your personal access token as the value.

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.

Create the Turbine MCP server and copy JSON Configuration.

Open the workspace .vscode/mcp.json file, or use Add Server.

Place the server object under servers. Keep "type": "http", the URL, and the Private-Token header.

Replace YOUR_PERSONAL_ACCESS_TOKEN with your personal access token.

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.

Copy JSON Configuration.

Keep "type": "http" if the client has a type field.

Map url to the client HTTP MCP field.

Map headers.Private-Token to a custom header. Do not use a Bearer token field unless the client can send Private-Token.

Save and reconnect.

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

Open the row menu and select Delete Server.

Read Delete Turbine MCP Server.

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?

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.
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.