Skip to main content
Connector ID: mcp-github · Type: mcp_server · Catalog entry: src/gaia/connectors/catalog/mcp_servers.py

​
What you’ll need

The GitHub connector is an MCP server — GAIA spawns the @modelcontextprotocol/server-github process on demand and routes tool calls through it. It needs a single secret: a GitHub Personal Access Token (PAT) with the scopes you want agents to use. You will create one PAT, paste it into the GAIA Agent UI, and you’re done. The token lives encrypted in your OS keyring; the MCP server process reads it via a $keyring reference at launch time.

​
Step 1 — Create a Personal Access Token

GitHub has two PAT types. Use the classic token unless you know otherwise — fine-grained tokens don’t yet support every endpoint the MCP server uses.
  1. Go to github.com/settings/tokens (Settings → Developer settings → Personal access tokens → Tokens (classic)).
  2. Generate new token → Generate new token (classic).
  3. Note: gaia-personal (or whatever helps you find it later).
  4. Expiration: pick something — 90 days is a sensible default. GitHub will email you before it expires.

​
Pick scopes

The scopes you grant the token are the maximum GAIA can do. Per- agent grants further narrow it from there. For a typical setup, tick repo and read:user. Add workflow if you want agents to interact with Actions.
  1. Scroll to the bottom and click Generate token.
  2. Copy the token now — GitHub will not show it again. It looks like ghp_… followed by 36 characters.

​
Step 2 — Paste it into GAIA

  1. Launch the Agent UI: gaia chat --ui.
  2. Settings (gear) → Connections → click the GitHub tile.
  3. Paste the PAT into the GitHub Personal Access Token field.
  4. Click Save.
GAIA will:
  1. Store the token in your OS keyring (single slot, distinct from any other connector).
  2. Write ~/.gaia/mcp_servers.json with a $keyring:gaia.connections:mcp-github:GITHUB_TOKEN reference — the actual token never lives in plaintext on disk.
  3. Hot-reload the MCP client manager so the GitHub tools are immediately available to agents.
Click the Test button on the tile to verify GAIA can find the token in the keyring.

​
Step 3 — Grant scopes to specific agents

Each agent must be granted access individually. The GitHub MCP server exposes its tools (e.g. list_issues, create_pull_request); GAIA’s agent grants are at the MCP-tool level.
(In the UI: open the connector tile → Per-agent grants section.)

​
Activate the tools for the agent

For MCP servers, a grant alone isn’t enough — the agent also needs an activation before the GitHub tools appear in its prompt. Activation defaults to OFF (least-privilege), so activate it explicitly:
(In the UI: the tile’s Per-agent toggle flips both at once.) An agent that has a grant but no activation still can’t see or call the tools. See the connections security model for why visibility and credential access are gated separately.

​
Common issues

​
Bad credentials from the MCP server

The token in your keyring is wrong, expired, or revoked. Click Disconnect on the tile and re-paste a fresh token.

​
npx: command not found

The GitHub MCP server is a Node package launched via npx. Install Node 18+ and ensure npx is on your PATH:

​
Resource not accessible by personal access token

Your token doesn’t have a scope the agent is trying to use. Either regenerate the token with broader scopes, or revoke the agent’s grant for that tool.

​
Tokens for organization-owned repos

Classic PATs scoped to repo work for any repo you have push access to, including org-owned repos. If your org enforces SSO, click Configure SSO next to the token in github.com/settings/tokens and authorize each org you want the token to reach.

​
Revoking access

  • From GAIA: Settings → Connections → GitHub → Disconnect. The PAT is removed from the keyring and the MCP server entry is dropped from mcp_servers.json.
  • From GitHub: github.com/settings/tokens → the row for gaia-personal → Delete. Use this if the laptop with the keyring is lost.

​
See also