​
Chat Integration

SynapseX Chat integrates with the MCP Router through a server-side Next.js proxy. The browser calls the Chat backend, and the backend forwards the request to api-gateway with the correct credentials.

​
Chat Proxy Route

POST /api/synapsex/mcp-router/{action}
Allowed actions:
ActionGateway targetPurpose
route/v1/mcp/routeSelect domain, MCP server and tool
plan/v1/mcp/planCreate an explainable plan and approval gate
ask/v1/mcp/askPlan or execute when safe/approved
execute/v1/mcp/executeExecute a structured request
The route is implemented at: 
apps/synapsex-chat/src/app/(backend)/api/synapsex/mcp-router/[action]/route.ts

​
Auth Resolution

The proxy resolves credentials in this order:
  1. Incoming Authorization header.
  2. Incoming X-API-Key header.
  3. Server-side SYNAPSEX_API_KEY environment variable.
  4. NextAuth session access token, when available.

​
Chat Service Methods

The client service methods live in: 
apps/synapsex-chat/src/services/synapsexAgents/real-integration.ts
apps/synapsex-chat/src/services/mcp.ts
Use them from UI components or chat actions: 
import { mcpService } from '@/services/mcp';

const plan = await mcpService.planIntelligentMcp({
  input: 'Run QAOA for this graph and compare with VQE',
  tenantId: 'tenant-123',
});

if (plan.requiresApproval) {
  // Show plan.steps and ask the user to approve.
}

const result = await mcpService.askIntelligentMcp({
  input: 'Run QAOA for this graph',
  preferredMcp: 'qcos-mcp',
  approve: true,
  toolName: 'optimize_qaoa',
  toolInput: { graph: [[0, 1], [1, 2]], p: 2, shots: 1024 },
});
  1. Call planIntelligentMcp for domain-specific prompts.
  2. Render the selected MCP, tool, risk, cost model and steps.
  3. If requiresApproval is true, require explicit user confirmation.
  4. Call askIntelligentMcp with approve: true and structured toolInput.
  5. Store outputs as artifacts through workspace-service when results should persist.

​
Environment Variables

VariablePurpose
SYNAPSEX_API_GATEWAY_URLServer-side gateway URL, defaults to NEXT_PUBLIC_API_GATEWAY_URL or http://localhost:8080
NEXT_PUBLIC_API_GATEWAY_URLBrowser-compatible gateway URL for existing direct client integrations
SYNAPSEX_API_KEYOptional server-side API key used by the Chat proxy

​
QCOS Flow

User asks quantum question
  -> Chat calls /api/synapsex/mcp-router/plan
  -> mcp-router-service selects qcos-mcp
  -> Chat shows approval and estimated cost model
  -> Chat calls /api/synapsex/mcp-router/ask with approve=true
  -> api-gateway -> mcp-router-service -> mcp-bridge -> QCOS tool

​
Safety

  • QCOS jobs require approval by default.
  • VM operations require approval by default.
  • Internal platform actions return a guided plan unless a direct executable tool is configured.
  • The proxy avoids exposing API keys to the browser when SYNAPSEX_API_KEY is configured server-side.