How to Fix the GitHub MCP Server Startup Error

Start with the host output log. “Failed to start” is only a summary. The first useful error usually identifies one of four layers: the MCP host configuration, the local runtime, authentication or hostname settings, or the server-to-host initialization handshake.

GitHub supports both remote and local MCP server operation, but transport support and configuration syntax vary by host. GitHub explicitly directs users to their host application’s documentation for the correct setup process. See the official GitHub MCP server repository before changing configuration.

1. Identify the failing layer

Record these details before editing anything:

MCP host and version, such as VS Code or GitHub Copilot CLI
Operating system
Remote server or local server
Local runtime, such as Docker or a native binary
Authentication method: OAuth or personal access token (PAT)
Exact error text and the first timestamped failure in the log

Symptom	Likely layer	First check
Server does not appear in the host	Host configuration	Host-specific MCP file location and schema
Command not found or process exits immediately	Runtime launch	Executable, Docker, permissions, and arguments
Unauthorized, invalid token, or wrong repository access	Authentication	Credential variables, scopes, and hostname
Server starts, then initialization fails	Protocol handshake	Logs written to stdout and transport settings

2. Read the server output before changing settings

VS Code

When Chat shows an MCP error notification, select it and choose Show Output. You can also run MCP: List Servers from the Command Palette, select the GitHub server, and choose Show Output. Preserve the first error; later messages often only report that startup failed. These steps are documented in the VS Code MCP troubleshooting guidance.

Other hosts

Open the host’s own MCP diagnostics and configuration documentation. Do not copy a VS Code configuration shape into another host automatically. Remote MCP, OAuth, environment-variable expansion, and transport choices are not supported identically everywhere.

3. Verify the local runtime

Docker-based setup

If the local GitHub server uses the container image, confirm that Docker is installed, the daemon is running, and the image can be pulled. Run:

docker version
docker info

Check the configured image name, command, arguments, and environment variables. For a VS Code MCP connection, the process must remain attached to the configured connection. VS Code’s troubleshooting guidance says to verify command arguments and ensure the container is not started in detached mode with -d.

A detached diagnostic command such as this is therefore a common mistake:

docker run -d ...

Remove -d from the MCP server command used by the host so the host can communicate with the running process.

Registry authentication

If pulling the image fails, inspect the registry error rather than the MCP host’s generic message. GitHub’s repository notes that an expired registry token may be fixed with:

docker logout ghcr.io

Then authenticate again using the current instructions from the GitHub repository and retry the pull.

Native local build

GitHub also documents a native local build route using Go. Use it when Docker is unavailable or unsuitable, and follow the repository’s current build and host-registration instructions. A native binary still needs correct host configuration, credentials, and a compatible transport.

4. Check authentication and hostname targeting

GitHub’s local server documentation describes OAuth and PAT authentication. Confirm that the selected method is complete and that the credential is available to the process launched by the MCP host, not only to your interactive shell.

For PAT authentication, verify the variable name required by the server and that the token has the access needed for the requested GitHub operations.
GitHub documents that a configured GITHUB_PERSONAL_ACCESS_TOKEN takes precedence over OAuth. Remove or correct an unintended value when testing OAuth.
For GitHub Enterprise Server or Enterprise Cloud with data residency, use the relevant enterprise hostname and setup instructions instead of the public GitHub host.
Never paste a PAT into a shared log, issue, screen recording, or configuration committed to source control. Redact credentials while collecting diagnostics.

5. Check host-specific MCP configuration

Configuration syntax is host-specific. Verify the file path, server name, transport, executable or URL, arguments, environment-variable names, and JSON syntax against the host’s current documentation and the GitHub repository.

GitHub Copilot CLI

Use Copilot CLI’s supported MCP registration mechanism. GitHub documents migration cases where a VS Code .vscode/mcp.json shape must be converted to the CLI’s .mcp.json format. Do not assume the VS Code file will be read by the CLI.

Also inspect stdout. Copilot CLI documents that server logs or errors written to stdout can be interpreted as protocol data, creating parse errors or stalling initialization. Send diagnostic output to stderr or a file according to the server and host documentation, and keep stdout reserved for MCP protocol messages.

6. Diagnose the initialization handshake

If the process launches but the host reports an initialization failure, check for:

Plain-text banners, debug logs, stack traces, or shell startup output written to stdout
A process that exits after printing one message
A transport mismatch between the host and server
Invalid JSON or malformed command arguments
Environment variables missing from the host’s launched process

Run the command directly in a terminal when the host documentation permits it. This separates an executable or credential problem from a host registration problem. Compare the direct command’s environment with the environment available to the MCP host.

7. Choose a documented connection mode

Mode	Use it when	Requirements
Remote GitHub server	Your MCP host supports the remote transport	Host support, remote URL, and the documented OAuth or credential flow
Docker-local server	You want a containerized local process	Docker daemon, image access, attached process, and environment variables
Native-local server	Docker is unavailable or a native binary fits your workflow	Go build prerequisites, executable permissions, host registration, and credentials

GitHub describes its remote server as the easiest route for compatible hosts, but compatibility and authentication still depend on the host. Switch modes only after confirming that the alternative is supported by your host.

8. Troubleshooting checklist

Copy the exact first error from the host output.
Confirm whether the configured server is remote or local.
Validate the host’s file path and configuration schema.
Run docker info if Docker is involved.
Remove detached mode from the MCP process command.
Retry the image pull and address registry authentication errors.
Confirm OAuth or PAT configuration and the target GitHub hostname.
Check that GITHUB_PERSONAL_ACCESS_TOKEN is not unintentionally overriding OAuth.
For Copilot CLI, use its .mcp.json format where required.
Keep logs and errors off stdout when the host parses stdout as protocol data.
Restart the host after changing configuration, then read the new first error.

9. Common errors, causes, and fixes

Error pattern	Cause	Fix
“Command not found”	The executable is missing or not on the host’s PATH	Use an absolute path or install the documented runtime and verify it from the host’s environment.
Docker daemon or connection error	Docker is not running or the host cannot reach it	Start Docker, run `docker info`, then retry.
Image pull denied or unauthorized	Registry credentials are invalid or expired	Follow the repository’s registry login steps; try `docker logout ghcr.io` before authenticating again.
Initialization parse error	Non-protocol output is written to stdout	Redirect logs to stderr or a file and keep stdout protocol-clean.
Unauthorized API request	Missing, incorrect, or insufficient OAuth/PAT credentials	Set the required variable in the host process and verify token access without exposing it.
Works on public GitHub but not Enterprise	Wrong hostname or enterprise-specific setup	Use the relevant Enterprise Server or data-residency hostname and instructions.
VS Code sees a server but it exits	Incorrect arguments or detached Docker process	Inspect Show Output and remove `-d`; verify command arguments.

10. Reliability and operational notes

Keep the server command and credentials in the host’s supported configuration rather than relying on shell-only aliases.
Pin the setup to the host and server documentation versions you use; UI labels and configuration schemas can change.
Prefer a repeatable launch command and record non-secret settings so another machine can reproduce the diagnosis.
Separate startup checks from permission checks: a server can initialize correctly and still lack access to a repository or organization.
When changing authentication, remove stale variables so precedence rules do not select an unexpected credential.

Or skip the browser setup

If the task that led you here is collecting screenshots for an agent or debugging workflow, ScreenshotNeo provides a direct screenshot API and an MCP server. One request returns PNG, JPEG, WebP, or PDF, while its cleanup steps accept consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture. Each cleanup step can be disabled.

Only clean shots are billed. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the result with X-Page-Verdict and X-Billed headers. Its MCP tools—take_screenshot, get_page_info, and capture_pdf—work with Claude, Cursor, and other MCP clients.

See the ScreenshotNeo API documentation for all options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://github.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://github.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://github.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

There are 1,000 free screenshots each month with no card. Paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Why is the exact error text necessary?

The same generic startup notice can represent a bad host schema, missing Docker, invalid credentials, or a protocol parse failure. The first log entry distinguishes these layers.

Can I use a VS Code MCP configuration in Copilot CLI?

Not automatically. GitHub documents migration cases where the VS Code shape must be converted to Copilot CLI’s .mcp.json format.

Does a successful process launch prove GitHub access works?

No. Startup proves the host and server initialized. Repository, organization, and enterprise permissions are separate checks.

Should MCP diagnostics go to stdout?

Not when the host parses stdout as MCP protocol data. In Copilot CLI, non-protocol stdout can cause parse errors or stall initialization.