Theme
Security and authentication
The gateway token authenticates the MCP connection. A separate VoiceLab API key authenticates the tool's API requests.
Authentication layers
Gateway Bearer token
The hosted endpoint, https://mcp.voicelab.uz/mcp, requires Authorization: Bearer <MCP_AUTH_TOKEN>. Request this token from the MCP operator. A missing or invalid token returns 401.
Client examples read the token from VOICELAB_MCP_AUTH_TOKEN. For a self-hosted Node HTTP server, set MCP_AUTH_TOKEN to require authentication.
VoiceLab API key
The operator configures the hosted server's API key. Calls use that account's permissions and credits. For self-hosted setups, create your own vlk_... key in the VoiceLab app and set VOICELAB_API_KEY.
Grant only the permissions your tools need:
| Tools | Scopes |
|---|---|
| LLM | llm:read, llm:write |
| TTS and voice discovery | tts:read, tts:write, voices:read |
| STT | stt:read, stt:write |
| Voice Isolator | audio_isolation:read, audio_isolation:write |
| Realtime tickets | tts:realtime or stt:realtime |
See API-key permissions for the permission map and key management.
HTTPS and transport security
Use HTTPS for remote MCP and API requests. The self-hosted Node server binds to 127.0.0.1 by default. Put a TLS proxy in front before exposing it remotely.
Signed audio URLs grant temporary access to audio. Keep them out of logs and refresh expired URLs through the resource endpoint. Download without forwarding API credentials. Create a fresh realtime ticket for each connection; never put a long-lived API key in a WebSocket URL.
Rate limits
The Node HTTP server defaults to 120 requests per 60 seconds per client IP. Change RATE_LIMIT_MAX and RATE_LIMIT_WINDOW_MS to configure it. VoiceLab's API limits apply separately.
For retryable 429 responses, honor Retry-After and use bounded exponential backoff with jitter.
CORS and browser access
Browser clients need CORS headers. On the Node HTTP server, ALLOWED_ORIGINS sets a comma-separated list of allowed origins. An empty value disables CORS reflection. It does not enable a wildcard.
Idempotency and replay protection
Creation tools generate an idempotency key if you omit it. Supply and save your own key before the first paid call, then reuse it with identical input on retries. Otherwise, a second tool call generates a new key and can create duplicate work. STT and Voice Isolator uploads require UUIDs.
Reusing a key with different input returns 409. Identical retries follow each endpoint's rules: audio jobs return existing results or status; LLM returns 409 and the original request ID. See retry handling.
Security checklist
- Store both credentials in a secret manager or private environment variables.
- Use separate, permission-limited keys for development and production.
- Set expiry and allowed IPs where appropriate. Revoke compromised keys.
- Require gateway authentication and TLS for remote access.
- Log request IDs, but exclude credentials, signed URLs and realtime tickets.
Reporting security issues
Report vulnerabilities to support@voicelab.uz. Do not post secrets or private recordings in a public issue.