​
Intelligent MCP Routing

SynapseX includes an MCP intelligence layer that selects the right MCP system for a natural-language request. It is inspired by patterns from Google ADK: MCP toolsets, explicit agent/tool routing, context-aware execution, graph-style planning, and approval gates for risky actions.

​
Why It Exists

Users should not need to know whether a task belongs to QCOS, SynapseX Ops, Manager integrations, or a search/grounding tool. Chat and CLI send the request to the MCP Router, which classifies intent and chooses the best MCP server and tool. 
User prompt
  -> mcp-router-service
  -> classify intent
  -> select MCP server
  -> select tool
  -> create explainable plan
  -> require approval when needed
  -> execute through mcp-bridge or return a guided API plan

​
MCP Domains

DomainMCP serverTypical toolsExample prompt
quantumqcos-mcpexecute_circuit, optimize_vqe, optimize_qaoa, list_backends“Run QAOA for this graph”
opssynapsex-ops-mcpget_metrics, tail_logs, restart_service, run_diagnostic“Investigate high CPU on this VM”
platformsynapsex-platformtenants, billing, usage, workspaces, model registry“Show usage for this tenant”
integrationmanager-integrationsGmail, Slack, GitHub, Notion tools“Create a GitHub PR”
searchsearch-groundingweb-search“Research recent MCP best practices”

​
Public API

The router is exposed through the API Gateway: 
GET /v1/mcp/servers
POST /v1/mcp/servers
GET /v1/mcp/router/tools
POST /v1/mcp/route
POST /v1/mcp/plan
GET /v1/mcp/plans
POST /v1/mcp/execute
POST /v1/mcp/ask

​
Route Only

Use route when you want to know what SynapseX would use without creating a persistent plan. 
curl -X POST https://api.synapsex.ai/v1/mcp/route \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"input":"run QAOA for this graph"}'
Example response: 
{
  "domain": "quantum",
  "server": { "name": "qcos-mcp", "domain": "quantum" },
  "tool": "optimize_qaoa",
  "explanation": "Classified the request as quantum, selected qcos-mcp, and prepared optimize_qaoa. Approval is required before execution."
}

​
Plan

Use plan when Chat or CLI should show an explainable execution preview. 
curl -X POST https://api.synapsex.ai/v1/mcp/plan \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"input":"restart nginx if logs show gateway errors","tenantId":"tenant-123"}'
Plans include:
  • classified domain;
  • selected MCP server;
  • selected tool;
  • risk level;
  • whether approval is required;
  • execution steps;
  • human-readable explanation.

​
Ask

ask is the high-level endpoint for Chat and CLI. It creates a plan and either returns it or executes it if safe and approved. 
curl -X POST https://api.synapsex.ai/v1/mcp/ask \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "input":"get CPU metrics for this VM",
    "vmId":"vm-123",
    "approve":true,
    "toolInput":{}
  }'
For QCOS tasks, use structured input when execution requires circuit/job data: 
{
  "input": "run QAOA for this graph",
  "preferredMcp": "qcos-mcp",
  "approve": true,
  "toolName": "optimize_qaoa",
  "toolInput": {
    "graph": [[0, 1], [1, 2], [2, 0]],
    "p": 2,
    "shots": 1024
  }
}

​
CLI UX

synapsex mcp route "run QAOA for this graph"
synapsex mcp plan "restart nginx if logs show gateway errors" --tenant tenant-123
synapsex mcp ask "get CPU metrics" --preferred synapsex-ops-mcp --vm vm-123 --approve
synapsex mcp ask "run QAOA" --preferred qcos-mcp --tool optimize_qaoa --tool-input '{"p":2,"shots":1024}' --approve
Use --json for automation: 
synapsex mcp plan "compare VQE and QAOA" --json

​
Chat UX

The chat app should call /v1/mcp/plan first for risky, expensive, or domain-specific actions. The UI should show:
  • “I detected a quantum task.”
  • “I plan to use qcos-mcp and optimize_qaoa.”
  • “Approval is required because this can start a backend job.”
  • “Estimated cost model: backend-job.”
After approval, Chat calls /v1/mcp/ask with approve: true and the structured tool input. SynapseX Chat includes a server-side proxy at: 
/api/synapsex/mcp-router/{route|plan|ask|execute}
This proxy forwards to the API Gateway and can use SYNAPSEX_API_KEY server-side so credentials are not exposed in the browser.

​
Relationship To Google ADK Patterns

Google ADK patternSynapseX implementation
McpToolset discovers and adapts toolsmcp-router-service stores MCP servers/tools and exposes routable tools
RoutedAgent selects an agent by contextPOST /v1/mcp/route selects MCP/tool by intent and preference
Context, sessions, artifactsworkspace-service stores artifacts and planned execution outputs
Human input / graph workflowsPlans include approval gates before risky execution
A2A for remote specialist agentsQCOS can be exposed as both qcos-mcp and a future A2A quantum specialist

​
Safety Defaults

  • QCOS and VM operations require approval by default.
  • Platform/search routes are low-risk by default.
  • Internal API surfaces return a guided plan instead of blind execution.
  • Execution events are published to event-bus-service when tenantId is provided.