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

> Discover how remote GitHub MCP Server architecture differs from local deployment. Learn when to use each for your development needs.

- Repository: [GitHub/github-mcp-server](https://github.com/github/github-mcp-server)
- Tags: architecture
- Published: 2026-02-16

---

**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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/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:

```json
{
  "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`](https://github.com/github/github-mcp-server/blob/main/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:

```bash
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:

```bash
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.