Connections Security Model

Credential storage

GAIA never writes tokens or API keys to plaintext files. All secrets live exclusively in your OS credential store:

Platform	Store
macOS	Keychain
Linux	gnome-keyring or kwallet
Windows	Credential Locker

Each connector occupies a dedicated keyring slot keyed by gaia.connections:<connector-id>:<secret-name>. MCP server tokens use $keyring:<slot> references in ~/.gaia/mcp_servers.json — the JSON file itself contains no actual secrets. OAuth refresh tokens and MCP server API keys are AES-256 encrypted by the OS keyring at rest and decrypted in memory only when a tool call needs them.

Per-agent grant + activation model

Connecting a service does not give every agent access to it. Access is gated at up to three levels depending on connector type:

Connection — you store a credential once in the keyring (OAuth refresh token or PAT).
Grant — you explicitly allow a specific agent to use that credential for a specific scope. Gates credential access (get_access_token). Applies to every connector type.
Activation — you explicitly enable a specific agent to see an MCP server’s tools in its system prompt. Gates MCP tool visibility. Defaults to OFF — least-privilege opt-in. Applies to mcp_server connectors only.

User → connects mcp-github once                   (credential)
User → grants chat-agent the GitHub PAT scope     (credential access)
User → activates chat-agent for mcp-github        (MCP tool visibility)

OAuth connectors (e.g. Google) reach the provider through native Python @tool functions that call get_credential_sync directly — there is no MCP tool surface for activations to gate. Per-agent control for OAuth is handled entirely by the per-scope grant toggles. Calling activate() / deactivate() for an OAuth connector raises ConfigurationError; the HTTP route returns 400 Bad Request; the CLI exits with code 3. An agent that calls get_credential_sync("google", agent_id=..., required_scopes=["gmail.readonly"]) without a matching grant receives AuthRequiredError(reason=AGENT_NOT_GRANTED) and cannot proceed. No token is ever returned to an ungranted agent. Without an activation, an MCP connector’s tools never enter the agent’s tool list — they don’t bloat the system prompt, and the agent cannot select them even if it has a grant. Grants are stored in ~/.gaia/connectors/grants.json and activations in ~/.gaia/connectors/activations.json — both flat files that are not secret stores. They contain agent IDs and scope/boolean values, never credentials. When a grant is requested during OAuth connect, GAIA records only the intersection of the agent’s requested scopes and the scopes the token endpoint actually grants.

Revocation

You can revoke access at any level:

Action	Effect
Settings → Connectors → <connector> → Disconnect	Removes token from keyring AND clears all grants AND all activations for that connector; all agent calls fail with `NOT_CONNECTED`
`gaia connectors grants revoke <connector> <agent>`	Removes the per-agent grant; that agent’s calls fail with `AGENT_NOT_GRANTED`
`gaia connectors activations deactivate <mcp-server-connector> <agent>`	Removes the per-agent activation; that agent stops seeing the MCP server’s tools but the grant survives so re-activation is one click. Only valid for `mcp_server` connectors
Revoke the PAT/OAuth client at the provider	Invalidates the token at the source; GAIA’s next API call surfaces the provider’s error

Threat model

Threat	Mitigation
Malicious process reads `mcp_servers.json`	File contains only `$keyring:...` references, never raw tokens
Malicious agent requests a credential it wasn’t granted	`get_credential_sync` checks the grants ledger before returning; unapproved calls raise `AuthRequiredError`
Agent code runs a tool in its own thread and loses its identity	The runtime copies the calling context into every tool thread; a credential request inside an agent turn with no identity is refused, never treated as an un-scoped CLI call
Grant ledger written with scopes the connector never advertised	`grant_agent` rejects any scope outside the connector’s catalog entry and any unknown connector id, so the Agent UI, the CLI, and the SDK share one ceiling
Connector re-added after disconnect silently inherits prior tool visibility	`disconnect` wipes both grants AND activations for that `connector_id`; re-adding requires explicit re-grant + re-activate
Token leak via logging	Connector code never logs token values; credentials are redacted before any log statement
Token exfiltration via a rogue custom agent	Custom agents run in the same process as GAIA — they are trusted code you install yourself, analogous to a browser extension

Getting Started

C++ Framework

Python Framework

Connections Security Model

Credential storage

Per-agent grant + activation model

Revocation

Threat model

See also

​Credential storage

​Per-agent grant + activation model

​Revocation

​Threat model

​See also

Credential storage

Per-agent grant + activation model

Revocation

Threat model

See also