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 an HTTP-only session cookie, stored as a SHA-256 hash in the app's Postgres schema. People create connections, pair accounts, rotate credentials, invite teammates, 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 database 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.

Organizations

Connections belong to an organization, and members have an administrator or member role in the management UI. Roles never widen a connector token: the token alone decides what an AI client can reach. See Organizations and roles.

Permission enforcement

Every tool request passes two independent gates:

1. Connection kind: a PostgreSQL token never registers messenger tools.
2. 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