diff --git a/src/pages/docs/falcon-ai/concepts/mcp-connectors.mdx b/src/pages/docs/falcon-ai/concepts/mcp-connectors.mdx
index ec9e07a5c..9455ba571 100644
--- a/src/pages/docs/falcon-ai/concepts/mcp-connectors.mdx
+++ b/src/pages/docs/falcon-ai/concepts/mcp-connectors.mdx
@@ -3,7 +3,7 @@ title: "MCP Connectors"
description: "Connect external MCP servers so their tools sit beside Falcon's own"
---
-## An MCP connector links Falcon to an external tool server
+## About
An **MCP connector** is a workspace's connection to an external server that speaks the [Model Context Protocol](https://modelcontextprotocol.io): a workspace-level object with a name, a server address, and everything Falcon has learned about that server since. Once that server is connected, its tools sit beside Falcon's own [platform tools](/docs/falcon-ai/concepts/understanding-falcon-ai) in the same conversation turn, so a single request can read an evaluation and open an issue in your tracker without you switching tools. [Skills](/docs/falcon-ai/concepts/skills) can reach for those same enabled tools too, alongside platform tools, when a workflow calls for them. Falcon's connector panel frames the idea plainly: "Add MCP connectors to give Falcon access to external services like GitHub, Slack, databases, and more."
@@ -24,7 +24,11 @@ Two moments decide what Falcon can actually do with a connector: discovery, when
## Discovered tools are not the same as enabled tools
-This is the distinction that matters most. Discovery is Falcon asking the connected server what it can do: it queries the server's tool list, and a successful discovery turns every one of those tools on, so Falcon can call everything the server offered. Enabling is what happens afterward, and it only ever narrows that starting set down: you choose which discovered tools stay on and disable the rest. Falcon may only call the subset you've left enabled, and that subset can never grow past what discovery found.
+Discovery asks the server for its tool list and stores the result on the connector. Every successful discovery enables all returned tools, replacing any previous selection. You can then narrow that set to the tools Falcon is allowed to call. The UI requires at least one discovered tool to stay allowed.
+
+
+Successful rediscovery resets your tool restrictions. OAuth reauthentication can also trigger discovery. Review and reapply your allowed-tool selection afterward, before continuing to use the connector.
+
Only use connectors from developers you trust. Future AGI does not control which tools developers make available and cannot verify that they will work as intended or that they won't change.
@@ -32,14 +36,15 @@ Only use connectors from developers you trust. Future AGI does not control which
## The states you'll see
-A connector moves through four stages, but the app tracks them with only three status chips: "Connected", "Pending", or "Inactive". The chip is coarser than the stages, so several of the stages below share the same chip.
+The status chip reflects the connector's stored active and verified state, not a live check of its tools.
-- **Added.** The connector exists with a name and a server address. Falcon hasn't confirmed it can reach or use anything yet, so the chip reads "Pending"
-- **Authenticated.** Falcon has verified it can talk to the server, and the chip changes to "Connected". If verification fails instead, the error shows on the connector's detail pane in **Falcon AI Connectors**, so you can see it without having to reproduce it
-- **Tools discovered.** Falcon keeps the tool list it got back from the server, and the chip still reads "Connected"
-- **Tools enabled.** This is where you narrow the default set down to just the tools you want Falcon to use, and the chip still reads "Connected" here too
+| Chip | Meaning |
+| --- | --- |
+| Connected | The connector is active and its stored state is verified. This does not prove that tool discovery succeeded. |
+| Pending | The connector is active but its stored state is not verified. |
+| Inactive | The connector is marked inactive, regardless of its verification or tool list. |
-A connector can also be turned off outright, at which point the chip reads "Inactive" regardless of what was discovered or enabled underneath it.
+**Test Connection** returns a test result without updating the stored verified state or tool inventory. Successful discovery stores the tool list and marks the connector verified. OAuth authentication can succeed even when discovery fails, so a Connected chip alone does not tell you whether tools were discovered.
To choose exactly which discovered tools stay enabled, see [Choose connector tools](/docs/falcon-ai/guides/choose-connector-tools).
@@ -57,7 +62,7 @@ Check the server's own documentation, or ask whoever runs it, to find out which
Vetting the server, and narrowing its enabled tools down to just what you want Falcon to use, is on you.
-## Keep exploring
+## Next Steps
diff --git a/src/pages/docs/falcon-ai/guides/choose-connector-tools.mdx b/src/pages/docs/falcon-ai/guides/choose-connector-tools.mdx
index a3ef0252a..7edbab41d 100644
--- a/src/pages/docs/falcon-ai/guides/choose-connector-tools.mdx
+++ b/src/pages/docs/falcon-ai/guides/choose-connector-tools.mdx
@@ -3,6 +3,8 @@ title: "Choose connector tools"
description: "Choose which of a connector's discovered tools Falcon AI is allowed to call."
---
+## About
+
A connector that's finished discovery hands Falcon AI every tool it found, already allowed. Narrowing that down to what you actually want Falcon AI calling is a separate step, and it happens on the [connector's](/docs/falcon-ai/concepts/mcp-connectors) own entry in Workspace Settings.
This guide assumes you've already added a connector, authenticated it, and run discovery on it. If you haven't, see [Connect an MCP server](/docs/falcon-ai/guides/connect-mcp-server) first.
@@ -15,16 +17,26 @@ Each tool is a row of its own, carrying the tool's name, the description the ser
## Allow or deny individual tools
-Every tool arrives switched on, so Falcon AI can already call all of them. Switch one off to stop Falcon AI calling it. Nothing else in the list is affected, so you can deny the odd tool you don't want called and leave the rest alone.
+Every successful discovery switches all returned tools on. Switch off the tools you don't want Falcon AI to call, leaving at least one allowed.
+
+
+You cannot switch off the last allowed tool. The UI explains: "At least one tool must stay allowed for this connector."
+
The change saves as you make it, with no confirmation step and nothing to submit, and it holds when you reload the page.
*The count beside the heading is how many tools were discovered, not how many are allowed, so it stays put as you switch tools off*
-
-Falcon AI can only call a tool that's both discovered and switched on. If the connected server stops offering a tool you'd allowed, the change is rejected with an "Unknown tools" error until you re-run [Discover Tools](/docs/falcon-ai/guides/connect-mcp-server).
-
+## If a permission change reports unknown tools
+
+An "Unknown tools" error means the names being saved aren't in the connector's stored discovery list. Saving permissions checks that cached list; it does not fetch a fresh tool list from the remote server. A tool disappearing from the server does not, by itself, cause this error.
+
+Re-run [Discover Tools](/docs/falcon-ai/guides/connect-mcp-server) to refresh the stored list, then review and reapply the tools you want allowed.
+
+
+Every successful discovery enables all returned tools, replacing your previous restrictions. OAuth reauthentication can also trigger discovery. Review and reapply your selection afterward, before continuing to use the connector.
+
## Before a connector has discovered anything
@@ -34,7 +46,7 @@ Until a connector has discovered something, there are no rows to switch, and a s
The chat input's **+** menu has a **Connectors** submenu listing every connector configured for the workspace along with its connected state, and a **Manage connectors** link that opens the connector settings page. If none are configured yet, it reads "No connectors configured" instead.
-## Dive deeper
+## Next Steps
diff --git a/src/pages/docs/falcon-ai/guides/connect-mcp-server.mdx b/src/pages/docs/falcon-ai/guides/connect-mcp-server.mdx
index 9831924d7..ca7fdf602 100644
--- a/src/pages/docs/falcon-ai/guides/connect-mcp-server.mdx
+++ b/src/pages/docs/falcon-ai/guides/connect-mcp-server.mdx
@@ -1,9 +1,11 @@
---
title: "Connect an MCP server"
-description: "Give Falcon AI access to a new MCP server, whatever transport and authentication it expects."
+description: "Connect an external MCP server to Falcon AI, configure its authentication, test the connection, and discover the tools you want to allow."
---
-This guide adds an MCP server to Falcon AI as a connector, so its tools become available for Falcon AI to call in chat once you turn them on (see [MCP Connectors](/docs/falcon-ai/concepts/mcp-connectors) for what a connector is). You name it, point it at the server, choose how Falcon AI talks to it and signs in, then check that the connection actually works before you rely on it in chat.
+## About
+
+This guide adds an MCP server to Falcon AI as a connector. Successful discovery enables all returned tools, so review and narrow the allowed-tool selection before using the connector in chat. See [MCP Connectors](/docs/falcon-ai/concepts/mcp-connectors) for what a connector is. You name it, point it at the server, choose how Falcon AI talks to it and signs in, then test the connection and discover its tools.
Before you start, make sure you have access to Workspace Settings in your workspace, the MCP server's URL, and any credential the server requires, such as an API key or bearer token.
@@ -43,18 +45,30 @@ Fill in whatever fields appear, then click **Create** to save the connector.
## Sign in to an OAuth connector
-If you set **Authentication** to **OAuth 2.0**, saving the connector doesn't sign you in. Authentication happens as a separate step. Once saved, select the connector in the list on the left to open its detail pane, where you'll find **Re-authenticate**. That's the button for both your first sign-in and any later ones: click **Re-authenticate** (it reads **Authenticating...** while it runs), then approve access in the provider's own sign-in window. The window closes itself once you approve, handing control back to Falcon AI, and the result lands as **Authentication updated.** or **Authentication failed.** If it fails, confirm you approved access in the provider's window and try again.
+If you set **Authentication** to **OAuth 2.0**, saving the connector doesn't sign you in. Authentication happens as a separate step. Once saved, select the connector in the list on the left to open its detail pane, where you'll find **Re-authenticate**. That's the button for both your first sign-in and any later ones: click **Re-authenticate**, then approve access in the provider's sign-in window. A successful callback closes the window and refreshes the connector details. Don't wait for an **Authentication updated.** message in Settings: the OAuth popup flow does not display that success message. If sign-in fails, use any error shown by the provider or shown briefly in the callback window (it closes itself after a moment), confirm you approved access, and retry **Re-authenticate**.
+
+OAuth sign-in and reauthentication can also trigger tool discovery, which enables every returned tool and replaces any previous [allowed-tool selection](/docs/falcon-ai/guides/choose-connector-tools).
+
+Authentication can succeed even if tool discovery fails. A **Connected** chip is not proof of successful discovery, and an existing **Discovered Tools** list can remain from an earlier successful attempt. Run **Discover Tools** and check its result when you need to confirm that the list was refreshed.
## Test the connection and discover its tools
-With the connector saved and, for OAuth, signed in, select the new connector in the list on the left to open its detail pane. This is where **Edit**, **Discover Tools**, **Test Connection**, and **Delete** all live, plus **Re-authenticate** on a connector that signs in through OAuth. Click **Test Connection** to confirm Falcon AI can reach it. While it runs, the button reads **Testing...**; it resolves to **Connection test succeeded.** or **Connection test failed.**
+With the connector saved and, for OAuth, signed in, select the new connector in the list on the left to open its detail pane. This is where **Edit**, **Discover Tools**, **Test Connection**, and **Delete** all live, plus **Re-authenticate** on a connector that signs in through OAuth. Click **Test Connection** to confirm Falcon AI can reach it. While it runs, the button reads **Testing...**. A successful test shows **Connection test succeeded.** unless the response supplies another message. A failed test shows available error details, falling back to **Connection test failed.** when none are available.
-Once the connection is good, click **Discover Tools** (it reads **Discovering...** while it runs) to have the server report what it offers. A successful pass shows something like **Discovered 4 tools.** A failed one shows **Tool discovery failed.**
+
+A successful test does not update the connector's stored verified status or tool inventory. It is not proof that the status chip changed or that discovery succeeded.
+
+
+Once the connection is good, click **Discover Tools** (it reads **Discovering...** while it runs) to have the server report what it offers. A successful pass shows something like **Discovered 4 tools.** A failed one shows available error details, falling back to **Tool discovery failed.** when none are available.
+
+
+Every successful discovery enables all returned tools, replacing any previous restrictions. Review and reapply your [allowed-tool selection](/docs/falcon-ai/guides/choose-connector-tools) before continuing to use the connector.
+
*Discovery stores what it found against the connector, so the list is still there when you come back without re-running it*
-Either failure points back at the form rather than at Falcon AI, so click **Edit** and re-check three things: the **Server URL** the server actually listens on, the **Transport** it expects (an older server given Streamable HTTP fails here rather than at save), and, for API Key, that **Header Name** matches what the server looks for and not just the credential in **Header Value**. Save and run **Test Connection** again.
+If testing or discovery fails, use the reported error to guide troubleshooting rather than assuming the form is the cause. Check the **Server URL**, the server's expected **Transport**, and the authentication settings. For API Key, check both **Header Name** and **Header Value**. If those settings are correct, investigate server availability, network access, or a platform error. Retry the failed action after addressing the reported problem.
## Narrow down the tools
@@ -62,17 +76,21 @@ A successful discovery turns every tool it found on, so Falcon AI can already ca
## Edit or delete a connector
-Select the connector in the list on the left to open its detail pane, then click **Edit** to change its name, URL, transport, or authentication, and click **Save** to save your changes. Re-run **Test Connection** and **Discover Tools** afterward to make sure they still match. Click **Delete** to remove a connector you no longer need.
+Select the connector in the list on the left to open its detail pane, then click **Edit** to change its name, URL, transport, or authentication, and click **Save** to save your changes.
+
+When editing an API Key or Bearer Token connector, leave **Header Value** or **Bearer Token** blank to keep the stored secret. A blank field does not mean no secret is stored, and saving it blank does not clear the secret. Enter a new value only when you want to replace it.
+
+Re-run **Test Connection** and **Discover Tools** after changing connection settings, then review your allowed-tool selection. Click **Delete** to remove a connector you no longer need.
Delete removes the connector immediately, there's no confirmation prompt.
-## Dive deeper
+## Next Steps
- Turn on the discovered tools Falcon AI is allowed to call
+ Narrow the discovered tools Falcon AI is allowed to call
Put connector tools to work once they're enabled