14 one-click service connections via Composio + MCP bridge, 4 messaging platforms, and the full OAuth connection flow.
All connections use OAuth 2.0 via Composio's MCP bridge. Tokens are encrypted at rest (AES-256) and stored in the central hermes_connections table. Auto-refresh runs 5 minutes before expiry.
Helium operates central bots for each platform. Users link their account via a one-time token. Messages are routed to the user's dedicated VM via Redis pub/sub. All 4 platforms are included in both Light and Heavy plans.
Composio provides the OAuth management layer and tool definitions. The MCP (Model Context Protocol) bridge exposes these as tools to the Hermes Agent running on each VM.
OAuth Initiation
User clicks "Connect" → Helium calls Composio API → returns auth_url → user completes OAuth → Composio stores tokens
Token Storage
Composio manages token lifecycle. Helium mirrors connection status to hermes_connections table for UI display
MCP Tool Registration
On VM startup, Hermes Agent queries Composio MCP endpoint for available tools based on connected services
Tool Execution
Agent calls MCP tool → Composio executes with stored OAuth token → returns result to agent
Token Refresh
Composio auto-refreshes tokens 5 minutes before expiry. Helium updates expires_at in hermes_connections
Disconnection
User disconnects → Helium calls Composio revoke API → deletes hermes_connections row → agent loses tool access
User visits /hermes-max/connections and clicks "Connect" on a service card. Frontend calls POST /api/hermes/connections/:service.
Backend calls Composio API to generate a scoped OAuth authorization URL. Returns auth_url to frontend. Frontend opens URL in new tab or modal.
User completes OAuth flow on the service's website (Google, GitHub, etc.). Service redirects to Composio callback URL with authorization code.
Composio exchanges authorization code for access + refresh tokens. Stores tokens securely. Fires webhook to Helium: connection.created.
Helium webhook handler creates/updates hermes_connections row. Frontend polls GET /api/hermes/connections and shows "Connected" status. Target: <30s total.
VM agent receives connection event via Redis pub/sub. Queries Composio MCP for new tools. Service tools become available in the agent's next conversation turn.