From a9742412b3de9fd5d88a797487384398f2d7f737 Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Tue, 22 Sep 2026 16:25:06 -0400 Subject: [PATCH 1/6] docs: explain saved MCP diagnostics and permission controls --- .../connections-and-mcp.mdx | 46 ++++++++++++++++--- content/docs/web/settings.mdx | 2 + 2 files changed, 42 insertions(+), 6 deletions(-) diff --git a/content/docs/configure-and-extend/connections-and-mcp.mdx b/content/docs/configure-and-extend/connections-and-mcp.mdx index 4b4ef36..f9d9c07 100644 --- a/content/docs/configure-and-extend/connections-and-mcp.mdx +++ b/content/docs/configure-and-extend/connections-and-mcp.mdx @@ -42,16 +42,50 @@ Local HTTP addresses also remain CLI-only. Web chat cannot reach your computer's Disable or delete a saved server to exclude its tools from subsequent turns. Servers stay private to the account that created them. In team scope, owners, admins, and developers can use their own saved servers. Viewers cannot use connection tools. -Saved `enabled_tools`, `disabled_tools`, and per-tool restrictions in **Extra JSON** also apply to chat. -Tools with an explicit `prompt` approval mode require Control, which can ask before a call. +Saved allowlists, blocklists, and per-tool restrictions also apply to chat. +Tools that need approval require Control, which can ask before a call. Workspace chat, the Slack agent, and native-harness runs withhold these tools because they cannot ask. -The **Integrations** approval menu applies only to Integration entries. Saved servers use their own **Extra JSON** settings. +### Test a saved connection + +Choose **Test connection** on a saved HTTP server. The test reads its saved URL and headers, then lists tools. It does not run tools. +The result shows the tool count, workspace chat availability, tools that require Control approval, and blocked tools. +Expand **Discovered tools** to inspect each tool's effective permission. + +An error explains whether to check the public URL, authorization headers, missing secrets, tool permissions, or server response time. +The test has a six-second deadline. A successful connection with no tools shows a count of zero. +The test also checks disabled servers. Enable a server before its allowed tools become available. +Test local stdio servers through the CLI. + +**Enabled** records a setting, not connection health. Results describe the last manual test during the current page visit. +They reset after saved settings change or the page reloads. Tests do not run automatically or monitor server health. +Chat still discovers tools at the start of each turn, so availability can change after a test. + +### Set tool permissions + +Choose **Edit** on an HTTP server and find **Tool permissions**. +The **Integrations** approval menu applies only to Integration entries. + +| Control | Effect | +| --- | --- | +| Default approval: Run automatically | Allows tools to run in workspace chat and Control without a separate approval. | +| Default approval: Ask in Control | Requires approval in Control. Other hosted chat surfaces withhold these tools. | +| Allow all tools unless blocked | Allows current and future tools, subject to block rules and approval. Turn this off to specify allowed names. | +| Allowed tools | Allows only the listed names. An empty list allows no tools. Enter one exact name per line. | +| Blocked tools | Excludes listed tools, even if an allowlist or approval rule permits them. | +| Per-tool approval | Overrides the default with Run automatically, Ask in Control, or Block. Use default removes the approval override. | + +Test the saved connection before an edit to populate its tool names. **Add tool rule** also accepts an exact name without a test. +A tool disabled in saved settings stays disabled until its switch is on. Other block rules still apply. + +Save changes to apply them on the next turn. The controls preserve unrelated CLI fields and permissions. +The app rejects invalid permissions. Correct invalid permission fields in **Extra JSON**. Invalid policies never become permissive defaults. Without an explicit approval mode, saved tools run automatically, like Integrations in web chat. CLI approval defaults remain unchanged. Other CLI-specific extra options do not configure web chat. -For example, this **Extra JSON** allows `search` and `publish`, blocks `delete`, and asks before `publish` in Control. +The controls use the same fields as **Extra JSON**. Advanced edits remain available. +For example, this JSON allows `search` and `publish`, blocks `delete`, and asks before `publish` in Control. Replace these example names with the tool names your server exposes. ```json @@ -195,7 +229,7 @@ A server that misses that deadline is left out. The deadline does not cancel lat ## Asking before a connection's tools run -This section describes **Integrations**. For saved MCP Servers, use the [Extra JSON permissions described above](#use-a-saved-server-in-web-chat). +This section describes **Integrations**. For saved MCP Servers, use [Tool permissions](#set-tool-permissions). By default, tools from Integrations run without asking. You can change that per connection: open the connection's menu in **Connections** (or the `auto` control on a row in the Connections pane) and choose @@ -281,7 +315,7 @@ Use `/mcp` in the CLI to inspect MCP state during a session. | Symptom | Check | | --- | --- | | Integration tool missing in a hosted run | Confirm the connection is enabled and included in the repo's resolved set. | -| Saved MCP tool missing in web chat | Confirm Enabled is on, the URL is public, and the server supports Streamable HTTP. Check saved tool restrictions and the startup deadline. | +| Saved MCP tool missing in web chat | Choose Test connection. Check the result and each tool's permission. Enable the server to use its allowed tools. | | Saved MCP tool needs approval | Use Control for tools with an explicit `prompt` approval mode. Other hosted chat surfaces withhold them. | | Integration tool works globally but not in one repo | Check for a project exclusion or a project-specific connection cap. | | CLI does not show cloud MCP servers | Confirm CLI token login, then inspect `/mcp` and the remote cache file. | diff --git a/content/docs/web/settings.mdx b/content/docs/web/settings.mdx index 3f8ace5..c249eeb 100644 --- a/content/docs/web/settings.mdx +++ b/content/docs/web/settings.mdx @@ -77,6 +77,8 @@ actually support them. **Models** and **Connections** have their own sidebar destinations. Open **Connections → MCP Servers** to manage saved servers for web chat and the CLI. +Use **Test connection** to check a saved HTTP server and list its tools without running them. +Edit **Tool permissions** to set approval, allowlists, blocklists, and per-tool overrides. Tools that require approval are available in Control only. For model setup, see [Available Models](/web/models). For the connection-specific operating guide, see From 7a182f65ee862ffcedb6ba032ed91b57d9b0e1e9 Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Tue, 22 Sep 2026 16:29:33 -0400 Subject: [PATCH 2/6] docs: clarify permission controls and direct links after review --- content/docs/configure-and-extend/connections-and-mcp.mdx | 4 ++-- content/docs/web/guides/connection-scope-and-overrides.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/configure-and-extend/connections-and-mcp.mdx b/content/docs/configure-and-extend/connections-and-mcp.mdx index f9d9c07..67926ac 100644 --- a/content/docs/configure-and-extend/connections-and-mcp.mdx +++ b/content/docs/configure-and-extend/connections-and-mcp.mdx @@ -76,7 +76,7 @@ The **Integrations** approval menu applies only to Integration entries. | Per-tool approval | Overrides the default with Run automatically, Ask in Control, or Block. Use default removes the approval override. | Test the saved connection before an edit to populate its tool names. **Add tool rule** also accepts an exact name without a test. -A tool disabled in saved settings stays disabled until its switch is on. Other block rules still apply. +For a tool marked **Disabled in saved settings**, turn on the switch beside that label to enable it. Other block rules still apply. Save changes to apply them on the next turn. The controls preserve unrelated CLI fields and permissions. The app rejects invalid permissions. Correct invalid permission fields in **Extra JSON**. Invalid policies never become permissive defaults. @@ -316,7 +316,7 @@ Use `/mcp` in the CLI to inspect MCP state during a session. | --- | --- | | Integration tool missing in a hosted run | Confirm the connection is enabled and included in the repo's resolved set. | | Saved MCP tool missing in web chat | Choose Test connection. Check the result and each tool's permission. Enable the server to use its allowed tools. | -| Saved MCP tool needs approval | Use Control for tools with an explicit `prompt` approval mode. Other hosted chat surfaces withhold them. | +| Saved MCP tool needs approval | Use Control for tools set to Ask in Control (`prompt` in Extra JSON). Other hosted chat surfaces withhold them. | | Integration tool works globally but not in one repo | Check for a project exclusion or a project-specific connection cap. | | CLI does not show cloud MCP servers | Confirm CLI token login, then inspect `/mcp` and the remote cache file. | | OAuth preset stopped working | Reconnect it from Connections and retest before changing prompts. | diff --git a/content/docs/web/guides/connection-scope-and-overrides.mdx b/content/docs/web/guides/connection-scope-and-overrides.mdx index 58a83f6..ff595c3 100644 --- a/content/docs/web/guides/connection-scope-and-overrides.mdx +++ b/content/docs/web/guides/connection-scope-and-overrides.mdx @@ -6,7 +6,7 @@ description: Understand when a connection should be global, project-scoped, or e Connections in Mogplex are not just account-wide settings. This guide covers **Integrations**. The separate **MCP Servers** catalog applies across repos and does not use project exclusions. -See [saved servers in web chat](/configure-and-extend/connections-and-mcp#use-a-saved-server-in-web-chat) for that catalog's permissions and availability. +See [saved server tool permissions](/configure-and-extend/connections-and-mcp#set-tool-permissions) for that catalog's permissions and availability. Integrations resolve at two levels: From 939fbde69b16d7217105b0a6d60841991e5c7ad0 Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Tue, 22 Sep 2026 17:06:24 -0400 Subject: [PATCH 3/6] docs: clarify MCP diagnostics timing and legacy permissions --- content/docs/configure-and-extend/connections-and-mcp.mdx | 7 ++++--- content/docs/web/guides/connection-scope-and-overrides.mdx | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/content/docs/configure-and-extend/connections-and-mcp.mdx b/content/docs/configure-and-extend/connections-and-mcp.mdx index 67926ac..bbb2d4c 100644 --- a/content/docs/configure-and-extend/connections-and-mcp.mdx +++ b/content/docs/configure-and-extend/connections-and-mcp.mdx @@ -53,7 +53,8 @@ The result shows the tool count, workspace chat availability, tools that require Expand **Discovered tools** to inspect each tool's effective permission. An error explains whether to check the public URL, authorization headers, missing secrets, tool permissions, or server response time. -The test has a six-second deadline. A successful connection with no tools shows a count of zero. +Tool discovery has a six-second deadline. Closing the connection can take up to two more seconds and does not hide a successful result. +A successful connection with no tools shows a count of zero. The test also checks disabled servers. Enable a server before its allowed tools become available. Test local stdio servers through the CLI. @@ -79,7 +80,7 @@ Test the saved connection before an edit to populate its tool names. **Add tool For a tool marked **Disabled in saved settings**, turn on the switch beside that label to enable it. Other block rules still apply. Save changes to apply them on the next turn. The controls preserve unrelated CLI fields and permissions. -The app rejects invalid permissions. Correct invalid permission fields in **Extra JSON**. Invalid policies never become permissive defaults. +The permission controls reject invalid values on save. If an earlier CLI or manual edit left invalid permission fields, fix them in **Extra JSON**. Invalid policies never become permissive defaults. Without an explicit approval mode, saved tools run automatically, like Integrations in web chat. CLI approval defaults remain unchanged. Other CLI-specific extra options do not configure web chat. @@ -315,7 +316,7 @@ Use `/mcp` in the CLI to inspect MCP state during a session. | Symptom | Check | | --- | --- | | Integration tool missing in a hosted run | Confirm the connection is enabled and included in the repo's resolved set. | -| Saved MCP tool missing in web chat | Choose Test connection. Check the result and each tool's permission. Enable the server to use its allowed tools. | +| Saved MCP tool missing in web chat | Choose Test connection. Check the result and each tool's permission. Enable the server to use its allowed tools. A server that misses the startup deadline stays out of that turn, even when an earlier test succeeded. | | Saved MCP tool needs approval | Use Control for tools set to Ask in Control (`prompt` in Extra JSON). Other hosted chat surfaces withhold them. | | Integration tool works globally but not in one repo | Check for a project exclusion or a project-specific connection cap. | | CLI does not show cloud MCP servers | Confirm CLI token login, then inspect `/mcp` and the remote cache file. | diff --git a/content/docs/web/guides/connection-scope-and-overrides.mdx b/content/docs/web/guides/connection-scope-and-overrides.mdx index ff595c3..11989a8 100644 --- a/content/docs/web/guides/connection-scope-and-overrides.mdx +++ b/content/docs/web/guides/connection-scope-and-overrides.mdx @@ -6,7 +6,7 @@ description: Understand when a connection should be global, project-scoped, or e Connections in Mogplex are not just account-wide settings. This guide covers **Integrations**. The separate **MCP Servers** catalog applies across repos and does not use project exclusions. -See [saved server tool permissions](/configure-and-extend/connections-and-mcp#set-tool-permissions) for that catalog's permissions and availability. +See [saved server tool permissions](/configure-and-extend/connections-and-mcp#set-tool-permissions) for that catalog's tool permissions. Integrations resolve at two levels: From 868fcca14ea1da32856bef56047d88e2b7781ce3 Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Tue, 22 Sep 2026 17:10:30 -0400 Subject: [PATCH 4/6] docs: distinguish manual test cleanup from chat startup --- content/docs/configure-and-extend/connections-and-mcp.mdx | 6 ++++-- content/docs/web/guides/connection-scope-and-overrides.mdx | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/content/docs/configure-and-extend/connections-and-mcp.mdx b/content/docs/configure-and-extend/connections-and-mcp.mdx index bbb2d4c..5a30e6f 100644 --- a/content/docs/configure-and-extend/connections-and-mcp.mdx +++ b/content/docs/configure-and-extend/connections-and-mcp.mdx @@ -53,7 +53,8 @@ The result shows the tool count, workspace chat availability, tools that require Expand **Discovered tools** to inspect each tool's effective permission. An error explains whether to check the public URL, authorization headers, missing secrets, tool permissions, or server response time. -Tool discovery has a six-second deadline. Closing the connection can take up to two more seconds and does not hide a successful result. +A manual test allows six seconds for discovery. Closing its connection can add up to two seconds and does not hide a successful result. +This cleanup budget applies only to the manual test, not chat startup. A successful connection with no tools shows a count of zero. The test also checks disabled servers. Enable a server before its allowed tools become available. Test local stdio servers through the CLI. @@ -80,7 +81,8 @@ Test the saved connection before an edit to populate its tool names. **Add tool For a tool marked **Disabled in saved settings**, turn on the switch beside that label to enable it. Other block rules still apply. Save changes to apply them on the next turn. The controls preserve unrelated CLI fields and permissions. -The permission controls reject invalid values on save. If an earlier CLI or manual edit left invalid permission fields, fix them in **Extra JSON**. Invalid policies never become permissive defaults. +The form only saves valid permission values. If an earlier CLI or manual edit left an invalid policy, the structured controls cannot edit it. +Open **Extra JSON**, correct the invalid fields, then save. Mogplex withholds tools from invalid policies until you fix them. Without an explicit approval mode, saved tools run automatically, like Integrations in web chat. CLI approval defaults remain unchanged. Other CLI-specific extra options do not configure web chat. diff --git a/content/docs/web/guides/connection-scope-and-overrides.mdx b/content/docs/web/guides/connection-scope-and-overrides.mdx index 11989a8..a3819a9 100644 --- a/content/docs/web/guides/connection-scope-and-overrides.mdx +++ b/content/docs/web/guides/connection-scope-and-overrides.mdx @@ -6,7 +6,7 @@ description: Understand when a connection should be global, project-scoped, or e Connections in Mogplex are not just account-wide settings. This guide covers **Integrations**. The separate **MCP Servers** catalog applies across repos and does not use project exclusions. -See [saved server tool permissions](/configure-and-extend/connections-and-mcp#set-tool-permissions) for that catalog's tool permissions. +See how to [set tool permissions for saved servers](/configure-and-extend/connections-and-mcp#set-tool-permissions). Integrations resolve at two levels: From 68e046424989682a7347eeccda04ab52dce3a5ed Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Tue, 22 Sep 2026 17:15:08 -0400 Subject: [PATCH 5/6] docs: clarify MCP permission labels and CLI prompts --- content/docs/configure-and-extend/connections-and-mcp.mdx | 6 ++++-- content/docs/web/settings.mdx | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/content/docs/configure-and-extend/connections-and-mcp.mdx b/content/docs/configure-and-extend/connections-and-mcp.mdx index 5a30e6f..28625c4 100644 --- a/content/docs/configure-and-extend/connections-and-mcp.mdx +++ b/content/docs/configure-and-extend/connections-and-mcp.mdx @@ -52,8 +52,8 @@ Choose **Test connection** on a saved HTTP server. The test reads its saved URL The result shows the tool count, workspace chat availability, tools that require Control approval, and blocked tools. Expand **Discovered tools** to inspect each tool's effective permission. -An error explains whether to check the public URL, authorization headers, missing secrets, tool permissions, or server response time. -A manual test allows six seconds for discovery. Closing its connection can add up to two seconds and does not hide a successful result. +An error explains whether to check the public URL, authorization headers, missing secrets, invalid permission fields, or server response time. +A manual test allows six seconds for discovery. Closing the connection can add up to two seconds. A slow close does not turn a successful test into a failure. This cleanup budget applies only to the manual test, not chat startup. A successful connection with no tools shows a count of zero. The test also checks disabled servers. Enable a server before its allowed tools become available. @@ -88,6 +88,8 @@ Without an explicit approval mode, saved tools run automatically, like Integrati CLI approval defaults remain unchanged. Other CLI-specific extra options do not configure web chat. The controls use the same fields as **Extra JSON**. Advanced edits remain available. +**Run automatically** maps to `auto`, **Ask in Control** to `prompt`, and per-tool **Block** to `deny`. +**Allowed tools** sets `enabled_tools`. **Blocked tools** sets `disabled_tools`. For example, this JSON allows `search` and `publish`, blocks `delete`, and asks before `publish` in Control. Replace these example names with the tool names your server exposes. diff --git a/content/docs/web/settings.mdx b/content/docs/web/settings.mdx index c249eeb..5e14154 100644 --- a/content/docs/web/settings.mdx +++ b/content/docs/web/settings.mdx @@ -78,7 +78,7 @@ actually support them. **Models** and **Connections** have their own sidebar destinations. Open **Connections → MCP Servers** to manage saved servers for web chat and the CLI. Use **Test connection** to check a saved HTTP server and list its tools without running them. -Edit **Tool permissions** to set approval, allowlists, blocklists, and per-tool overrides. Tools that require approval are available in Control only. +Edit **Tool permissions** to set approval, allowlists, blocklists, and per-tool overrides. In hosted chat, tools that require approval run only in Control. The CLI uses its own prompts. For model setup, see [Available Models](/web/models). For the connection-specific operating guide, see From d4464a540dbe2a8e833a43682be6adf1a56d9377 Mon Sep 17 00:00:00 2001 From: Charles Howard <96023061+charlesrhoward@users.noreply.github.com> Date: Tue, 22 Sep 2026 17:19:26 -0400 Subject: [PATCH 6/6] docs: complete MCP permission mappings and troubleshooting links --- content/docs/configure-and-extend/connections-and-mcp.mdx | 5 +++-- content/docs/web/settings.mdx | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/content/docs/configure-and-extend/connections-and-mcp.mdx b/content/docs/configure-and-extend/connections-and-mcp.mdx index 28625c4..9e8e226 100644 --- a/content/docs/configure-and-extend/connections-and-mcp.mdx +++ b/content/docs/configure-and-extend/connections-and-mcp.mdx @@ -68,7 +68,7 @@ Chat still discovers tools at the start of each turn, so availability can change Choose **Edit** on an HTTP server and find **Tool permissions**. The **Integrations** approval menu applies only to Integration entries. -| Control | Effect | +| Setting | Effect | | --- | --- | | Default approval: Run automatically | Allows tools to run in workspace chat and Control without a separate approval. | | Default approval: Ask in Control | Requires approval in Control. Other hosted chat surfaces withhold these tools. | @@ -90,6 +90,7 @@ CLI approval defaults remain unchanged. Other CLI-specific extra options do not The controls use the same fields as **Extra JSON**. Advanced edits remain available. **Run automatically** maps to `auto`, **Ask in Control** to `prompt`, and per-tool **Block** to `deny`. **Allowed tools** sets `enabled_tools`. **Blocked tools** sets `disabled_tools`. +The switch beside **Disabled in saved settings** sets `tools..enabled` to `true`. For example, this JSON allows `search` and `publish`, blocks `delete`, and asks before `publish` in Control. Replace these example names with the tool names your server exposes. @@ -320,7 +321,7 @@ Use `/mcp` in the CLI to inspect MCP state during a session. | Symptom | Check | | --- | --- | | Integration tool missing in a hosted run | Confirm the connection is enabled and included in the repo's resolved set. | -| Saved MCP tool missing in web chat | Choose Test connection. Check the result and each tool's permission. Enable the server to use its allowed tools. A server that misses the startup deadline stays out of that turn, even when an earlier test succeeded. | +| Saved MCP tool missing in web chat | Confirm the URL is public and the server supports Streamable HTTP. Choose Test connection, then check the result and each tool's permission. Enable the server to use its allowed tools. A server that misses the startup deadline stays out of that turn, even when an earlier test succeeded. | | Saved MCP tool needs approval | Use Control for tools set to Ask in Control (`prompt` in Extra JSON). Other hosted chat surfaces withhold them. | | Integration tool works globally but not in one repo | Check for a project exclusion or a project-specific connection cap. | | CLI does not show cloud MCP servers | Confirm CLI token login, then inspect `/mcp` and the remote cache file. | diff --git a/content/docs/web/settings.mdx b/content/docs/web/settings.mdx index 5e14154..8ba7182 100644 --- a/content/docs/web/settings.mdx +++ b/content/docs/web/settings.mdx @@ -78,7 +78,7 @@ actually support them. **Models** and **Connections** have their own sidebar destinations. Open **Connections → MCP Servers** to manage saved servers for web chat and the CLI. Use **Test connection** to check a saved HTTP server and list its tools without running them. -Edit **Tool permissions** to set approval, allowlists, blocklists, and per-tool overrides. In hosted chat, tools that require approval run only in Control. The CLI uses its own prompts. +Edit [**Tool permissions**](/configure-and-extend/connections-and-mcp#set-tool-permissions) to set approval, allowlists, blocklists, and per-tool overrides. In hosted chat, tools that require approval run only in Control. The CLI uses its own prompts. For model setup, see [Available Models](/web/models). For the connection-specific operating guide, see