# VoiceMode Connect Architecture
How agents and clients connect through voicemode.dev.
## Overview
```
┌─────────────────┐ ┌─────────────────┐
│ AI Agent │ │ Client │
│ (Claude Code) │ │ (iOS/Web App) │
└────────┬────────┘ └────────┬────────┘
│ MCP │ WebSocket
│ │
└────────────┬───────────────────┘
│
┌───────┴───────┐
│ voicemode.dev │
│ Platform │
└───────────────┘
```
## Components
### Agents
AI assistants that want to have voice conversations. They connect via MCP (Model Context Protocol) and use tools like `status` and `converse`.
- Connect using `mcp-remote` to `https://voicemode.dev/mcp`
- Authenticate via OAuth
- Call MCP tools to interact with the platform
### Clients
Devices that handle the actual voice I/O (microphone/speaker). They connect via WebSocket.
- iOS app - native mobile client
- Web app - browser-based dashboard at voicemode.dev
- Future: macOS menu bar app, browser extension
### Platform
The voicemode.dev backend routes messages between agents and clients.
- User accounts link agents and clients
- WebSocket connections for real-time voice delivery
- OAuth authentication via Auth0
## Connection Flow
1. **Agent connects**: Claude Code adds the MCP server and authenticates
2. **Client connects**: User opens iOS/web app and signs in with same account
3. **Agent sends message**: Uses `converse` tool with text to speak
4. **Platform routes**: Message delivered to connected client(s)
5. **Client speaks**: TTS plays on device, STT captures response
6. **Response returns**: User's voice response sent back to agent
## Authentication
Both agents and clients authenticate against the same voicemode.dev account:
- **Agents**: OAuth flow triggered when MCP tools are first used
- **Clients**: Standard login flow in app/web
The platform matches agents to clients by user account.
## Protocol Notes
- MCP transport: stdio to mcp-remote, which handles HTTP/SSE
- WebSocket: persistent connection for clients
- Voice data: handled by clients, not transmitted through platform (clients use their own TTS/STT)
## See Also
- [MCP Protocol](https://modelcontextprotocol.io/) - Model Context Protocol specification
- [Auth0](https://auth0.com/) - Authentication provider
