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. Follow GitHub’s instructions for creating a personal access token (classic). Use a recognizable name such as gaia-personal, choose an expiration that fits your setup, and select the scopes below before generating the token.

​
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, include repo and read:user. Add workflow if you want agents to interact with Actions. Copy the generated token for Step 2 — GitHub will not show it again.

​
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_PERSONAL_ACCESS_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.

​
Private repos are missing, or you hit the anonymous rate limit

Connections saved before GAIA passed the token as GITHUB_PERSONAL_ACCESS_TOKEN still hand it to the server under the old name, so the server calls GitHub without it. Click Disconnect on the tile and paste the token again, or run gaia connectors configure mcp-github --set GITHUB_PERSONAL_ACCESS_TOKEN=ghp_….

​
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, follow GitHub’s instructions for authorizing a personal access token for SSO for each organization 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: Follow GitHub’s instructions for deleting a personal access token to revoke the token you created for GAIA. Use this if the laptop with the keyring is lost.

​
See also