How to Validate Your MCP Servers in GitHub Actions CI

#mcp #github #ci #python

Integrating Model Context Protocol (MCP) servers into your LLM workflows is a great way to give models like Claude or GPT access to custom tools and databases. But as your server grows, keeping its tool definitions, JSON schemas, and error handling bug-free becomes a challenge. A single broken inputSchema can crash your LLM agent or trap it in an expensive corrective loop.

In this tutorial, we will show you how to set up automated validation for your MCP servers on every commit or pull request using the open-source CLI tool mcp-lint and GitHub Actions.

The Open-Source Workflow

To validate your schemas and code statically, you can use mcp-lint. It checks for missing properties, shell injection risks, raw exceptions, and insufficient docstrings.

First, add a workflow file to your repository at .github/workflows/mcp-lint.yml:

name: MCP Linting
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: |
          pip install mcp-lint

      - name: Run static linter
        run: |
          mcp-lint . --min-score 80 --format json --output lint-report.json

This workflow installs the linter, scans the directory, and fails the build if the server quality score drops below 80.

Running Runtime Validation (Pro)

Statically checking your source code is a great start, but it does not guarantee your server will run successfully. To verify JSON-RPC 2.0 conformance and run health checks, you can upgrade to the Pro version.

Here is how to set up live integration tests, health checks, and latency profiling in your CI pipeline.

Step 1: Create a Test Definition

Create a mcp-lint-tests.yaml file in your repository. This file defines the test inputs and expected latency limits for your tools:

tests:
  - tool: get_user_records
    input:
      user_id: "usr_992"
    expect:
      schema_valid: true
      max_latency_ms: 1000

Step 2: Add Pro Commands to GitHub Actions

To run runtime validation in CI, configure your license key as a GitHub secret (MCP_LINT_KEY). Then, update your workflow to run the checks:

name: MCP Server Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install mcp-lint

      - name: Activate Pro Features
        run: |
          mcp-lint --pro activate --key ${{ secrets.MCP_LINT_KEY }}

      - name: Run health check
        run: |
          mcp-lint health-check ./my_server.py --timeout 10

      - name: Run schema and tool testing
        run: |
          mcp-lint test ./my_server.py