Publish from GitHub

This tutorial shows you how to connect a GitHub repository to MCP Hub Platform so that every push or release triggers automatic security analysis and certification. By the end, you will have a fully automated pipeline from git push to certified artifact.

Before You Begin

You need:

• A running MCP Hub Platform instance (see Quick Start)
• A GitHub account with a repository containing an MCP server
• A GitHub personal access token with repo scope

Make sure your GITHUB_TOKEN is configured in the Hub environment:

# In mcp-hub/.env
GITHUB_TOKEN=ghp_your_personal_access_token_here

Step 1: Prepare Your Repository

Your GitHub repository should contain a valid MCP server project. The Hub supports four languages:

The scanner automatically detects the primary language based on the files present. No special configuration file is required in the repository, though you can add an mcp-server.yaml manifest for explicit metadata:

# mcp-server.yaml (optional)
name: my-mcp-server
version: 1.0.0
language: python
description: "A weather data MCP server"
entry_point: src/main.py

Step 2: Add the Repository in MCP Hub

Via the Web Dashboard

1. Open the Hub dashboard at http://localhost:8080
2. Navigate to MCP Servers > Add MCP Server
3. Select Git Repository as the ingestion method
4. Enter your repository URL:

   https://github.com/your-org/my-mcp-server
   

5. Configure the branch to track (default: main)
6. Choose the ingestion trigger:
   • Manual: You trigger certification from the dashboard each time
   • Webhook: GitHub notifies the Hub on every push (recommended)
   • Polling: The Hub checks for new commits at a configurable interval
7. Click Add Repository

Via the CLI

mcp-client push \
  --name my-mcp-server \
  --version 1.0.0 \
  --repo https://github.com/your-org/my-mcp-server \
  --branch main \
  --hub http://localhost:8080

Step 3: Configure Webhook Integration (Recommended)

Webhook integration provides real-time triggers – the Hub receives a notification within seconds of each push. This is the recommended approach for active development.

Automatic Webhook Setup

If your GITHUB_TOKEN has admin:repo_hook permissions, the Hub can create the webhook automatically. On the repository settings page in the Hub dashboard, click Enable Webhook and the Hub will register it with GitHub.

Manual Webhook Setup

If you prefer manual setup or your token does not have hook permissions:

1. Go to your GitHub repository settings
2. Navigate to Webhooks > Add webhook
3. Configure the webhook:

4. Click Add webhook
5. GitHub will send a ping event. Verify it appears in the Hub dashboard under the repository’s webhook history.

Step 4: Configure Polling (Alternative)

If webhooks are not feasible (for example, behind a firewall without external access), you can use polling instead.

On the repository settings page in the Hub dashboard:

1. Set Ingestion Trigger to Polling
2. Configure the poll interval (minimum: 5 minutes, recommended: 15 minutes)
3. Save the configuration

The Hub will check the repository for new commits at the configured interval and trigger certification when changes are detected.

Poll Cycle:
  Hub checks GitHub API for latest commit SHA
      |
      +-- No change? Sleep until next poll cycle.
      |
      +-- New commit? Trigger ingestion and certification.

Step 5: Trigger Your First Build

With Webhooks

Simply push a commit to your tracked branch:

cd /path/to/my-mcp-server
git add .
git commit -m "feat: add weather data endpoint"
git push origin main

Within seconds, the Hub receives the webhook event and starts the certification pipeline.

Manually

From the repository page in the Hub dashboard, click Trigger Certification. Select the branch and commit to analyze.

Step 6: Monitor the Pipeline

Watch the certification progress in the Hub dashboard. The repository page shows:

• Pipeline Status: Current stage (Queued, Analyzing, Scoring, Certified, Failed)
• Commit: The Git commit SHA being analyzed
• Duration: Time elapsed since the pipeline started
• History: Previous certification runs with scores and results

You can also follow the pipeline in the terminal:

# Watch the Hub worker logs for dispatch and completion messages
# Terminal running make dev-worker will show:
#   "received webhook push event for my-mcp-server"
#   "dispatching ANALYZE job for my-mcp-server@abc1234"
#   "received ANALYZE_COMPLETE for my-mcp-server@abc1234"
#   "computed score: 85/100, cert_level: 2"
#   "published certified artifact to registry"

Step 7: Access the Certified Artifact

Once certification completes, the artifact is automatically published to the Registry. End users can download it immediately:

# Pull the latest certified version
mcp-client pull my-mcp-server@latest

# Pull a specific version
mcp-client pull [email protected]

# Run the certified server
mcp-client run [email protected]

Version Tagging

The Hub determines the version number using this precedence:

1. Git tags: If the pushed commit has a semver tag (e.g., v1.2.3), that version is used
2. mcp-server.yaml: If a manifest file exists with a version field, that is used
3. Auto-generated: The Hub generates a version based on the commit SHA (e.g., 0.0.0-abc1234)

For clean version management, use Git tags:

git tag v1.2.0
git push origin v1.2.0

Continuous Certification

With webhook integration, you get continuous certification as part of your development workflow:

Developer pushes code
      |
      v
GitHub sends webhook to Hub
      |
      v
Hub ingests source, dispatches to Scanner
      |
      v
Scanner analyzes, returns results
      |
      v
Hub scores, certifies, publishes to Registry
      |
      v
Certified artifact available for download

Every push produces a new certification. Teams can set policies requiring minimum certification levels, ensuring only properly analyzed code reaches production.

Troubleshooting

Webhook Not Triggering

• Verify the webhook URL is reachable from GitHub (check with curl)
• Check the webhook secret matches between GitHub and the Hub
• Review GitHub’s webhook delivery logs (repository settings > Webhooks > Recent Deliveries)

Repository Not Detected

• Ensure the GITHUB_TOKEN has repo scope
• Verify the repository URL is correct and accessible with the configured token
• Check Hub logs for authentication errors

Analysis Fails

• Confirm the scan-worker container is running (docker compose ps)
• Check that minio-init has completed (required for S3 access)
• Review the scan-worker logs for analysis errors

Next Steps

• Enforce Security Policies – Set minimum certification levels for your organization
• Set Up an Organization – Manage teams and access controls
• Self-Hosted Deployment – Deploy the platform for production use