How Remote GitHub MCP Server Architecture Differs from Local Deployment: A Complete Guide

The remote GitHub MCP Server runs as a managed HTTP endpoint at https://api.githubcopilot.com/mcp/ inside GitHub's infrastructure with remote-only toolsets and header-based configuration, while the local server requires running your own binary or container with CLI flags, supports dynamic toolset discovery, and is required for GitHub Enterprise Server deployments.

The github/github-mcp-server repository provides two distinct architectural patterns for exposing GitHub functionality through the Model Context Protocol (MCP). Understanding how the remote GitHub MCP Server architecture differs from local server deployment is essential for choosing the right approach for your development environment, security requirements, and GitHub hosting scenario.

Core Architectural Differences

Deployment Model and Infrastructure

The fundamental distinction lies in where the server binary executes. According to the source code in cmd/github-mcp-server/main.go, the local server runs as a separate process owned by the user—either as a Docker container, via go run ./cmd/github-mcp-server stdio, or as a compiled binary. The same source code is used for both architectures, but the local executable must be started manually by the user.

Conversely, the remote GitHub MCP Server is deployed inside GitHub's own infrastructure. The binary in this repository is compiled as a library and linked into an internal service that listens at https://api.githubcopilot.com/mcp/. As documented in docs/remote-server.md, no binary needs to be shipped or started by the user when using the remote architecture.

Transport and Configuration Methods

Configuration mechanisms differ significantly between the two architectures. The remote server operates as a pure HTTP endpoint where configuration is supplied through HTTP headers such as X-MCP-Toolsets, X-MCP-Tools, X-MCP-Readonly, and X-MCP-Insiders. URL path modifiers can also enforce specific configurations, such as /x/issues/readonly to enable only the issues toolset in read-only mode.

The local server, as implemented in pkg/http/server.go, can be started either as an HTTP server (github-mcp-server http …) or as a stdio server (github-mcp-server stdio …). Configuration is passed via command-line flags or environment variables, including --toolsets, GITHUB_TOOLSETS, --lockdown-mode, and GITHUB_LOCKDOWN_MODE.

Toolset Availability and Discovery

The remote architecture includes all public toolsets plus three remote-only toolsets: copilot, copilot_spaces, and github_support_docs_search. These specialized toolsets are only exposed by the remote service and cannot be accessed when running a local server.

However, the local server supports dynamic toolset discovery through the --dynamic-toolsets flag, which loads discovery tools such as enable_toolset and list_available_toolsets on demand. This capability is not supported in the remote architecture, where the set of enabled toolsets is fixed at start-up based on the headers provided.

When to Use the Remote GitHub MCP Server

Choose the remote architecture when you need immediate availability without operational overhead. The remote server is ideal for zero-setup scenarios where you want MCP tools available in supported IDEs such as VS Code 1.101+, Claude Desktop, or Cursor. Since the endpoint is always up, you only need to add a simple JSON configuration block or use a click-install button—no Docker containers or compiled binaries required.

The remote server is also necessary when you require the remote-only toolsets. If your workflow depends on copilot, copilot_spaces, or github_support_docs_search functionality, you must use the remote architecture as these tools are not available in local deployments.

Additionally, choose remote when operating in managed environments such as GitHub-hosted CI, Codespaces, or corporate environments where you cannot run arbitrary containers. The remote server runs inside GitHub's network, avoiding firewall or policy restrictions that might prevent local process execution.

When to Use the Local GitHub MCP Server

Select the local architecture when you require full control over the runtime environment or need to operate in restricted networks. The local server is required for GitHub Enterprise Server (GHES) deployments, as the remote hosting is not supported for GHES instances according to the repository documentation.

Use the local server when you need dynamic toolset discovery capabilities. The --dynamic-toolsets flag enables runtime loading of toolsets, which is essential for scenarios where you want to enable or disable functionality on demand rather than at startup.

Local deployment is also necessary for debugging and development workflows. When you need to inspect logs, adjust --log-file settings, or enable command logging via --enable-command-logging, you must run the binary locally to access these diagnostic features.

Choose local when operating in air-gapped or on-premises environments where you cannot reach api.githubcopilot.com, or when you need to enforce internal firewall rules that prohibit external HTTP endpoints. The local server also supports classic Personal Access Tokens (PATs) filtered at startup based on their scopes, which is useful when OAuth flows are not available.

Configuration Examples

Remote Server HTTP Headers

To configure the remote GitHub MCP Server, include specific headers in your HTTP requests or client configuration:

{
  "type": "http",
  "url": "https://api.githubcopilot.com/mcp/",
  "headers": {
    "X-MCP-Toolsets": "repos,issues,pull_requests",
    "X-MCP-Readonly": "false",
    "X-MCP-Insiders": "true"
  }
}

The X-MCP-Toolsets header selects specific functionality, while X-MCP-Readonly controls write permissions. Setting X-MCP-Insiders to true activates early-access tools. This configuration can be pasted into VS Code settings.json under "mcp.servers.github".

Local Server CLI and Environment Variables

For local deployment, use command-line flags or environment variables to achieve equivalent configuration:

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PAT \
  -e GITHUB_TOOLSETS="repos,issues" \
  -e GITHUB_READ_ONLY="true" \
  ghcr.io/github/github-mcp-server \
  http --port 8082 --lockdown-mode

This Docker command maps environment variables to the same toolset and permission controls available in the remote server. The --lockdown-mode flag enforces additional security restrictions. For stdio transport with dynamic discovery:

github-mcp-server stdio \
  --dynamic-toolsets \
  --tools=get_me,search_code \
  --insiders

The --dynamic-toolsets flag enables runtime toolset loading, which is exclusive to the local architecture.

Summary

• Remote GitHub MCP Server runs as a managed HTTP endpoint inside GitHub's infrastructure at https://api.githubcopilot.com/mcp/, requiring no local runtime but limiting configuration to HTTP headers and excluding dynamic toolset discovery.
• Local GitHub MCP Server requires running your own binary or container with CLI flags and environment variables, supports dynamic toolset discovery via --dynamic-toolsets, and is mandatory for GitHub Enterprise Server deployments.
• Remote-only toolsets (copilot, copilot_spaces, github_support_docs_search) are exclusively available through the remote architecture.
• Authentication methods differ: remote expects OAuth tokens with scope challenge headers, while local supports both OAuth and classic PATs with startup scope filtering.
• Configuration parity exists between both architectures, but local deployment offers additional debugging capabilities through --enable-command-logging and custom log files.

Frequently Asked Questions

Can I use the remote GitHub MCP Server with GitHub Enterprise Server?

No, the remote GitHub MCP Server is not supported for GitHub Enterprise Server (GHES) deployments. According to the repository documentation, GHES users must run a local GitHub MCP Server instance because the remote endpoint at api.githubcopilot.com cannot connect to internal GHES instances. Local deployment allows you to point the server at your internal GHES URL using standard GitHub API environment variables.

How do I enable insider features on each architecture?

For the remote GitHub MCP Server, enable insider features by including the X-MCP-Insiders: true HTTP header in your configuration, or by using the /insiders URL path modifier. For the local GitHub MCP Server, start the binary with the --insiders command-line flag or set the GITHUB_INSIDERS environment variable to true. Both methods activate early-access toolsets, though the remote server may receive insider updates before they are available in the open-source binary.

Which authentication methods work with remote vs local servers?

The remote GitHub MCP Server primarily expects OAuth tokens and can issue scope challenges via the X-MCP-Scope-Challenge header when additional permissions are required. The local GitHub MCP Server supports both OAuth tokens and classic Personal Access Tokens (PATs). When using a local server with a classic PAT, the server filters available tools at startup based on the token's scopes, whereas OAuth tokens can dynamically request additional scopes through the challenge mechanism when using the remote server.

Can I switch between remote and local without changing my client code?

Yes, if your client uses a standard MCP client library that abstracts transport details. Both architectures expose the same MCP protocol, so tool calls and responses remain identical. However, you must update configuration parameters: switch from HTTP headers (X-MCP-Toolsets, etc.) to CLI flags or environment variables (GITHUB_TOOLSETS, etc.), and change the transport type from http to stdio or a local HTTP port. The ghmcp package used by both servers builds identical request handling logic, but the transport layer differs based on the type field in your configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}