Troubleshooting

401 Unauthorized

Confirm the client sends a QuickVoice API key with x-api-key or Authorization: Bearer <key>. Do not use a console browser cookie as the MCP credential.

403 Insufficient permissions

The API key is valid but does not include the route permission required by the selected MCP tool or resource. Create a new key from Settings → API keys with the needed permission matrix, then reconnect the MCP client.

Upstream 404

The MCP server is reachable, but the configured QUICKVOICE_API_BASE_URL does not expose the wrapped API route. Deploy the latest QuickVoice server or point MCP at the correct API host.

Tool succeeds locally but fails remotely

Compare deployment environment, network egress, QUICKVOICE_API_BASE_URL, and API key permissions. Then run the MCP smoke script against the deployed URL.

Model picks a risky tool

Update the client approval policy so external-cost and destructive tools always require human confirmation.