smart-mcp-proxy · Dumbris · Aug 17, 2026 · Aug 17, 2026
diff --git a/docs/cli-client-mode.md b/docs/cli-client-mode.md
@@ -1,3 +1,9 @@
+---
+title: "CLI Client Mode"
+sidebar_label: "Client Mode"
+description: "Use the mcpproxy CLI as an MCP client to call tools against a running proxy."
+---
+
 # CLI Client Mode
 
 ## Overview

diff --git a/docs/cli-output-formatting.md b/docs/cli-output-formatting.md
@@ -1,3 +1,9 @@
+---
+title: "CLI Output Formatting"
+sidebar_label: "Output Formatting"
+description: "Machine-readable and human-readable output formats for the MCPProxy CLI."
+---
+
 # CLI Output Formatting
 
 MCPProxy CLI supports multiple output formats for machine-readable and human-readable output.

diff --git a/docs/cli/credential-commands.md b/docs/cli/credential-commands.md
@@ -1,3 +1,9 @@
+---
+title: "Credential Commands"
+sidebar_label: "Credential Commands"
+description: "Server edition: manage per-user brokered credentials for shared upstream servers."
+---
+
 # Credential CLI Commands (Server Edition)
 
 > **Server edition only.** These commands are built into `mcpproxy-server`

diff --git a/docs/code_execution/api-reference.md b/docs/code_execution/api-reference.md
@@ -1,3 +1,9 @@
+---
+title: "Code Execution API Reference"
+sidebar_label: "API Reference"
+description: "Complete reference for the objects, functions, and limits available inside the code execution sandbox."
+---
+
 # Code Execution - API Reference
 
 Complete reference for the `code_execution` MCP tool (JavaScript and TypeScript).

diff --git a/docs/code_execution/cookbook.md b/docs/code_execution/cookbook.md
@@ -1,3 +1,9 @@
+---
+title: "Code Execution Cookbook"
+sidebar_label: "Cookbook"
+description: "Task-oriented recipes for common code execution patterns."
+---
+
 # Code Execution — Orchestration Cookbook
 
 **TypeScript** recipes for orchestrating multiple upstream MCP tools in a
@@ -91,7 +97,7 @@ Batch concurrency is **not** an `options` field: it comes from the
 with `call_tools(requests, {max_parallel})` (1–32).
 
 > **Check the target server's limits before you fan out.** Per‑server
-> [concurrency limits](../configuration.md#concurrency-limits--request-queueing)
+> [concurrency limits](https://github.com/smart-mcp-proxy/mcpproxy-go/blob/main/docs/configuration.md#concurrency-limits--request-queueing)
 > still apply and are never bypassed: a server with `max_concurrent_requests: 1`
 > and `queue_size: 9` serializes a 10‑element batch, while the same server with
 > **no** `queue_size` sheds the overflow as nine per‑slot `queue_full` errors.
@@ -201,7 +207,7 @@ lists into several `call_tools` calls.
 
 ---
 
-## Recipe 2 — Fan‑out + merge (many tools, one object)
+## Recipe 2 — Fan‑out + merge (many tools, one object) {#recipe-2--fan-out--merge-many-tools-one-object}
 
 **Problem:** Gather related facts from several *different* tools/servers and
 return one merged object — a "dashboard" call.
@@ -356,7 +362,7 @@ error each time.
 
 ---
 
-## Recipe 6 — Continue‑on‑error (partial results)
+## Recipe 6 — Continue‑on‑error (partial results) {#recipe-6--continue-on-error-partial-results}
 
 **Problem:** One bad item shouldn't sink the whole batch. Return the successes
 *and* a structured list of failures.
@@ -381,7 +387,7 @@ to restart. The caller gets a complete picture in one result.
 
 ---
 
-## Recipe 7 — Map‑reduce aggregation
+## Recipe 7 — Map‑reduce aggregation {#recipe-7--map-reduce-aggregation}
 
 **Problem:** Fetch many records, then compute a summary the model would
 otherwise have to do token‑by‑token.
@@ -440,7 +446,7 @@ repeat. **Always** bound the loop with `maxPages` *and* set
 
 ---
 
-## Recipe 9 — Rate‑limit via chunking
+## Recipe 9 — Rate‑limit via chunking {#recipe-9--rate-limit-via-chunking}
 
 **Problem:** A downstream tool rejects large bursts. You can't `sleep`, so you
 control pressure by **bounding batch size**, not by waiting.
@@ -514,7 +520,7 @@ issuing one lookup per unique ID. `Set` does the dedupe in‑sandbox.
 ## Benchmarks — token & latency
 
 The numbers behind these recipes come from the reproducible harness in
-[`bench/`](../../bench/README.md), published on every release to the
+[`bench/`](https://github.com/smart-mcp-proxy/mcpproxy-go/tree/main/bench), published on every release to the
 [benchmark dashboard](https://mcpproxy-bench.pages.dev). Reproduce locally with:
 
 ```bash
@@ -561,7 +567,7 @@ savings.
 
 ---
 
-## Upgrade note — TypeScript GA
+## Upgrade note — TypeScript GA {#upgrade-note-typescript-ga}
 
 **Status:** TypeScript code execution (Spec 033) graduates from **preview to
 GA** in v0.46.0 (it shipped in preview in v0.45.0). There is no

diff --git a/docs/code_execution/examples.md b/docs/code_execution/examples.md
@@ -1,3 +1,9 @@
+---
+title: "Code Execution Examples"
+sidebar_label: "Examples"
+description: "Worked end-to-end examples of orchestrating upstream tools with code execution."
+---
+
 # JavaScript Code Execution - Examples
 
 This guide provides working examples demonstrating common use cases for the `code_execution` tool.

diff --git a/docs/code_execution/overview.md b/docs/code_execution/overview.md
@@ -1,3 +1,9 @@
+---
+title: "Code Execution Overview"
+sidebar_label: "Overview"
+description: "How the sandboxed JavaScript/TypeScript runtime orchestrates multiple upstream MCP tools in one request."
+---
+
 # Code Execution - Overview
 
 ## What is Code Execution?
@@ -520,7 +526,7 @@ as long as its slowest element instead of the sum of all of them. Rules:
 - Use it only for **independent** calls — chained steps still belong in a
   sequential pipeline (Pattern 1).
 
-> **Per-server limits still apply.** [Concurrency limits](../configuration.md#concurrency-limits--request-queueing)
+> **Per-server limits still apply.** [Concurrency limits](https://github.com/smart-mcp-proxy/mcpproxy-go/blob/main/docs/configuration.md#concurrency-limits--request-queueing)
 > are enforced inside the call path, never bypassed by batching. A server with
 > `max_concurrent_requests: 1` and `queue_size: 9` serializes a 10-element batch;
 > the same server with **no** `queue_size` sheds the overflow as per-slot

diff --git a/docs/code_execution/troubleshooting.md b/docs/code_execution/troubleshooting.md
@@ -1,3 +1,9 @@
+---
+title: "Code Execution Troubleshooting"
+sidebar_label: "Troubleshooting"
+description: "Diagnose sandbox errors, timeouts, and unexpected results in code execution."
+---
+
 # JavaScript Code Execution - Troubleshooting
 
 Common issues, error messages, and solutions for the `code_execution` tool.

diff --git a/docs/development/macos-tray.md b/docs/development/macos-tray.md
@@ -1,3 +1,9 @@
+---
+title: "macOS Tray Development"
+sidebar_label: "macOS Tray"
+description: "Build, replace, and verify the Swift macOS tray app in native/macos/."
+---
+
 # macOS Tray App development (`native/macos/`)
 
 ## Building the Tray App

diff --git a/docs/development/release-gate.md b/docs/development/release-gate.md
@@ -1,3 +1,9 @@
+---
+title: "Release Qualification Gate"
+sidebar_label: "Release Gate"
+description: "Tag-blocking QA harness that produces one machine-readable pass/fail verdict before artifacts are published."
+---
+
 # Release Qualification Gate (Spec 081)
 
 The release qualification gate is a tag-blocking QA harness: on a release tag it

diff --git a/docs/development/server-edition-multiuser-auth.md b/docs/development/server-edition-multiuser-auth.md
@@ -1,3 +1,9 @@
+---
+title: "Server Multi-User Authentication"
+sidebar_label: "Server Multi-User Auth"
+description: "OAuth-based multi-user authentication for the server edition with Google, GitHub, or Microsoft identity providers."
+---
+
 # Server Multi-User Authentication (Spec 024)
 
 Server edition supports OAuth-based multi-user authentication with Google, GitHub, or Microsoft identity providers. All server code is behind `//go:build server`; the personal edition is unaffected.

diff --git a/docs/development/web-ui-verification.md b/docs/development/web-ui-verification.md
@@ -1,3 +1,9 @@
+---
+title: "Verifying Web UI Changes"
+sidebar_label: "Web UI Verification"
+description: "Playwright sweep and HTML report workflow for verifying changes to the Vue Web UI."
+---
+
 # Verifying Web UI changes (Playwright + rich HTML report)
 
 When you modify the Web UI (any Vue file under `frontend/src/`), verify it end-to-end with a Playwright sweep that captures screenshots and packages them into a self-contained HTML report. This is the same workflow used to verify Spec 046 v2 — see `specs/046-local-first-onboarding/verification/` for a worked example.

diff --git a/docs/features/idp-token-storage.md b/docs/features/idp-token-storage.md
@@ -1,3 +1,9 @@
+---
+title: "IdP Subject Token Storage"
+sidebar_label: "IdP Token Storage"
+description: "Server edition: encrypted persistence of identity-provider tokens for on-behalf-of token exchange."
+---
+
 # IdP Subject Token Storage (Server Edition)
 
 MCPProxy Server edition can persist the IdP (identity-provider) access and refresh

diff --git a/docs/features/observability.md b/docs/features/observability.md
@@ -1,3 +1,9 @@
+---
+title: "Observability"
+sidebar_label: "Observability"
+description: "Export Prometheus metrics and OpenTelemetry traces from MCPProxy to your own monitoring stack."
+---
+
 # Observability for mcpproxy
 
 MCPProxy can export operational metrics and distributed traces so you can run it

diff --git a/docs/features/output-sanitisation.md b/docs/features/output-sanitisation.md
@@ -1,3 +1,9 @@
+---
+title: "Output Sanitisation"
+sidebar_label: "Output Sanitisation"
+description: "Spotlight untrusted tool output, redact detected secrets, and strip control sequences at the response chokepoint."
+---
+
 # Output Sanitisation (Spec 054 Track B)
 
 mcpproxy contains untrusted tool output before it reaches your agent. It builds

diff --git a/docs/features/output-schema-validation.md b/docs/features/output-schema-validation.md
@@ -1,3 +1,9 @@
+---
+title: "Output-Schema Validation"
+sidebar_label: "Output Schema Validation"
+description: "Verify that a tool's structured response conforms to its declared outputSchema before it reaches the agent."
+---
+
 # Output-Schema Validation (Spec 056 / Security Gateway Track A)
 
 When an upstream MCP tool declares an `outputSchema`, MCPProxy can verify that

diff --git a/docs/features/profiles.md b/docs/features/profiles.md
@@ -1,3 +1,9 @@
+---
+title: "Profiles"
+sidebar_label: "Profiles"
+description: "Named subsets of upstream servers addressable as permanent URLs, selectable statefully via the set_profile tool."
+---
+
 # In-Proxy Profiles (Spec 057 · Profiles v2)
 
 > Profiles v1 (Spec 057) is **stateless, URL-based**: a request to `/mcp/p/<slug>` is scoped to that profile for that request. Profiles v2 adds **stateful** selection via the `set_profile` tool, a **shared resolver** with a clear precedence, and a **REST surface** for UI clients.

diff --git a/docs/features/registry-add.md b/docs/features/registry-add.md
@@ -1,3 +1,9 @@
+---
+title: "Adding Servers from Registries"
+sidebar_label: "Registry Add"
+description: "Add an upstream server by registry and server id; the daemon derives the runnable config and quarantines it for review."
+---
+
 # Adding Servers from Registries
 
 MCPProxy can discover MCP servers in known registries and add them as upstream

diff --git a/docs/features/sandbox-isolation.md b/docs/features/sandbox-isolation.md
@@ -1,3 +1,9 @@
+---
+title: "Native Sandbox Isolation"
+sidebar_label: "Sandbox Isolation"
+description: "Isolate stdio MCP servers on Linux without Docker using the Landlock LSM plus resource limits."
+---
+
 # Native Sandbox Isolation (Linux, no Docker)
 
 MCPProxy can isolate a stdio MCP server **without Docker** using the Linux
@@ -65,5 +71,5 @@ stdin/stdout pass straight through with no intervening multiplexer.
 | **macOS / Windows** | Documented **no-op** → effective `none` (Landlock is Linux-only) |
 
 See also: [Docker Isolation](/features/docker-isolation) for the Docker mode, and
-the [non-Docker sandbox spike](/development/sandbox-spike-mcp-34) for the
+the [non-Docker sandbox spike](https://github.com/smart-mcp-proxy/mcpproxy-go/blob/main/docs/development/sandbox-spike-mcp-34.md) for the
 mechanism evaluation.
diff --git a/docs/features/scanner-images.md b/docs/features/scanner-images.md
@@ -1,3 +1,9 @@
+---
+title: "Security Scanner Images"
+sidebar_label: "Scanner Images"
+description: "Where the Docker images behind the security scanners come from and how they are published."
+---
+
 # Security Scanner Images
 
 MCPProxy's security scanners run as Docker containers. This document

diff --git a/docs/features/settings-page.md b/docs/features/settings-page.md
@@ -1,3 +1,9 @@
+---
+title: "Settings Page"
+sidebar_label: "Settings Page"
+description: "The Web UI Configuration page: prioritized form sections over mcpproxy's config, with a raw JSON escape hatch."
+---
+
 # Settings Page (Web UI)
 
 The Web UI **Configuration** page (`/ui/settings`) presents mcpproxy's config as

diff --git a/docs/features/telemetry.md b/docs/features/telemetry.md
@@ -1,3 +1,9 @@
+---
+title: "Anonymous Telemetry"
+sidebar_label: "Telemetry"
+description: "What the anonymous daily heartbeat contains, what it never contains, and how to disable it."
+---
+
 # Anonymous Telemetry
 
 MCPProxy collects anonymous usage statistics to help improve the product. This page explains what is collected, what is not, and how to disable it.

diff --git a/docs/logging.md b/docs/logging.md
@@ -1,3 +1,9 @@
+---
+title: "Logging"
+sidebar_label: "Logging"
+description: "Log file locations per OS, log levels, rotation, and per-server log files."
+---
+
 # Logging System
 
 The mcpproxy-go project includes a comprehensive logging system that follows OS-specific standards for log file storage and provides flexible configuration options.

diff --git a/docs/prerelease-builds.md b/docs/prerelease-builds.md
@@ -1,3 +1,9 @@
+---
+title: "Prerelease Builds"
+sidebar_label: "Prerelease Builds"
+description: "Automated prerelease builds from the next branch with signed and notarized macOS installers."
+---
+
 # Prerelease Builds
 
 MCPProxy supports automated prerelease builds from the `next` branch with signed and notarized macOS installers.

diff --git a/docs/registries.md b/docs/registries.md
@@ -1,3 +1,9 @@
+---
+title: "MCP Server Registries"
+sidebar_label: "Registries"
+description: "The built-in set of MCP server registries used by search_servers and list_registries."
+---
+
 # MCP Server Registries
 
 mcpproxy discovers MCP servers through a built-in set of registries. Discovery is
@@ -101,7 +107,7 @@ at once — loopback, RFC1918/CGNAT private, link-local **and** the
 so enabling it for a localhost dev registry also re-opens the cloud-metadata SSRF
 vector; enable it only for trusted local/dev use, ideally on hosts with no
 cloud-metadata exposure. The change takes effect on daemon (re)start / config
-reload. See [Configuration](configuration.md#registries).
+reload. See [Configuration](configuration/config-file.md).
 
 Equivalent surfaces:
 

diff --git a/docs/socket-communication.md b/docs/socket-communication.md
@@ -1,3 +1,9 @@
+---
+title: "Tray-Core Socket Communication"
+sidebar_label: "Socket Communication"
+description: "Platform-specific local IPC between the tray application and the core server."
+---
+
 # Tray-Core Socket Communication
 
 MCPProxy uses platform-specific local IPC for secure, low-latency communication between the tray application and core server.

diff --git a/docs/web-ui/activity-log.md b/docs/web-ui/activity-log.md
@@ -1,3 +1,9 @@
+---
+title: "Activity Log Page"
+sidebar_label: "Activity Log"
+description: "Real-time monitoring and analysis of MCP server activity in the Web UI."
+---
+
 # Activity Log Web UI
 
 The Activity Log page provides real-time monitoring and analysis of all activity across your MCP servers through a web-based interface.

diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
@@ -48,10 +48,23 @@ const config = {
             'api/**/*.{md,mdx}',
             'web-ui/**/*.{md,mdx}',
             'features/**/*.{md,mdx}',
+            'code_execution/**/*.{md,mdx}',
             'operations/**/*.{md,mdx}',
             'errors/**/*.{md,mdx}',
             'development/**/*.{md,mdx}',
             'contributing.md',
+            // Standalone references with no structured counterpart
+            'cli-client-mode.md',
+            'cli-output-formatting.md',
+            'logging.md',
+            'prerelease-builds.md',
+            'registries.md',
+            'socket-communication.md',
+          ],
+          // Internal working documents that live in the repo but are not published
+          exclude: [
+            'development/sandbox-snap-docker-harness.md',
+            'development/sandbox-spike-mcp-34.md',
           ],
         },
         blog: false,
@@ -77,6 +90,7 @@ const config = {
           'api/*',
           'web-ui/*',
           'features/*',
+          'code_execution/*',
           'operations/*',
         ],
       },