Catalog My learning Blog
MCP Setup Guides: Cursor, Codex, Gemini CLI and Top Servers · Phase 2 · Lesson 6 · 3 min read

GitHub MCP Server Setup: Toolsets and Read-Only

On this page
  1. What it gives your agent
  2. Step 1: create a token
  3. Step 2: add it to your tool
  4. Step 3: give it only the tools you need
  5. Running it locally with Docker
  6. Check it works
  7. Check yourself

What it gives your agent

With the GitHub MCP server connected, you can ask "summarize the open issues labeled bug", "open a PR from this branch with a description" or "why did the last CI run fail?" and the agent does it through GitHub's API. It's the server that shows up first on almost every "best MCP servers" list, and it's maintained by GitHub.

You have two ways to run it:

OptionURL or commandGood for
Hosted (remote)https://api.githubcopilot.com/mcp/Most people. Nothing to install
Local (Docker)ghcr.io/github/github-mcp-serverGitHub Enterprise Server, or when you want it on your own machine

Step 1: create a token

Most clients connect with a personal access token (PAT). VS Code can sign in with OAuth instead, but Cursor and Claude Code use a token. Create a fine-grained token in GitHub under Settings, Developer settings, Personal access tokens, and give it access to only the repositories you'll use.

Grant the smallest permissions that cover your tasks. For reading code and issues, read access is enough. Add write access to issues or pull requests only if you want the agent to create them. Then put the token in an environment variable so it stays out of config files:

Shell
export GITHUB_PAT=github_pat_your_token_here

Step 2: add it to your tool

Claude Code. GitHub's install guide uses add-json for current versions:

Code
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'

To share it with your team, put it in the project's .mcp.json with ${GITHUB_PAT} in place of the token. Claude Code expands it from each person's environment.

Cursor (.cursor/mcp.json or ~/.cursor/mcp.json):

JSON
{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${env:GITHUB_PAT}" }
    }
  }
}

VS Code (.vscode/mcp.json). VS Code can use OAuth, so no token is needed. It opens a GitHub sign-in the first time:

JSON
{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Codex CLI reads the token from the variable at runtime:

Code
codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT

Gemini CLI:

Code
gemini mcp add -s user -t http github https://api.githubcopilot.com/mcp/ -H 'Authorization: Bearer $GITHUB_PAT'

Step 3: give it only the tools you need

The server has dozens of tools grouped into toolsets, such as repos, issues, pull_requests, actions, code_security, discussions and notifications. Loading all of them costs tokens on every request and gives the agent more ways to do something you didn't intend. Two controls help.

Pick toolsets. On the hosted server, add one toolset to the URL path, such as https://api.githubcopilot.com/mcp/x/repos. For several, send a header instead:

Code
"headers": {
  "Authorization": "Bearer ${env:GITHUB_PAT}",
  "X-MCP-Toolsets": "repos,issues,pull_requests"
}

Make it read-only. Add /readonly to the URL (https://api.githubcopilot.com/mcp/readonly) or send X-MCP-Readonly: true. Write tools are then skipped entirely. This is a good default for exploring a codebase or triaging issues.

Running it locally with Docker

The local server takes the same token as an environment variable. In Claude Code:

Code
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT \
  -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

Locally, choose toolsets with the GITHUB_TOOLSETS environment variable (for example repos,issues) and turn on read-only mode with GITHUB_READ_ONLY. For GitHub Enterprise Server, set GITHUB_HOST to your server's https:// address. Enterprise Server can't use the hosted endpoint, so the local server is your option there.

Check it works

Ask: "List the five most recent open issues in owner/repo." You should see a call to an issues tool and a short list. If you get a 401 error, the token is missing or expired. If you get a 404 on a private repository, the token doesn't have access to that repository.

Check yourself

Use https://api.githubcopilot.com/mcp/readonly, or send the X-MCP-Readonly: true header. Write tools are skipped.

The local server, with GITHUB_HOST set to your server's https:// address. Enterprise Server doesn't support the hosted endpoint.

Every tool's definition is sent with each request. Fewer tools means fewer tokens and less chance of the agent picking the wrong one.