Use this boundary when deploying and maintaining QuickVoice MCP.

MCP architecture

QuickVoice uses a dedicated Node MCP service and a separate Next.js docs site. The docs site may contain the MCP landing page, setup guide, client configuration generator, API reference, and troubleshooting content. The actual MCP endpoint should remain inapps/mcp-server.

Recommended app boundary

bash

apps/docs       → Human-facing documentation, MCP setup UI, API reference
apps/mcp-server → Machine-facing Streamable HTTP MCP endpoint
apps/server     → Existing QuickVoice REST API source of truth
apps/ai         → Voice AI worker/runtime
apps/console    → Main QuickVoice product console

Why not put MCP backend inside Next.js?

Keep apps/mcp-server dedicated

The MCP endpoint is machine-facing infrastructure. It should own Streamable HTTP, authentication, validation, tool/resource execution, health checks, and MCP-specific logs.

Keep apps/docs human-facing

The docs app should explain the product, show setup flows, publish API reference pages, and help users copy client configuration. It should not be the operational MCP runtime.

Keep apps/server as the API source of truth

The MCP server should call existing verified QuickVoice APIs instead of reimplementing business logic inside MCP or Next.js route handlers.

Production domain layout

bash

docs.quickvoice.co        → apps/docs
mcp.quickvoice.co/mcp    → apps/mcp-server
api.quickvoice.co/api/v1 → apps/server

When a combined Next.js app is acceptable

A combined Next.js deployment is acceptable only for a very small internal deployment where one service is easier to operate than clean separation. If that route is chosen, keep /mcp implemented as backend-only route handlers, keep public docs pages separate from MCP auth, and preserve the same validation and smoke tests used by apps/mcp-server.

Decision

For QuickVoice production, use apps/mcp-server for MCP and apps/docs for documentation. This keeps the MCP runtime smaller, easier to scale, easier to secure, and easier to debug independently from public docs traffic.