GitHub App for the GitHub MCP

The GitHub MCP in Keycard’s Resource catalog is GitHub’s hosted MCP server (https://api.githubcopilot.com/mcp). Keycard protects it and connects each User to GitHub through a GitHub App that you register. When a User approves the app, GitHub issues a token for that User, and every tool call acts as them, limited to what both the User and the app can access.

This page covers the GitHub App that the GitHub MCP setup screen and the Console onboarding guide ask for. To build your own MCP server against the GitHub API with an OAuth App instead, see GitHub.

1. Copy your Keycard redirect URL

   In Keycard Console, open Resources → Add Resource → Explore Resources, search for GitHub, and choose GitHub MCP. The setup screen shows the Redirect URI to give GitHub. It has the form https://<zone-id>.keycard.cloud/oauth/2/redirect, and it’s also under Settings → Connection → Redirect URL. Keep the screen open; you’ll come back to it.

2. Open the new GitHub App form

   In GitHub, click your profile picture, then Settings → Developer settings → GitHub Apps (github.com/settings/apps) and click New GitHub App. To have an organization own the app, start from the organization’s Settings → Developer settings → GitHub Apps instead.

3. Fill in the app details

   Field	Value
   GitHub App name	A name your Users will recognize, such as Greendale GitHub MCP. GitHub shows it when they approve the app. 34 characters at most, and unique across GitHub.
   Homepage URL	Any URL for your organization, for example https://github.com/<github-org>.
   Redirect URI	The Keycard redirect URL from step 1, exactly as Console shows it.
   Expire user authorization tokens	Leave it selected. Keycard refreshes expired tokens.
   Webhook → Active	Deselect it. Keycard doesn’t use webhooks, and GitHub requires a Webhook URL while it’s selected.

   Leave the other fields as they are.

4. Choose permissions

   Under Permissions, set what the GitHub MCP’s tools can do. GitHub limits every tool call to the permissions you pick here, so a tool fails on anything the app can’t access, even when the User could do it on github.com.

   Permission	Access	Tools that need it
   Repository → Metadata	Read-only	Every tool. GitHub selects it for you.
   Repository → Contents	Read & write	Files, branches, commits, tags, releases, code search, and merging pull requests.
   Repository → Issues	Read & write	Reading, creating, and commenting on issues, and issue search.
   Repository → Pull requests	Read & write	Reading, creating, reviewing, and updating pull requests.
   Repository → Administration	Read & write	Only to create or fork repositories.
   Organization → Members	Read-only	Only to list teams and team members.

   Pick Read-only instead of Read & write if agents should only read. Grant the fewest permissions your agents need: you can add more later, and each User approves the change.

5. Choose where the app can be installed

   Under Where can this GitHub App be installed?, choose Only on this account if everyone who uses the GitHub MCP works in this account’s repositories. Choose Any account if Users need it in repositories that other accounts own. Click Create GitHub App.

6. Copy the client ID and generate a client secret

   GitHub opens the app’s settings page. Copy the Client ID. It starts with Iv, and it isn’t the numeric App ID.

   Under Client secrets, click Generate a new client secret and copy the secret right away. GitHub shows it only once. If you lose it, generate a new one and paste the new value into Keycard.

7. Install the app

   In the app’s settings, click Install App, then Install next to the organization or account that owns the repositories. Choose All repositories, or Only select repositories and pick the ones agents should reach. The GitHub MCP can only reach repositories where the app is installed. To change the selection later, open the account’s Settings → GitHub Apps and click Configure next to the app.

   In an organization where you aren’t an owner, GitHub sends the owners an install request instead. Ask one of them to approve it.

1. Paste the credentials into Keycard

   Back on the GitHub MCP setup screen in Console, paste the values from GitHub:

   • Client ID: the GitHub App’s Client ID
   • Client Secret: the client secret you generated

2. Protect the GitHub MCP

   Click Protect GitHub MCP. Keycard creates a GitHub Provider that holds the app’s credentials and a GitHub MCP Resource that uses it.

3. Connect it to your Application

   Add the GitHub MCP to the Application your agent uses. In the Console onboarding guide, choose Add dependency, select GitHub, and choose Connect. Otherwise, open the Application, and on the Dependencies tab click Add dependency and add the GitHub MCP.

4. Approve the app on first use

   The first time a User’s agent calls the GitHub MCP, Keycard sends them to GitHub to approve the app. After that, Keycard issues their GitHub token without asking again.

Keycard keeps GitHub’s error details out of the response to the client, so most GitHub App problems reach the client as a generic error. Match what you see to a cause below.

What you see	Likely cause	Fix
GitHub shows an error page about the redirect URI instead of the approval screen, or the error is redirect_uri_mismatch	The app’s Redirect URI doesn’t match Keycard’s redirect URL: a typo, a trailing slash, another Zone’s URL, or an empty field.	In the app’s settings, set Redirect URI to the URL under Settings → Connection → Redirect URL in Console, character for character.
After the User approves the app, the client gets access_denied with “The provider returned an error. Try again.”, and trying again fails the same way	GitHub rejected the client ID or secret (incorrect_client_credentials): the secret in Keycard was deleted or replaced in GitHub, or a value was pasted wrong. The numeric App ID in place of the Client ID fails the same way.	In GitHub, generate a new client secret. In Console, open Providers, choose the GitHub Provider, and on Configuration paste the Client ID and the new secret, then click Save changes. Then delete the old secret in GitHub.
The same access_denied error once, and trying again works	GitHub rejected an expired or reused approval code (bad_verification_code), for example after a long pause on GitHub’s approval screen.	Start again from the agent.
GitHub MCP tools return Not Found or an empty list for a repository the User can open on github.com	The app isn’t installed on the account that owns the repository, or the installation doesn’t include it.	Install the app on that account, and add the repository under Configure → Repository access.
GitHub MCP tools return 403 Resource not accessible by integration	The app lacks a permission the tool needs, or the installation hasn’t accepted a newly added permission.	Add the permission in the app’s settings under Permissions & events. The owner of each installation then accepts the new permission from the app’s Configure page.
Sign-in to the Zone fails after the User approves the app, with server_error and “An internal server error occurred. Please try again later.”, or the login page says “Sign-in with GitHub failed. Try again.”	The GitHub Provider also signs Users in to the Zone, and the app lacks Account → Email addresses. Keycard can’t read the User’s email, and the retry it suggests fails the same way.	Give the app Account → Email addresses → Read-only. Users sign in again and approve the new permission.