--- title: External MCP Servers slug: turbine-user-guide/external-mcp-servers docTags: createdAt: 2026-10-21T03:48:23.572Z --- 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](Hero%20AI%20Companion%20Configuration.md) or on a [Hero AI Native Action](docId\:C4CKmT7fHXgjBtlXxOOC2). ## 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](Hero%20AI%20Companion%20Configuration.md). | | 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](Hero%20AI%20Native%20Action.md). | | Cursor, Claude, or another AI client should run Turbine components | No. Use [Turbine MCP Servers](Turbine%20MCP%20Servers.md). | ## 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](docId\:wtnSkvjA7nAmCbc1mpLZg). | | 2 | On **View Tools**, wait for discovery, then select **Add Server**. | | 3 | For Companion, allow tools on [Hero AI Companion Configuration](Hero%20AI%20Companion%20Configuration.md). | | 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](docId\:wtnSkvjA7nAmCbc1mpLZg). | ## Choose Your Path | **Goal** | **Where to go** | | ------------------------------------------------- | --------------------------------------------------------------------------- | | Decide whether External MCP is the right path | [When to Use External MCP Servers](docId\:wtnSkvjA7nAmCbc1mpLZg) | | Complete the first run | [Quick Path](docId\:wtnSkvjA7nAmCbc1mpLZg) | | Add a remote MCP server | [Add an External MCP Server](docId\:wtnSkvjA7nAmCbc1mpLZg) | | Name, URL, and length limits | [Name and Field Limits](docId\:wtnSkvjA7nAmCbc1mpLZg) | | Review the server list | [Review the Server List](docId\:wtnSkvjA7nAmCbc1mpLZg) | | Review discovered tools | [View Tools](docId\:wtnSkvjA7nAmCbc1mpLZg) | | Edit a saved server | [Edit a Saved Server](docId\:wtnSkvjA7nAmCbc1mpLZg) | | Remove a server | [Remove an External MCP Server](docId\:wtnSkvjA7nAmCbc1mpLZg) | | Allow discovered tools in Companion | [Hero AI Companion Configuration](Hero%20AI%20Companion%20Configuration.md) | | Use discovered tools on a Hero AI playbook action | [Hero AI Native Action](Hero%20AI%20Native%20Action.md) | | Publish Turbine components to an external client | [Turbine MCP Servers](Turbine%20MCP%20Servers.md) | ## 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 1. In the left navigation, open **HERO AI**. 2. 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: :::BlockQuote Model Context Protocol servers let Turbine reach tools hosted outside the platform. Register a server here to discover the tools it advertises, then choose which of them Hero AI Native Actions and the Hero AI Companion are allowed to run. ::: ## 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 1. Select **Add New Server**. 2. On **Configure Server**, under **MCP Settings**, enter **MCP Server Name**. 3. Enter **MCP Server URL**. 4. Enter **Description** if you want it. 5. On **Authentication**, select an option and enter the fields in the table below. 6. Open **Parameters** or **Headers** if the remote server requires query parameters or extra headers. 7. 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](Turbine%20MCP%20Servers.md). | **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.** 1. Wait until discovery finishes. 2. Review each row. Each row shows a wrench icon, the tool name, and the tool description. 3. Select **Add Server** to save the server. 4. Select **Back** to return to **Configure Server**. In-flight discovery is cancelled. 5. 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](Hero%20AI%20Companion%20Configuration.md). 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 1. Open the server from the list. 2. Confirm the title **MCP Server Details**. 3. On **Settings**, review **Server Status**, **Status Last Checked**, **MCP Settings**, and authentication. 4. 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](docId\:wtnSkvjA7nAmCbc1mpLZg) 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 1. Open the row menu and select **Remove Server**. 2. Read **Are you sure you want to delete this server?** 3. Review **Deleting this server will:** - **Remove its tools from the Hero AI Companion** - **Delete its stored credentials** 4. 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.** 5. Click and hold the delete control. The hint is **Click and hold button to confirm**. 6. 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](docId\:wtnSkvjA7nAmCbc1mpLZg). | | **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](Hero%20AI%20Companion%20Configuration.md). Saving the server does not allow them. | ## See Also - [Hero AI Native Action](docId\:C4CKmT7fHXgjBtlXxOOC2) - [Hero AI Companion Configuration](Hero%20AI%20Companion%20Configuration.md) - [Turbine MCP Servers](Turbine%20MCP%20Servers.md) - [Hero AI Companion](docId\:crQKFVnGpCz_wJ8xtHDs7) - [Hero AI](docId\:swZ8uETVmVoOJwGm_xNK-)