Connect GitHub

By the end of this page, your GitHub repo is connected to mctx and your App is created. Takes about 2 minutes.

Before you start

You need a GitHub repository with:

• A package.json with name, version, description, and main fields
• A built JavaScript file (.js or .mjs) committed in your repo -- the file that main points to

If you don't have an App yet, build one in under 5 minutes using the @mctx-ai/app framework — or start from the example template for a pre-configured project you can customize and deploy.

Step 1: Sign in

Go to app.mctx.ai/dev/servers/new and sign in. You can sign in with your email and password, Google, or GitHub.

Step 2: Connect your GitHub account

When you first add a server, mctx prompts you to link GitHub:

1. Click Connect GitHub Account
2. Authorize the mctx GitHub App
3. You are redirected back to mctx

This is a one-time step. Your connection is encrypted and stored securely. You can manage it anytime from Developer Settings.

Step 3: Grant repository access

After linking GitHub, grant mctx access to the repositories you want to deploy:

1. Click Configure repository access
2. Select All repositories or pick specific ones
3. Click Install GitHub App

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

Step 4: Select your repository

Back on the add App page:

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

mctx validates your repository and shows a result:

• Ready to deploy -- All checks passed. You are good to go.
• Not ready -- Something needs fixing. See below.

Your package.json

mctx reads your standard package.json for server configuration. No custom config files needed.

Minimal example:

{
  "name": "weather-api",
  "version": "1.0.0",
  "description": "Get real-time weather data for any location",
  "main": "dist/index.js",
  "type": "module"
}

Required fields: name, version, description, and main. The main field points to your built JavaScript file. Capabilities are auto-detected at deploy time — nothing extra to configure.

Runtime instructions (what AI clients receive when they connect) are set in code via createServer({ instructions: "..." }). You can also set instructions in package.json for use when publishing to the MCP Community Registry — these are two separate fields with two separate purposes. See package.json Configuration for details.

For the complete field reference including version formatting, description best practices, and build tool examples, see Server Requirements.

If validation fails

These are the most common issues and how to fix them.

"package.json not found" -- Check the path field. Make sure package.json is committed to the branch you selected, at the root or the subdirectory you specified.

"Main file not found" -- The file in your main field does not exist in the repo. Make sure you have built your project and committed the output file. mctx does not run build commands -- you commit the built file, similar to GitHub Actions JavaScript actions.

"Invalid version" -- Use standard semver format: 1.0.0, not v1.0.0 or 1.0.

"Invalid package.json" -- Check your JSON syntax. A missing comma or bracket is the usual cause.

What's next

After selecting your repository, the dashboard guides you through the remaining setup:

1. Build Your App -- done (completed before reaching this page)
2. Connect GitHub -- done
3. Add Your App -- done
4. Set Up Payouts -- complete payout onboarding
5. Add Support Email -- verify a contact email for subscribers
6. Deploy Your App -- go live

Next step: Set Up Payouts.

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