GitHub MCP server: tools, toolsets, read-only

GitHub's default tools arrive before the first request. Unless the client defers tool loading, their definitions take context before the agent asks anything.

Checked 1 September 2026 · from GitHub's repository, its documentation and the server's own tools/list response

One of 91 guides to monitoring and developer tools. Each covers what an AI coding agent can get out of the tool through MCP, the protocol that lets the agent query the tool directly.

What is the GitHub MCP server?

It is GitHub's server for the Model Context Protocol. You point the agent at a hosted endpoint or run a small binary, and the agent gains a set of tools: read this pull request, list those workflow runs, search that code.

There are two ways to connect, and they are not equivalent. The hosted server at api.githubcopilot.com/mcp/ needs no install and authenticates with OAuth. The local binary needs a personal access token and runs on your machine, which is the only option for GitHub Enterprise Server.

Tools are grouped into toolsets you switch on by name with GITHUB_TOOLSETS. all enables every one. The agent then picks tools on its own based on what you ask in English.

GitHub covers code review and release broadly, and reaches nothing in production observability, agent observability or cost.

For an agent, GitHub answers questions about the code and the pipeline that shipped it, and nothing about what happened afterwards. An agent connected here can find the pull request that introduced a regression and re-run the job that caught it. It cannot tell you the regression is happening in production. Pair this connector with an observability connector.

What can an AI agent do with GitHub?

The toolset column matters more here than on most connectors. actions is not in the default set, so an agent asked about a failed build on a default connection reports nothing and does not explain why. Enable it by name before asking about CI.

What the tool definitions cost in context

A client that loads every tool definition at the start of a session spends this much context before the first question. Claude Code defers definitions by default through tool search, and loads a tool's definition when the agent needs it. The method below gives the version and date measured.

A context window is the amount of text a model can hold at once. A client that loads every tool definition upfront sends each tool's name, description and input schema to the model when the session starts. That list is charged whether or not a single tool is called.

GitHub does not publish this figure, and neither does any other vendor in this guide. Turning every toolset on roughly doubles the context cost. Name the toolsets you need instead of sending all.

Encodings: GPT-5.6, GPT-5.5 o200k_base; GPT-4, GPT-3.5 cl100k_base; Claude Haiku 4.5 to Opus 5 count_tokens. Counted 19 August 2026 from tools/list on the released v1.9.0 Darwin binary. It was run locally with a placeholder token. Later releases added tools, so these figures understate the current cost.

Registration is static, so no GitHub account was involved. Figures cover name, description and input schema. The two models in column one share the o200k_base encoding, so they get one count. The spread is formatting, about 49%. Reasoning tokens are output, spent per request. This count is billed as input whenever the client loads it.

The Claude figures are measured rather than encoded. Anthropic publishes no local tokenizer. The definitions were sent to the API's count_tokens endpoint, and a no-tools baseline was subtracted. The range covers two tokenizer generations rather than two serializations. Haiku 4.5 and Opus 4.6 sit at the low end. Opus 5 and Sonnet 5 sit at the high end. The gap between them is about a third.

GitHub MCP server limits: where answers come back incomplete

Every limit below is documented by GitHub. None of them announces itself in the response, so the agent answers confidently either way.

How to configure GitHub MCP for agents

1. 1

   Decide on write access first

   --read-only is a real server-side flag, and it takes priority over --tools: a write tool named explicitly is still skipped. It leaves 26 of the 44 default tools, so 18 of the defaults write.

2. 2

   Name your toolsets

   GITHUB_TOOLSETS defaults to a subset that excludes actions, so a default connection cannot answer a CI question. GITHUB_TOOLSETS=all enables everything and roughly doubles the context cost, from about 10,535 tokens to about 19,558.

3. 3

   Choose hosted or local

   The hosted server at api.githubcopilot.com/mcp/ needs no install and authenticates with OAuth. The local binary needs a personal access token, and is the only option for GitHub Enterprise Server.

4. 4

   Raise the content window for review work

   Tool output is truncated at 5,000 characters by default, set with --content-window-size. A large diff or a long job log is cut at that boundary with no marker.

Paste this into your agent’s instructions

Two of GitHub's limits arrive silently: the content window truncates without saying so, and a toolset that is off produces an empty answer that reads like a real one. The block below makes the agent state both rather than answering around them.

When you answer using GitHub MCP tools, state:
- Which toolsets are enabled. If a question needs a toolset
  that is not enabled, say so rather than reporting nothing
  found.
- Whether any tool output was truncated. The content window
  is 5,000 characters by default and truncation is silent.
- The branch and repository each result came from. Code search
  indexes the default branch only.
Never state that data does not exist. State that it was not
found under the constraints above.
Write your answer in ASD-STE100 Simplified Technical
English. Use short sentences with one idea in each.

Do you need the MCP server at all?

Sometimes. A coding agent already has git and the gh CLI, and for reading a diff or checking out a branch those are faster and cost no context at all.

The MCP server earns its place on the things gh does not make easy: code scanning alerts, Dependabot, discussions, and search across an organization. It also gives the agent tool descriptions, so it can pick the right call without you naming the endpoint.

The split is simple. gh is better inside one repository you have already cloned. The server is better for questions that span repositories, or reach features with no convenient CLI shape.

If the agent already has the repository checked out, reach for gh first. Connect the server when the question spans repositories or touches security and Actions data.

GitHub MCP server setup

The hosted server needs nothing installed: point the client at https://api.githubcopilot.com/mcp/ and complete the OAuth flow. The local server needs the binary or Docker, plus a personal access token in GITHUB_PERSONAL_ACCESS_TOKEN.

GITHUB_PERSONAL_ACCESS_TOKEN takes precedence over OAuth when both are present. Grant the token only the scopes you are comfortable giving an agent; the security toolset needs security_events.

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

claude mcp add-json "github" '{"command":"github-mcp-server",
  "args":["stdio","--read-only"],
  "env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"<your-token>",
         "GITHUB_TOOLSETS":"repos,issues,pull_requests,actions"}}'

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

[mcp_servers.github]
command = "github-mcp-server"
args = ["stdio", "--read-only"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "<your-token>" }

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

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

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

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

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

docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN \
  ghcr.io/github/github-mcp-server stdio --read-only

GITHUB_HOST=https://ghe.example.com \
GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> github-mcp-server stdio

Read-only access, permissions and security

• Read-only is a real flag

  --read-only is enforced by the server, not by the client, and it takes priority over --tools. It leaves 26 of the 44 default tools.

• Scope the token

  The personal access token's permissions are the agent's permissions. GitHub's own guidance is to grant only the scopes you are comfortable giving an AI tool, and to restrict file permissions on any config holding one.

• Write tools ship in the defaults

  issue_write, create_pull_request, add_issue_comment and actions_run_trigger are all in the default set. actions_run_trigger re-runs workflows, which can redeploy.

• The server declares which tools are safe

  Of the 85 tools on v1.9.0, 54 carry a readOnlyHint of true and 31 do not. That hint is an annotation the server attaches to each tool, saying whether the tool only reads. A client that respects annotations can gate on the server's own declaration.

Troubleshooting

The agent says there are no workflow runs

The actions toolset is not in the default set. Set GITHUB_TOOLSETS to include it, then ask again.

A diff or log is cut off partway

The content window truncates tool output at 5,000 characters by default. Raise it with --content-window-size, or ask for the specific file or failed step rather than the whole thing.

403 on a security tool

Code scanning, secret scanning and Dependabot need the token to carry security_events. A token without it reaches the rest of the server normally.

A write happened that you did not intend

Write tools are in the default set. Restart with --read-only, which the server enforces even when --tools names a write tool explicitly.

The hosted server will not connect from Enterprise Server

GitHub Enterprise Server does not support remote server hosting. Run the local binary with GITHUB_HOST pointed at your instance.

GitHub MCP server: Reference

What engineers report

GitHub's server is the most widely used in the directory, and the discussion reflects that: 33,394 stars as of 6 October 2026 and a steady release cadence. The recurring themes are tool count and permission scope rather than whether it works.

“PATs are long lived credentials that are discouraged, and sometimes entirely restricted in many organizations. This limits the organizations from taking advantage of this MCP server.”

“Currently, GitHub MCP Server lacks the ability to access private repositories that belong to organizations where a user is a member. This is a significant limitation for professional developers who primarily work with company repositories.”

Repository counts retrieved from the GitHub API on 6 October 2026. Tool counts come from the server's own tools/list response on the released v1.9.0 binary, measured 19 August 2026.

Should you connect an agent to GitHub?

Yes. Best for any team already on GitHub, connected with named toolsets and --read-only unless a write is the point of the session.

Strongest fit

Teams that want an agent working across code review and CI in one conversation, especially where code scanning and Dependabot are part of the review.

Main advantage

Breadth and maintenance. It reaches more of the code-and-release stages than any other connector here, and it is actively released.

Main weakness

Size. 44 tools arrive before you ask for anything, and enabling every toolset roughly doubles the context cost.

Operational risk

Write tools ship in the default set, including workflow re-runs. Read-only is a flag you have to set.

Frequently asked questions