> ## Documentation Index
> Fetch the complete documentation index at: https://amd-gaia.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors

> Connect GAIA agents to your accounts and external services.

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

<CardGroup cols={2}>
  <Card title="Google" icon="google" href="/docs/connectors/google">
    Gmail, Calendar, Drive, and other Google Workspace APIs via OAuth.
  </Card>

  <Card title="Microsoft" icon="microsoft" href="/docs/connectors/microsoft">
    Outlook mail, calendar, and OneDrive via Microsoft Graph (OAuth).
  </Card>

  <Card title="GitHub" icon="github" href="/docs/connectors/github">
    Repos, PRs, issues, and Actions via the official GitHub MCP server.
  </Card>

  <Card title="Tavily" icon="globe" href="/docs/connectors/tavily">
    Web search and content extraction for agents via the Tavily MCP server.
  </Card>
</CardGroup>

## 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](https://github.com/amd/gaia/issues/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`](https://github.com/amd/gaia/blob/main/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:

```bash theme={null}
# CLI
gaia connectors grants grant google builtin:chat \
  --scopes https://www.googleapis.com/auth/gmail.readonly

# Or in the UI: open the connector tile → "Per-agent grants" section.
```

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](/docs/security/connections) for the full model.

## See also

* [Connectors security model](/docs/security/connections) — what is stored
  where, how revocation works, and the threat model.
* [Building agents that use connectors](/docs/sdk/infrastructure/connectors) — how
  to declare `REQUIRED_CONNECTORS` and call `get_credential` from a
  custom agent.