Connect GitHub

Prerequisites

Before connecting GitHub, you need:

• A GitHub repository containing an MCP server
• A bundled JavaScript entry point (.js or .mjs file) committed to your repo
• An mctx.json configuration file in your repository

If you don't have an MCP server yet, see Building MCP Servers to create one.

Step 1: Sign In to mctx

1. Go to app.mctx.ai/dev/servers/new
2. Sign in with your email if prompted
3. You'll receive a login link via Auth0

Step 2: Link GitHub Account

When you first add a server, you'll be prompted to link your GitHub account:

1. Click Connect GitHub
2. Authorize the mctx GitHub App
3. You'll be redirected back to mctx

Your connection is securely stored using encryption so you won't need to reconnect. You can manage your GitHub connection from Settings if you ever need to reconnect or update repository access.

Step 3: Grant Repository Access

After linking GitHub, you need to grant the mctx GitHub App access to repositories:

1. Click Configure repository access
2. Select which repositories mctx can access:
   • All repositories - Grant access to all current and future repos
   • Only select repositories - Choose specific repos from the list
3. Click Install & Authorize or Save

You can change repository access anytime through your GitHub Apps settings.

Step 4: Select Repository

Back on the add server page:

1. Select your repository from the Repository dropdown
2. Enter the Branch name (defaults to your repository's default branch)
3. Enter the Path to your mctx.json file:
   • Leave empty if mctx.json is in the repository root
   • Enter the directory path for monorepos (e.g., packages/my-server)

mctx will validate your repository configuration and show:

• ✓ Ready to deploy - All checks passed
• ✗ Not ready - Specific errors that need fixing

Common validation errors:

• mctx.json not found - Check the path and ensure the file is committed
• Invalid mctx.json - Verify the JSON syntax and required fields
• Entrypoint not found - Ensure the file specified in entrypoint exists and is committed
• Invalid version - Use valid semver format (e.g., 1.0.0, not v1.0.0)

The mctx.json File

Your repository must contain an mctx.json file at the root or in a subdirectory (for monorepos). This file configures your MCP server:

Minimal example:

{
  "version": "1.0.0",
  "description": "Get real-time weather data for any location",
  "entrypoint": "dist/index.js"
}

Required fields:

Optional fields:

For the complete reference, see The mctx.json File.

Repository Requirements

Your repository must meet these requirements:

1. Built JavaScript file - Your entrypoint must be a .js or .mjs file committed to the repo
2. Valid mctx.json - Must be valid JSON with all required fields
3. Accessible to mctx - The mctx GitHub App must have access to the repository

Note: mctx does not run build commands. You must commit your built JavaScript files to the repository, just like GitHub Actions JavaScript actions.

What's Next?

After connecting GitHub and selecting your repository, your dashboard guides you through the remaining setup steps to get your server live. Next up is setting up payouts so you can receive payments from subscribers.

• Set Up Payouts - Complete payout setup to receive payments

See something wrong? Report it or suggest an improvement — your feedback helps make these docs better.