better explanation for Linux support in MCP optimizer

[kantord]

Description

This addresses a frustrating point that a real user had on Discord: https://discord.com/channels/1184987096302239844/1340110387453886515/1490713636682076340

There is also an internal Slack discussion on it.

Type of change

• New documentation
• Documentation update
• Bug fix (typo, broken link, etc.)
• Navigation/structure change

Related issues/PRs

Screenshots

Submitter checklist

Content and formatting

• I have reviewed the content for technical accuracy
• I have reviewed the content for spelling, grammar, and style

Navigation

• New pages include a frontmatter section with title and description at a minimum
• Sidebar navigation (sidebars.ts) updated for added, deleted, reordered, or renamed files
• Redirects added to vercel.json for moved, renamed, or deleted pages (i.e., if the URL slug changed)

Reviewer checklist

Content

• I have reviewed the content for technical accuracy
• I have reviewed the content for spelling, grammar, and style

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	Apr 8, 2026 11:14am

[Copilot]

Pull request overview

Updates the ToolHive MCP Optimizer documentation to clarify Linux support, replacing the prior “Linux not supported” messaging with guidance for Linux-specific setups and linking the UI guide to the new Linux instructions.

Changes:

• Update tutorial prerequisites and CLI instructions to reference Linux setup guidance.
• Add a new “Linux setup” section covering VM-based vs native container runtimes.
• Update the UI guide “Limitations” note to include Linux via a link to the tutorial section.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
docs/toolhive/tutorials/mcp-optimizer.mdx	Updates prerequisites/CLI guidance and adds a new Linux setup section with runtime-specific instructions.
docs/toolhive/guides-ui/mcp-optimizer.mdx	Revises limitations to remove “Linux not supported” and links to the tutorial’s Linux setup section.

[aponcedeleonch]

LGTM from the technical point of view

[danbarr]

Editorial review

Nice work addressing the real user pain point here - replacing "Linux: Not currently supported" with actual setup instructions is a big improvement. The Limitations note consolidation in the UI guide reads much better, and all CLI flags and cross-references check out. A few navigation and completeness issues to address:

Primary issues

1. "instead" in Step 3 intro contradicts the Linux setup flow

tutorials/mcp-optimizer.mdx lines 215-216: The new sentence says "see Linux setup instead," implying the reader should skip Step 3 entirely. But the Linux setup section itself (line 336) says "Follow the CLI tab in Step 3 first." These two instructions contradict each other.

Ask: Reword to clarify that Linux native-container users still follow most of Step 3, e.g.:

The ToolHive UI is the recommended way to set up MCP Optimizer, but you can also do it manually with the ToolHive CLI. If you are on Linux with native containers, follow the steps below but see Linux setup for the modified thv run command.

2. Linux command missing TOOLHIVE_PORT consideration

tutorials/mcp-optimizer.mdx lines 349-355: The existing Step 3.2 command includes -e TOOLHIVE_PORT=50100 and a note explaining when to omit it (line 245-246). The Linux-specific command omits TOOLHIVE_PORT without explanation. A Linux CLI user who started the API server manually with --port 50100 would need this variable too.

Ask: Add TOOLHIVE_PORT to the example or add a note after the command, e.g.:

If you started the API server manually with a custom port (Step 3.1), also pass -e TOOLHIVE_PORT=<port>.

Secondary issues

Issue	Recommendation
Lines 325-326, 345-346: Em dashes used (—). Project preference is hyphens with spaces (-).	Replace — with - in both instances.
Line 372: "Scroll up to Step 4" is an unusual web-docs pattern and fragile if the page is reorganized.	Replace with a standard forward link: "Continue with Step 4: Sample prompts to verify the setup."
Lines 330-332 + 336-339: The paragraph before the note and the note itself both state prerequisites, creating a "do 1 and 2 first, also do 3 first" stutter.	Consolidate into a single instruction block. For example, move the Step 1/Step 2 mention into the note so the reader gets one sequential checklist.