Skip to main content

​
Prerequisites

  • Access to your Runlayer instance
  • GitHub organization admin permissions
  • Admin / Server Admin permissions in Runlayer (to add servers)

​
Setup Steps

1

Create GitHub OAuth Application

  1. Go to your organization’s Developer Settings
    • Navigate to Settings → Developer settings → OAuth Apps → New OAuth app
GitHub Organization OAuth Apps List
  1. Fill in the details:
    • Application name: Choose a name (e.g., Runlayer MCP)
    • Homepage URL: Your Runlayer instance URL
    • Authorization callback URL: https://<your-tenant-url>.runlayer.com/oauth/callback/
      • For self-hosted: Use your exact tenant URL
  2. Click Register application
GitHub OAuth App Registration Form
2

Generate Client Secret

  1. After creating the app, you’ll see the Client ID (save this)
  2. Click Generate a new client secret
  3. Copy the Client Secret immediately (it’s only shown once)
  4. Save both credentials temporarily in a secure location
GitHub Client Credentials Page
3

Add GitHub Server in Runlayer

  1. In your Runlayer instance, go to Catalog
  2. Find GitHub and click Install MCP
  3. In the server configuration form:
    • Check Custom OAuth credentials
    • Enter your Client ID and Client Secret
  4. Click Create Hosted Server
GitHub Server Configuration with Custom OAuth
4

Authorize GitHub Access

  1. After creating the server, you’ll be redirected to the server details page
  2. Under Missing Authorization, click Connect
GitHub Server Missing Authorization
  1. This opens GitHub’s OAuth authorization page
GitHub OAuth Authorization Page
  1. Review the requested permissions and select repositories
  2. Click Authorize to complete the flow
5

Verify Connection

After successful authorization, you’ll be redirected back to Runlayer. The server will now show:
  • Active status
  • List of available tools (e.g., create_branch, add_issue_comment, etc.)
  • Revoke Access option in the Connection section
GitHub Server with Available Tools

​
Troubleshooting

Error: “The redirect_uri is not associated with this application.”GitHub Invalid Redirect URI ErrorSolution:
  • Verify the callback URL in your GitHub OAuth app matches exactly: https://<your-tenant-url>.runlayer.com/oauth/callback/
  • For self-hosted instances, ensure you’re using the exact tenant URL
  • The URL must include the trailing slash
Issue: Authorization popup completes successfully, but you see a “Failed to Connect” error in Runlayer.Failed to Connect ErrorCause: This occurs when the OAuth authorization succeeds, but the token exchange fails due to invalid Client ID or Client Secret.Solution:
  • Verify your Client ID and Client Secret are correct in the server configuration
  • Check that you copied the Client Secret correctly (it’s only shown once)
  • Regenerate the Client Secret in GitHub if needed
  • Ensure the credentials match the OAuth app you’re using
  • Try disconnecting and reconnecting the server with updated credentials
Error: “Invalid client credentials” or authentication failsSolution:
  • Double-check your Client ID and Client Secret are correct
  • Ensure the Client Secret hasn’t expired (regenerate if needed)
  • Verify the OAuth app is active in your organization’s Developer Settings
Issue: Server shows as connected but no tools are visibleSolution:
  • Refresh the page
  • Check that you authorized the required scopes in GitHub
  • Try revoking and re-authorizing the connection
  • Verify the server status shows “Active”

​
Next Steps

Once your GitHub MCP server is set up and authorized:
  • Connect to your MCP client: Use the “Add to MCP Client” section to integrate with Cursor, VS Code, or other supported clients
  • Review available tools: Browse the 40+ GitHub tools available for repository management, issue tracking, and more
  • Manage permissions: You can revoke access at any time from the Connection section

OAuth Broker Guide

Learn more about OAuth Broker and BYOC

MCP Custom Servers

Create other custom MCP servers