CI/CD for MCP Servers

An MCP server that works in development can break in production in subtle ways: a tool’s Zod schema changes and clients that cached the old schema break; a new tool is added and existing clients need to discover it; a bug fix changes a tool’s output format and downstream agents that parse it stop working. This lesson covers the testing strategy, versioning approach, and CI/CD pipeline that makes MCP server deployments safe and repeatable.

Testing Strategy for MCP Servers

Unit Tests: Tool Handlers in Isolation

// test/tools/search-products.test.js
import { test, describe, mock } from 'node:test';
import assert from 'node:assert';
import { searchProductsHandler } from '../../tools/search-products.js';

describe('searchProductsHandler', () => {
  test('returns products matching query', async () => {
    const mockDb = {
      query: mock.fn(async () => ({ rows: [{ id: 1, name: 'Laptop X1', price: 999 }] })),
    };

    const result = await searchProductsHandler({ query: 'laptop', limit: 10 }, { db: mockDb });

    assert.ok(!result.isError);
    assert.ok(result.content[0].text.includes('Laptop X1'));
    assert.strictEqual(mockDb.query.mock.calls.length, 1);
  });

  test('returns error on empty query', async () => {
    const result = await searchProductsHandler({ query: '', limit: 10 }, {});
    assert.ok(result.isError);
  });
});

Integration Tests: Full MCP Client-Server Round Trip

// test/integration/mcp-server.test.js
import { test, describe, before, after } from 'node:test';
import assert from 'node:assert';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

let client;
let transport;

before(async () => {
  transport = new StdioClientTransport({
    command: 'node',
    args: ['src/server.js'],
    env: { ...process.env, DATABASE_URL: process.env.TEST_DATABASE_URL },
  });
  client = new Client({ name: 'test-client', version: '1.0.0' });
  await client.connect(transport);
});

after(async () => {
  await client.close();
});

describe('MCP server integration', () => {
  test('lists expected tools', async () => {
    const { tools } = await client.listTools();
    const toolNames = tools.map(t => t.name);
    assert.ok(toolNames.includes('search_products'), 'search_products tool missing');
    assert.ok(toolNames.includes('get_product'), 'get_product tool missing');
  });

  test('search_products returns results', async () => {
    const result = await client.callTool({
      name: 'search_products',
      arguments: { query: 'laptop', limit: 5 },
    });
    assert.ok(!result.isError);
    const parsed = JSON.parse(result.content[0].text);
    assert.ok(Array.isArray(parsed));
  });

  test('get_product returns 404 error for unknown id', async () => {
    const result = await client.callTool({
      name: 'get_product',
      arguments: { id: 'nonexistent-99999' },
    });
    assert.ok(result.isError);
    assert.ok(result.content[0].text.includes('not found'));
  });
});

Protocol Versioning

// server.js - declare server version in metadata
const server = new McpServer({
  name: 'product-server',
  version: process.env.npm_package_version ?? '1.0.0',
});

// Add a version resource so clients can check compatibility
server.resource('server://version', 'application/json', async () => ({
  contents: [{
    uri: 'server://version',
    mimeType: 'application/json',
    text: JSON.stringify({
      serverVersion: process.env.npm_package_version,
      mcpProtocolVersion: '2025-11-05',
      minimumClientVersion: '1.0.0',
      breaking_changes: [],
    }),
  }],
}));

GitHub Actions CI Pipeline

name: MCP Server CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_DB: mcp_test
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: testpass
        ports:
          - 5432:5432
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - run: npm ci
      - run: npm test
        env:
          TEST_DATABASE_URL: postgresql://postgres:testpass@localhost:5432/mcp_test

  build-and-push:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v5
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }},ghcr.io/${{ github.repository }}:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max

  deploy:
    needs: build-and-push
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to production
        run: |
          ssh deploy@production "
            docker pull ghcr.io/${{ github.repository }}:${{ github.sha }} &&
            docker service update --image ghcr.io/${{ github.repository }}:${{ github.sha }} mcp-product-server
          "

Zero-Downtime Deployment with Docker Swarm

# Rolling update: replace instances one at a time, wait for health checks
docker service update \
  --image ghcr.io/myorg/mcp-product-server:v1.3.0 \
  --update-parallelism 1 \
  --update-delay 10s \
  --update-failure-action rollback \
  --health-cmd "wget -qO- http://localhost:3000/health || exit 1" \
  --health-interval 10s \
  --health-retries 3 \
  mcp-product-server

What to Build Next

• Write integration tests for your top 3 most-used tools using the client-server pattern above. Run them with node --test.
• Add the GitHub Actions pipeline from this lesson to your MCP server repo. Verify that a failing test blocks the build.

nJoy 😉