How Automata works
Automata separates management from tool execution, then narrows each MCP request by connection kind and connector-token scope.
Two surfaces, one server
The web UI uses a PocketBase session cookie. People create connections, pair accounts, rotate credentials, and manage connector tokens there.
The MCP endpoint uses Authorization: Bearer <token> or /mcp/<token>. It never falls back to a browser session. An invalid token receives a proper 401 response with WWW-Authenticate; a PocketBase outage returns 503 rather than pretending the token was revoked.
Connections and tokens
A connection is exactly one WhatsApp account, Telegram account, or PostgreSQL database. Every connector token resolves to exactly one connection, so tools do not accept a connection argument.
The connection keeps upstream credentials server-side. WhatsApp uses a per-instance Evolution token, Telegram uses a per-session bridge token, and PostgreSQL uses the supplied connection string. Connector tokens are Automata credentials, not upstream API keys.
Permission enforcement
Every tool request passes two independent gates:
- Connection kind: a PostgreSQL token never registers messenger tools.
- Token scope: only explicitly enabled actions, chats, and tables are reachable.
For PostgreSQL, query plans are checked before data is read or modified. For messenger searches, chat allowlists are applied in the data query rather than filtering results afterward.
Service architecture
| Service | Responsibility | Required when |
|---|---|---|
| Web | Management UI and MCP endpoint | Always |
| PocketBase | Users, sessions, connections, scopes, and token hashes | Always |
| Evolution API + Redis + Postgres | WhatsApp pairing, transport, and message storage | WhatsApp is enabled |
| Telegram bridge + Postgres | Personal-account sessions and synced chats | Telegram is enabled |
| User database | The database reached by PostgreSQL tools | A PostgreSQL connection is added |
A deployment serving only PostgreSQL connections needs the web app and PocketBase. Messenger infrastructure is optional and should not be exposed unless it is used.