External MCP Servers
Register a remote Model Context Protocol (MCP) server so Hero AI in Turbine can discover its tools. After discovery, allow selected tools on Hero AI Companion Configuration or on a Hero AI Native Action.
When to Use External MCP Servers
Use External MCP when Hero AI inside Turbine must call tools that are not tenant components.
Situation | Use this topic |
|---|---|
Companion should query a remote knowledge, documentation, or vendor MCP that your organization already hosts | Yes. Register the server here, then allow tools on Hero AI Companion Configuration. |
A Hero AI Native Action should call those remote tools during a playbook run | Yes. Register the server here, then add tools on the action Tools tab. The same playbook can also use connectors or HTTP actions. See Hero AI Native Action. |
Cursor, Claude, or another AI client should run Turbine components | No. Use Turbine MCP Servers. |
How External MCP Helps
Benefit | How it helps |
|---|---|
Reach tools you do not rebuild in Turbine | Register the remote server once. Hero AI discovers the tools the server advertises. You do not have to recreate those tools as tenant components. |
Keep the allowlist small | After discovery, Companion and each Native Action choose only the tools they need. Unused tools stay registered on the server and are not offered to Hero AI. |
Use Hero AI where analysts already work | Companion can pull from a remote knowledge MCP in chat. A playbook Native Action can call a remote tool in the same run as other Turbine actions. |
Call out without publishing the tenant | External MCP lets Turbine reach a remote host. It does not give Cursor or Claude access to this tenant. |
Quick Path
Step | Action |
|---|---|
1 | Open HERO AI > External MCP Servers and add the HTTPS server. See Add an External MCP Server. |
2 | On View Tools, wait for discovery, then select Add Server. |
3 | For Companion, allow tools on Hero AI Companion Configuration. |
4 | For a playbook, add tools on the Hero AI Native Action Tools tab. |
5 | Confirm the outcome. In Companion, open the wrench. On the action, check the saved tool list. See What You See After Setup. |
Choose Your Path
Goal | Where to go |
|---|---|
Decide whether External MCP is the right path | |
Complete the first run | |
Add a remote MCP server | |
Name, URL, and length limits | |
Review the server list | |
Review discovered tools | |
Edit a saved server | |
Remove a server | |
Allow discovered tools in Companion | |
Use discovered tools on a Hero AI playbook action | |
Publish Turbine components to an external client |
Prerequisites
- A role that can administer Hero AI
- External MCP Servers visible under HERO AI in the ADMINISTRATOR rail
- The remote server URL (HTTPS)
If the Host capability is off, External MCP Servers is missing from the rail and the URL shows Page Not Found.
Open External MCP Servers
- In the left navigation, open HERO AI.
- Open External MCP Servers.
When no servers exist, the heading is External MCP Servers. The empty state reads Start by adding an external MCP server. Search and Add New Server appear in the header. A second Add New Server control is in the empty state.
Empty-state body:
Review the Server List
After you add servers, the page lists them. The header has Search, Status, and Add New Server. Status filters All, Connected, or Error. If nothing matches, the page states No MCP servers match your search or status filter. While the list loads, it states Loading MCP servers.... If the list fails, a Retry control appears.
Column | What it shows |
|---|---|
Name | The server name. A subtitle shows when it was added and by whom. |
Description | Optional description from the form. |
Server Status | Connected or Error. |
Last Check | Date and time of the last status check. |
Tools | Discovered tool count. After you allow tools in Companion, the value is N/M (allowed / discovered). Before any are allowed, the value can be a single number. |
Enabled | Toggle that enables or disables the server. |
Select the chevron on a row to list the discovered tools. Expand a tool to review Description, Inputs, and Outputs. A tool that is already allowed in Companion shows In Companion. Some tools also include a Follow-up Pattern note.
The row menu is Edit Server, Remove Server, and Refresh Tools. On the list, Refresh Tools reloads discovery for that server. The add-success toast for a limited connection says Use Update Tools when the connection is healthy. The control on the page is Refresh Tools.
Add an External MCP Server
- Select Add New Server.
- On Configure Server, under MCP Settings, enter MCP Server Name.
- Enter MCP Server URL.
- Enter Description if you want it.
- On Authentication, select an option and enter the fields in the table below.
- Open Parameters or Headers if the remote server requires query parameters or extra headers.
- Select Next.
Next stays unavailable until MCP Server Name and MCP Server URL are valid.
The wizard title is Add New Server. The steps are Configure Server and View Tools. The intro line is Configure an external third-party server to use its tools. The authentication hint is If required by the MCP server, fill out the authentication needed. Footer buttons on Configure Server are Close and Next.
Name and Field Limits
These rules come from the create and edit forms. The same name rules apply to Turbine 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 External 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 | Required. 2000 characters or fewer. Must be an HTTPS URL (for example, https://host/path). HTTP is not accepted on a new server. If an existing server still has HTTP, you can leave that URL unchanged; a new or edited URL must use HTTPS. Do not put a username or password in the URL. Loopback and link-local hosts, such as localhost, are not accepted. |
If the name is reserved or already used, the form shows the product error and Next stays unavailable.
View Tools
Select Next on Configure Server. The wizard opens View Tools and starts discovery immediately. This step is review only. You cannot select or allow tools here.
The heading is Available Tools. A count appears next to the heading after discovery succeeds, including when the count is 0. The count is hidden while discovery is running and when discovery fails. The help tooltip is Other capabilities within the MCP server, such as resources and prompts, are not supported in Turbine.
- Wait until discovery finishes.
- Review each row. Each row shows a wrench icon, the tool name, and the tool description.
- Select Add Server to save the server.
- Select Back to return to Configure Server. In-flight discovery is cancelled.
- If discovery failed, select Retry discovery to run discovery again on this step.
Footer buttons on View Tools are Close, Back, and Add Server. Add Server stays unavailable while discovery is running, while the save is running, or if Configure Server is still invalid. While the save runs, the primary button reads Adding….
You can select Add Server after a discovery failure. The server is saved with a degraded status until tools are discovered successfully.
What you see | Meaning |
|---|---|
Connecting to Server... | Discovery is in progress. A spinner is shown. Add Server is unavailable until this finishes. |
Tool list and a count | Discovery succeeded. Each row shows the wrench icon, the tool name, and the description. You cannot expand a row on this step. |
Discovery succeeded, but the server did not advertise any tools. | The connection worked. The count is 0. There is nothing to allow in Companion yet. |
Error text, a note, and Retry discovery | Discovery failed. The note is You can still add this server. It will be saved with a degraded status until tools are discovered successfully. The error is the API message when one is returned. If none is returned, the fallback is There was an error connecting to the MCP Server. Check your settings and try again. |
If add succeeds, the product shows MCP server added and states that the tools stay unavailable to the Hero AI Companion until you allow them in Companion Configuration.
If add succeeds but discovery did not, the product shows MCP server added with limited connectivity. The message states that the server was saved and that tool discovery did not succeed. On the server list and when you edit the server, use Refresh Tools after the connection is healthy.
If add fails, the product shows Add server failed. The body is the API message when one is returned. If none is returned, the fallback is Unable to add the MCP server. Try again.
After the server is saved, tools stay unavailable to Companion until you allow them on Hero AI Companion Configuration.
When you edit a saved server, tools are on the Tools tab, not on a View Tools wizard step. That tab still uses the Available Tools heading. You can expand a tool to see Description, Inputs, and Outputs. A tool that is already allowed in Companion shows In Companion. Some tools also include a Follow-up Pattern note. Refresh Tools reloads the catalog (Refreshing… while it runs). If the catalog is empty, the text is This server has not advertised any tools yet.
Edit a Saved Server
- Open the server from the list.
- Confirm the title MCP Server Details.
- On Settings, review Server Status, Status Last Checked, MCP Settings, and authentication.
- Select Save.
Server Status shows Connected or Error. Status Last Checked shows the date and time of the last status check. The footer is Close and Save.
On Tools, the heading is Available Tools plus the count. Use Refresh Tools to reload the catalog. The catalog matches View Tools on the create wizard.
Authentication Fields
Option | What you enter |
|---|---|
No Auth | Nothing. The form shows No authorization configured for this MCP server. |
API Key | Header name (hint: defaults to X-API-Key) and API key |
Bearer Token | Bearer token |
Basic Auth | Username and Password |
OAuth is not on this page.
Remove an External MCP Server
- Open the row menu and select Remove Server.
- Read Are you sure you want to delete this server?
- Review Deleting this server will:
- Remove its tools from the Hero AI Companion
- Delete its stored credentials
- If playbooks or components use the server, review those names. Each name is a link. If none use it, the dialog states No playbooks or components currently use this server's tools.
- Click and hold the delete control. The hint is Click and hold button to confirm.
- Select Cancel if you do not want to delete.
The dialog states This action cannot be undone. While it checks usage, it states Checking what uses this server…. If the check fails, it states that Turbine could not check which playbooks and components use the server, and that delete still removes those tools. If the playbook list is incomplete, it states This list may be incomplete — some playbooks could not be checked.
What You See After Setup
Where | What you see |
|---|---|
Server list | The new server appears. If discovery failed, the product saved it with limited connectivity. Use Refresh Tools after the connection is healthy. |
Companion | Tools stay unavailable until you allow them. After you allow them, the wrench in chat lists them under Hero AI Context & Tools. If none are allowed, the dialog states There are no tools configured for Hero AI Companion usage. |
Hero AI Native Action | The action External Tools list stays empty until you add tools on that action. Companion allowlist changes do not appear here. |
Limits
Limit | What it means |
|---|---|
HTTPS only on new or edited URLs | HTTP is not accepted for a new server. An existing HTTP URL can stay until you change it. The URL cannot include user credentials. Loopback and link-local hosts are rejected. |
No OAuth | Authentication is No Auth, API Key, Bearer Token, or Basic Auth. |
Tools only | Resources and prompts on the remote MCP server are not supported in Turbine. |
View Tools is review only | You cannot allow tools on the create wizard. Allow them later on Companion or on a Native Action. |
Security
- Do not publish third-party MCP URLs as product samples.
- Allow only the tools Companion or the action need. Discovery can list more than you should offer to Hero AI.
- Credentials on the server stay in Turbine. They are not the same as a Turbine personal access token used for Turbine MCP.
Troubleshoot External MCP
What you see | What to do |
|---|---|
External MCP Servers is missing, or the URL shows Page Not Found | The Host capability is off. Ask an administrator to enable it. |
The URL is rejected | Use HTTPS with no username in the URL. Do not use localhost or another loopback host. See Name and Field Limits. |
Discovery succeeded, but the server did not advertise any tools. | The connection worked. There is nothing to allow yet. Confirm the remote host advertises tools. |
MCP server added with limited connectivity | The server is saved. Use Refresh Tools or Retry discovery after you fix URL or authentication. |
Add server failed | Read the API message if one is shown. Check name uniqueness, reserved names, and the URL. |
Companion still has no remote tools | Allow them on Hero AI Companion Configuration. Saving the server does not allow them. |