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.

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`
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