Problem
docs/toolhive/guides-cli/run-mcp-servers.mdx has grown to ~1,290 lines with 5 top-level sections and ~25 subheadings. The table of contents is unwieldy, and the page conflates several distinct reader journeys: running registry servers, running custom servers (Docker/protocol schemes), running remote servers, configuring any server, and exporting/importing configurations.
Proposed split
Two sections are good extraction candidates:
1. "Configure MCP servers" (highest-value split). The "Customize server settings" section is an 11-subheading grab-bag, and most of its options apply across all run modes (registry, custom, remote), so they don't belong inside the registry-run flow. Pulling them into a shared configuration page removes the biggest ToC contributor and avoids repeating options like --name/--secret/--group across run-mode pages.
Important nuance: not all of these options are universal. They split into two groups, and the new page should make the distinction explicit rather than presenting one undifferentiated list (which the current page does, even though several flags are no-ops for remote servers):
- Cross-cutting (proxy/workload level, all modes): custom name, secrets, group, audit logging, proxy port, session timeout, tool filtering, tool overrides.
- Container-based servers only (no container exists for remote servers): volume mounts, network isolation, image verification, command-line arguments.
2. "Run remote MCP servers." The "Run a remote MCP server" section (~255 lines) is already a self-contained ## covering basic setup, authentication (OAuth/OIDC/bearer token), advanced configuration, and management. It's conceptually distinct from launching a local/registry container and owns the heaviest subsection on the page.
Resulting CLI section structure
- Run MCP servers - registry + custom (Docker/protocol) launch mechanics, trimmed down
- Run remote MCP servers - remote + auth
- Configure MCP servers - shared options, with the container-only caveat
- Share and reuse configurations - export/import (optional smaller extraction)
Migration considerations
- Extracting a section changes its anchors (e.g.
run-mcp-servers#run-a-server-with-secrets → configure-mcp-servers#...). Inbound in-page cross-links, sidebar entries, and external inbound links need updating.
- Add
vercel.json redirects for the moved content.
- Update
sidebars.ts for the new pages.
- Audit inbound links before each move to size it; the "Customize server settings" anchors likely have the most references.
Suggested sequence
Configure page first (biggest ToC win, establishes the shared-options page), then the remote extraction.
Problem
docs/toolhive/guides-cli/run-mcp-servers.mdxhas grown to ~1,290 lines with 5 top-level sections and ~25 subheadings. The table of contents is unwieldy, and the page conflates several distinct reader journeys: running registry servers, running custom servers (Docker/protocol schemes), running remote servers, configuring any server, and exporting/importing configurations.Proposed split
Two sections are good extraction candidates:
1. "Configure MCP servers" (highest-value split). The "Customize server settings" section is an 11-subheading grab-bag, and most of its options apply across all run modes (registry, custom, remote), so they don't belong inside the registry-run flow. Pulling them into a shared configuration page removes the biggest ToC contributor and avoids repeating options like
--name/--secret/--groupacross run-mode pages.Important nuance: not all of these options are universal. They split into two groups, and the new page should make the distinction explicit rather than presenting one undifferentiated list (which the current page does, even though several flags are no-ops for remote servers):
2. "Run remote MCP servers." The "Run a remote MCP server" section (~255 lines) is already a self-contained
##covering basic setup, authentication (OAuth/OIDC/bearer token), advanced configuration, and management. It's conceptually distinct from launching a local/registry container and owns the heaviest subsection on the page.Resulting CLI section structure
Migration considerations
run-mcp-servers#run-a-server-with-secrets→configure-mcp-servers#...). Inbound in-page cross-links, sidebar entries, and external inbound links need updating.vercel.jsonredirects for the moved content.sidebars.tsfor the new pages.Suggested sequence
Configure page first (biggest ToC win, establishes the shared-options page), then the remote extraction.