refactor: unify virtual and non-virtual MCPs under the same route

[tlgimenes]

Summary

This PR unifies virtual MCPs (agents) and regular connections under the same route pattern /mcp/:connectionId. Previously, virtual MCPs were accessed via separate endpoints (/mcp/gateway/:virtualMcpId or /mcp/virtual-mcp/:virtualMcpId), creating an inconsistent API surface.

Changes

Core Changes

• Unified route handling: Both virtual and non-virtual connections now use POST /mcp/:connectionId
• Strategy parameter support: Added strategy parameter to createMCPProxy functions to support tool selection strategies (passthrough, smart_tool_selection, code_execution) via ?mode= query parameter
• Client creation refactor: Updated createClient to accept an options object with superUser and strategy parameters instead of separate boolean flags

Files Modified

• apps/mesh/src/api/routes/proxy.ts: Updated to handle virtual MCPs via the same route, added strategy parsing from query params
• apps/mesh/src/mcp-clients/index.ts: Refactored to accept options object and pass strategy to virtual client creation
• apps/mesh/src/mcp-clients/virtual-mcp/index.ts: Added strategy parameter support
• apps/mesh/src/core/context-factory.ts: Updated createMCPProxy signature to accept strategy
• apps/mesh/src/core/mesh-context.ts: Updated type definitions for strategy parameter
• Documentation updates: Updated API reference docs to reflect unified endpoint pattern
• UI updates: Updated share modal to use new endpoint pattern

Benefits

• Consistent API: Single endpoint pattern for all connection types simplifies client integration
• Better discoverability: Virtual MCPs are now treated as first-class connections
• Flexibility: Strategy parameter allows clients to control tool selection behavior
• Backward compatibility: The old /mcp/gateway and /mcp/virtual-mcp endpoints remain available for backward compatibility

Testing

• Verified virtual MCPs work via /mcp/:connectionId route
• Verified regular connections continue to work via /mcp/:connectionId route
• Verified strategy parameter parsing from query string
• Updated documentation to reflect changes
• Updated UI components to use new endpoint

Migration Notes

Clients using the old virtual MCP endpoints (/mcp/gateway/:virtualMcpId or /mcp/virtual-mcp/:virtualMcpId) should migrate to /mcp/:connectionId where connectionId is the virtual MCP's connection ID. The old endpoints remain available for backward compatibility but may be deprecated in a future release.

Made with Cursor

---

Summary by cubic

Unifies virtual MCPs (Agents) and regular connections under POST /mcp/:connectionId for a consistent API. Adds a tool selection strategy via ?mode= and updates docs/UI to use the new pattern.

• New Features

  • Single route: POST /mcp/:connectionId for all connections, including Agents/virtual MCPs.
  • Tool selection via ?mode= passthrough | smart_tool_selection | code_execution; applied in proxy and call-tool routes.
  • Client API updates: createClient now takes { superUser, strategy }; MeshContext.createMCPProxy accepts strategy; virtual clients honor it.

• Migration

  • Move from /mcp/gateway/:id or /mcp/virtual-mcp/:id to /mcp/:connectionId.
  • Legacy endpoints remain available for now.

^{Written for commit 4a55bd9. Summary will update on new commits.}

[github-actions]

🧪 Benchmark

Should we run the Virtual MCP strategy benchmark for this PR?

React with 👍 to run the benchmark.

Reaction	Action
👍	Run quick benchmark (10 & 128 tools)

Benchmark will run on the next push after you react.

[github-actions]

Release Options

Should a new version be published when this PR is merged?

React with an emoji to vote on the release type:

Reaction	Type	Next Version
👍	Prerelease	2.59.7-alpha.1
🎉	Patch	2.59.7
❤️	Minor	2.60.0
🚀	Major	3.0.0

Current version: 2.59.6

Deployment

• Deploy to production (triggers ArgoCD sync after Docker image is published)

[cubic-dev-ai]

1 issue found across 11 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="apps/docs/client/src/content/en/mcp-mesh/mcp-gateways.mdx">

<violation number="1" location="apps/docs/client/src/content/en/mcp-mesh/mcp-gateways.mdx:23">
P3: Grammar mismatch: "Agents are... Supports..." should be "They support..." or "This endpoint supports...". Also, the term "tool selection strategy" is slightly inconsistent with the section title "Tool exposure strategies".</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}