Skip to main content

​
What connectors do

Connectors give GAIA agents permission to act on your behalf — read your Gmail, list your GitHub issues, search the web with Tavily, and so on. You configure each connector once, then grant individual agents the specific scopes they need. An agent can never see or use a credential you haven’t granted it. There are two flavors:
  • OAuth providers (e.g. Google) — you authenticate through the provider’s own consent screen. GAIA stores a refresh token in your OS keyring, never on disk.
  • MCP servers (e.g. GitHub, Slack, Postgres) — an external Model Context Protocol server exposes the API as tools. You provide the required API tokens once; GAIA stores them in the keyring and passes them to the MCP server at launch.
All credentials live in your OS credential store (macOS Keychain, gnome-keyring/kwallet on Linux, Credential Locker on Windows). GAIA never writes a token to a plaintext file.

​
How to set up a connector

  1. Launch the Agent UI: gaia chat --ui.
  2. Click Settings (gear icon) → Connections.
  3. Find the connector you want and click its tile to expand it.
  4. Either click Connect (OAuth) or fill in the credentials form (MCP). Step-by-step instructions for the most common ones below.

​
Documented connectors

Google

Gmail, Calendar, Drive, and other Google Workspace APIs via OAuth.

Microsoft

Outlook mail, calendar, and OneDrive via Microsoft Graph (OAuth).

GitHub

Repos, PRs, issues, and Actions via the official GitHub MCP server.

Tavily

Web search and content extraction for agents via the Tavily MCP server.

​
Also available today

Two more MCP servers ship in the catalog and work now. Neither needs an API key, so there’s no dedicated setup page — enable them per agent from Settings → Connections or the CLI:
  • Git — mcp-git: log, diff, status, and blame for a local repository.
  • Memory — mcp-memory: a knowledge-graph scratchpad agents can persist to across a conversation.
Run gaia connectors list to see every connector the catalog currently ships — it is the source of truth for what you can configure today.

​
On the roadmap

More connectors are planned but are not yet in the catalog, so gaia connectors list will not show them and they can’t be configured yet. Track progress and request priorities at issue #937:
  • Email & calendar — dedicated Gmail / Outlook / SendGrid servers
  • Productivity — Notion, Linear, Jira, Slack
  • Developer tools — Postgres, Playwright
  • Web — Brave Search, Context7

​
Try it: the Connectors Demo agent

GAIA ships a built-in Connectors Demo agent that exercises the full grant flow against your real Google account and GitHub PAT — useful for verifying your setup or seeing the per-agent grants flow in action. After connecting Google + GitHub:
  1. In the AgentUI agent dropdown (top of the chat panel), pick Connectors Demo.
  2. Settings → Connections → Google → Per-agent grants → grant the demo agent the gmail.readonly, calendar.readonly, and drive.readonly scopes. Same for GitHub (use).
  3. Ask: “What’s in my inbox?”, “What’s on my calendar today?”, “List my recent Drive files”, or “List my GitHub repos”. The agent calls the matching tool and surfaces the result.
If you skip a grant, the demo will surface an actionable error like AGENT_NOT_GRANTED: open Settings → Connections → google → Per-agent grants and grant <scope>. The agent’s source — hub/agents/python/connectors-demo/gaia_agent_connectors_demo/agent.py — is a working reference for any custom agent that needs to call external services.

​
Per-agent grants

After you connect an account, grant individual agents the scopes they need:
Agents that don’t have a grant for a scope they request will fail with AGENT_NOT_GRANTED and tell you exactly what scope to add. The same flow protects you whether the agent is built-in, custom, or installed from the Agent Hub. For MCP-server connectors (GitHub, Tavily, …) a grant isn’t enough on its own — the agent also needs an activation before those tools appear in its prompt (gaia connectors activations activate <id> <agent>). OAuth connectors like Google don’t use activations. See the connections security model for the full model.

​
See also