Deploying the MCP service on ECS

Run QuickVoice MCP as the dedicated apps/mcp-server Node HTTP service. The docs app should stay responsible for the public setup UI and API reference; it should not host the production MCP runtime.

See the architecture guide for the recommended service boundary.

Recommended production shape

bash
docs.quickvoice.co        → apps/docs        → documentation and setup UI
mcp.quickvoice.co/mcp    → apps/mcp-server  → Streamable HTTP MCP endpoint
api.quickvoice.co/api/v1 → apps/server      → QuickVoice REST APIs

Container command

bash
pnpm --filter quickvoice-mcp-server build
pnpm --filter quickvoice-mcp-server start

Required environment variables

  • PORT: HTTP port exposed by the MCP service.
  • MCP_ENDPOINT_PATH: MCP endpoint path, default /mcp.
  • QUICKVOICE_API_BASE_URL: internal or public QuickVoice API URL including /api/v1.
  • MCP_CORS_ORIGINS: optional comma-separated browser origins allowed to call MCP.

Do not configure a shared upstream API token in the MCP service. Clients send their own QuickVoice API key with x-api-key, and the MCP service forwards that key to the QuickVoice API so organization permissions remain authoritative.

Same ECS task vs dedicated ECS service

A dedicated ECS service is preferred because MCP traffic has different logs, auth, scaling, and failure modes than the console API or docs website. Running it in the same ECS task is acceptable for early low-traffic deployments, but keep it as a separate process with its own port, health check, and environment variables.

Health checks

Check the MCP HTTP listener and run the MCP smoke script after each deployment. The smoke script must call the MCP endpoint, not the raw QuickVoice REST API.

bash
QUICKVOICE_API_KEY="YOUR_QUICKVOICE_API_KEY" MCP_URL="https://mcp.quickvoice.co/mcp" pnpm --filter quickvoice-mcp-server test:mcp