wehub-resource-sync
194 lines
13 KiB
Markdown
194 lines
13 KiB
Markdown
# GitHub Remote MCP Integration Guide for MCP Host Authors
|
||
|
||
This guide outlines high-level considerations for MCP Host authors who want to allow installation of the Remote GitHub MCP server.
|
||
|
||
The goal is to explain the architecture at a high-level, define key requirements, and provide guidance to get you started, while pointing to official documentation for deeper implementation details.
|
||
|
||
---
|
||
|
||
## Table of Contents
|
||
|
||
- [Understanding MCP Architecture](#understanding-mcp-architecture)
|
||
- [Connecting to the Remote GitHub MCP Server](#connecting-to-the-remote-github-mcp-server)
|
||
- [Authentication and Authorization](#authentication-and-authorization)
|
||
- [OAuth Support on GitHub](#oauth-support-on-github)
|
||
- [Create an OAuth-enabled App Using the GitHub UI](#create-an-oauth-enabled-app-using-the-github-ui)
|
||
- [Things to Consider](#things-to-consider)
|
||
- [Initiating the OAuth Flow from your Client Application](#initiating-the-oauth-flow-from-your-client-application)
|
||
- [Handling Organization Access Restrictions](#handling-organization-access-restrictions)
|
||
- [Essential Security Considerations](#essential-security-considerations)
|
||
- [Additional Resources](#additional-resources)
|
||
|
||
---
|
||
|
||
## Understanding MCP Architecture
|
||
|
||
The Model Context Protocol (MCP) enables seamless communication between your application and various external tools through an architecture defined by the [MCP Standard](https://modelcontextprotocol.io/).
|
||
|
||
### High-level Architecture
|
||
|
||
The diagram below illustrates how a single client application can connect to multiple MCP Servers, each providing access to a unique set of resources. Notice that some MCP Servers are running locally (side-by-side with the client application) while others are hosted remotely. GitHub's MCP offerings are available to run either locally or remotely.
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph "Local Runtime Environment"
|
||
subgraph "Client Application (e.g., IDE)"
|
||
CLIENTAPP[Application Runtime]
|
||
CX["MCP Client (FileSystem)"]
|
||
CY["MCP Client (GitHub)"]
|
||
CZ["MCP Client (Other)"]
|
||
end
|
||
|
||
LOCALMCP[File System MCP Server]
|
||
end
|
||
|
||
subgraph "Internet"
|
||
GITHUBMCP[GitHub Remote MCP Server]
|
||
OTHERMCP[Other Remote MCP Server]
|
||
end
|
||
|
||
CLIENTAPP --> CX
|
||
CLIENTAPP --> CY
|
||
CLIENTAPP --> CZ
|
||
|
||
CX <-->|"stdio"| LOCALMCP
|
||
CY <-->|"OAuth 2.0 + HTTP/SSE"| GITHUBMCP
|
||
CZ <-->|"OAuth 2.0 + HTTP/SSE"| OTHERMCP
|
||
```
|
||
|
||
### Runtime Environment
|
||
|
||
- **Application**: The user-facing application you are building. It instantiates one or more MCP clients and orchestrates tool calls.
|
||
- **MCP Client**: A component within your client application that maintains a 1:1 connection with a single MCP server.
|
||
- **MCP Server**: A service that provides access to a specific set of tools.
|
||
- **Local MCP Server**: An MCP Server running locally, side-by-side with the Application.
|
||
- **Remote MCP Server**: An MCP Server running remotely, accessed via the internet. Most Remote MCP Servers require authentication via OAuth.
|
||
|
||
For more detail, see the [official MCP specification](https://modelcontextprotocol.io/specification/2025-06-18).
|
||
|
||
> [!NOTE]
|
||
> GitHub offers both a Local MCP Server and a Remote MCP Server.
|
||
|
||
---
|
||
|
||
## Connecting to the Remote GitHub MCP Server
|
||
|
||
### Authentication and Authorization
|
||
|
||
GitHub MCP Servers require a valid access token in the `Authorization` header. This is true for both the Local GitHub MCP Server and the Remote GitHub MCP Server.
|
||
|
||
For the Remote GitHub MCP Server, the recommended way to obtain a valid access token is to ensure your client application supports [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13). It should be noted, however, that you may also supply any valid access token. For example, you may supply a pre-generated Personal Access Token (PAT).
|
||
|
||
|
||
> [!IMPORTANT]
|
||
> The Remote GitHub MCP Server itself does not provide Authentication services.
|
||
> Your client application must obtain valid GitHub access tokens through one of the supported methods.
|
||
|
||
The expected flow for obtaining a valid access token via OAuth is depicted in the [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-flow-steps). For convenience, we've embedded a copy of the authorization flow below. Please study it carefully as the remainder of this document is written with this flow in mind.
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant B as User-Agent (Browser)
|
||
participant C as Client
|
||
participant M as MCP Server (Resource Server)
|
||
participant A as Authorization Server
|
||
|
||
C->>M: MCP request without token
|
||
M->>C: HTTP 401 Unauthorized with WWW-Authenticate header
|
||
Note over C: Extract resource_metadata URL from WWW-Authenticate
|
||
|
||
C->>M: Request Protected Resource Metadata
|
||
M->>C: Return metadata
|
||
|
||
Note over C: Parse metadata and extract authorization server(s)<br/>Client determines AS to use
|
||
|
||
C->>A: GET /.well-known/oauth-authorization-server
|
||
A->>C: Authorization server metadata response
|
||
|
||
alt Dynamic client registration
|
||
C->>A: POST /register
|
||
A->>C: Client Credentials
|
||
end
|
||
|
||
Note over C: Generate PKCE parameters
|
||
C->>B: Open browser with authorization URL + code_challenge
|
||
B->>A: Authorization request
|
||
Note over A: User authorizes
|
||
A->>B: Redirect to callback with authorization code
|
||
B->>C: Authorization code callback
|
||
C->>A: Token request + code_verifier
|
||
A->>C: Access token (+ refresh token)
|
||
C->>M: MCP request with access token
|
||
M-->>C: MCP response
|
||
Note over C,M: MCP communication continues with valid token
|
||
```
|
||
|
||
> [!NOTE]
|
||
> Dynamic Client Registration is NOT supported by Remote GitHub MCP Server at this time.
|
||
|
||
|
||
#### OAuth Support on GitHub
|
||
|
||
GitHub offers two solutions for obtaining access tokens via OAuth: [**GitHub Apps**](https://docs.github.com/en/apps/using-github-apps/about-using-github-apps#about-github-apps) and [**OAuth Apps**](https://docs.github.com/en/apps/oauth-apps). These solutions are typically created, administered, and maintained by GitHub Organization administrators. Collaborate with a GitHub Organization administrator to configure either a **GitHub App** or an **OAuth App** to allow your client application to utilize GitHub OAuth support. Furthermore, be aware that it may be necessary for users of your client application to register your **GitHub App** or **OAuth App** within their own GitHub Organization in order to generate authorization tokens capable of accessing Organization's GitHub resources.
|
||
|
||
> [!TIP]
|
||
> Before proceeding, check whether your organization already supports one of these solutions. Administrators of your GitHub Organization can help you determine what **GitHub Apps** or **OAuth Apps** are already registered. If there's an existing **GitHub App** or **OAuth App** that fits your use case, consider reusing it for Remote MCP Authorization. That said, be sure to take heed of the following warning.
|
||
|
||
> [!WARNING]
|
||
> Both **GitHub Apps** and **OAuth Apps** require the client application to pass a "client secret" in order to initiate the OAuth flow. If your client application is designed to run in an uncontrolled environment (i.e. customer-provided hardware), end users will be able to discover your "client secret" and potentially exploit it for other purposes. In such cases, our recommendation is to register a new **GitHub App** (or **OAuth App**) exclusively dedicated to servicing OAuth requests from your client application.
|
||
|
||
#### Create an OAuth-enabled App Using the GitHub UI
|
||
|
||
Detailed instructions for creating a **GitHub App** can be found at ["Creating GitHub Apps"](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps#building-a-github-app). (RECOMMENDED)<br/>
|
||
Detailed instructions for creating an **OAuth App** can be found ["Creating an OAuth App"](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app).
|
||
|
||
For guidance on which type of app to choose, see ["Differences Between GitHub Apps and OAuth Apps"](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps).
|
||
|
||
#### Things to Consider:
|
||
- Tokens provided by **GitHub Apps** are generally more secure because they:
|
||
- include an expiration
|
||
- include support for fine-grained permissions
|
||
- **GitHub Apps** must be installed on a GitHub Organization before they can be used.<br/>In general, installation must be approved by someone in the Organization with administrator permissions. For more details, see [this explanation](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps#who-can-install-github-apps-and-authorize-oauth-apps).<br/>By contrast, **OAuth Apps** don't require installation and, typically, can be used immediately.
|
||
- Members of an Organization may use the GitHub UI to [request that a GitHub App be installed](https://docs.github.com/en/apps/using-github-apps/requesting-a-github-app-from-your-organization-owner) organization-wide.
|
||
- While not strictly necessary, if you expect that a wide range of users will use your MCP Server, consider publishing its corresponding **GitHub App** or **OAuth App** on the [GitHub App Marketplace](https://github.com/marketplace?type=apps) to ensure that it's discoverable by your audience.
|
||
|
||
|
||
#### Initiating the OAuth Flow from your Client Application
|
||
|
||
For **GitHub Apps**, details on initiating the OAuth flow from a client application are described in detail [here](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#using-the-web-application-flow-to-generate-a-user-access-token).
|
||
|
||
For **OAuth Apps**, details on initiating the OAuth flow from a client application are described in detail [here](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#web-application-flow).
|
||
|
||
> [!IMPORTANT]
|
||
> For endpoint discovery, be sure to honor the [`WWW-Authenticate` information provided](https://modelcontextprotocol.io/specification/draft/basic/authorization#authorization-server-location) by the Remote GitHub MCP Server rather than relying on hard-coded endpoints like `https://github.com/login/oauth/authorize`.
|
||
|
||
|
||
### Handling Organization Access Restrictions
|
||
Organizations may block **GitHub Apps** and **OAuth Apps** until explicitly approved. Within your client application code, you can provide actionable next steps for a smooth user experience in the event that OAuth-related calls fail due to your **GitHub App** or **OAuth App** being unavailable (i.e. not registered within the user's organization).
|
||
|
||
1. Detect the specific error.
|
||
2. Notify the user clearly.
|
||
3. Depending on their GitHub organization privileges:
|
||
- Org Members: Prompt them to request approval from a GitHub organization admin, within the organization where access has not been approved.
|
||
- Org Admins: Link them to the corresponding GitHub organization’s App approval settings at `https://github.com/organizations/[ORG_NAME]/settings/oauth_application_policy`
|
||
|
||
|
||
## Essential Security Considerations
|
||
- **Token Storage**: Use secure platform APIs (e.g. keytar for Node.js).
|
||
- **Input Validation**: Sanitize all tool arguments.
|
||
- **HTTPS Only**: Never send requests over plaintext HTTP. Always use HTTPS in production.
|
||
- **PKCE:** We strongly recommend implementing [PKCE](https://datatracker.ietf.org/doc/html/rfc7636) for all OAuth flows to prevent code interception, to prepare for upcoming PKCE support.
|
||
|
||
## Additional Resources
|
||
- [MCP Official Spec](https://modelcontextprotocol.io/specification/draft)
|
||
- [MCP SDKs](https://modelcontextprotocol.io/sdk/java/mcp-overview)
|
||
- [GitHub Docs on Creating GitHub Apps](https://docs.github.com/en/apps/creating-github-apps)
|
||
- [GitHub Docs on Using GitHub Apps](https://docs.github.com/en/apps/using-github-apps/about-using-github-apps)
|
||
- [GitHub Docs on Creating OAuth Apps](https://docs.github.com/en/apps/oauth-apps)
|
||
- GitHub Docs on Installing OAuth Apps into a [Personal Account](https://docs.github.com/en/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-personal-account) and [Organization](https://docs.github.com/en/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-organization)
|
||
- [Managing OAuth Apps at the Organization Level](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data)
|
||
- [Managing Programmatic Access at the GitHub Organization Level](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization)
|
||
- [Building Copilot Extensions](https://docs.github.com/en/copilot/building-copilot-extensions)
|
||
- [Managing App/Extension Visibility](https://docs.github.com/en/copilot/building-copilot-extensions/managing-the-availability-of-your-copilot-extension) (including GitHub Marketplace information)
|
||
- [Example Implementation in VS Code Repository](https://github.com/microsoft/vscode/blob/main/src/vs/workbench/api/common/extHostMcp.ts#L313)
|