Examples

Ready-to-run test collections, CI/CD configurations, and end-to-end workflows. Copy, paste, and go.

Quick Start

simple.yaml

3 tests

Minimal collection — the simplest way to test a server. Uses shorthand assertions.

name: Simple Filesystem Tests
server: npx -y @modelcontextprotocol/server-filesystem /tmp

tests:
  - name: List allowed directories
    call: list_allowed_directories
    expect:
      - exists: $.content

  - name: Read a test file
    call: read_file
    with:
      path: /tmp/mcpspec-test.txt
    expect:
      - exists: $.content

  - name: Handle missing file
    call: read_file
    with:
      path: /tmp/nonexistent-file-12345.txt
    expectError: true
mcpspec test examples/collections/simple.yaml

with-environments.yaml

2 tests

Advanced collection with environments, tags, typed assertions, and latency checks.

schemaVersion: "1.0"
name: Environment-Aware Tests
description: Tests that use environment variables

server:
  transport: stdio
  command: npx
  args: ["-y", "@modelcontextprotocol/server-filesystem", "{{baseDir}}"]

environments:
  dev:
    variables:
      baseDir: /tmp
  staging:
    variables:
      baseDir: /var/tmp

defaultEnvironment: dev

tests:
  - id: test-list
    name: List directories
    tags: [smoke]
    call: list_allowed_directories
    assertions:
      - type: schema
      - type: latency
        maxMs: 10000

  - id: test-read
    name: Read test file
    tags: [integration]
    call: read_file
    with:
      path: "{{baseDir}}/mcpspec-test.txt"
    assertions:
      - type: exists
        path: $.content
mcpspec test examples/collections/with-environments.yaml --env dev

Community Server Collections

70 tests across 7 popular MCP servers. Each collection is ready to run with no setup.

Filesystem

12 tests

@modelcontextprotocol/server-filesystem

Read/write files, list directories, search, edit, path traversal security checks.

Show full collection 
mcpspec test examples/collections/servers/filesystem.yaml

Memory

10 tests

@modelcontextprotocol/server-memory

Knowledge graph CRUD: create entities/relations, search, add observations, delete, verify cleanup.

Show full collection 
mcpspec test examples/collections/servers/memory.yaml

Everything

11 tests

@modelcontextprotocol/server-everything

Reference server exercising all protocol features: echo, sum, images, annotations, resource links.

Show full collection 
mcpspec test examples/collections/servers/everything.yaml

Time

10 tests

@modelcontextprotocol/server-time

Time and timezone queries, conversions, and error handling for invalid inputs.

mcpspec test examples/collections/servers/time.yaml

Fetch

7 tests

@modelcontextprotocol/server-fetch

HTTP fetch operations, URL validation, content extraction, and error handling.

mcpspec test examples/collections/servers/fetch.yaml

GitHub

9 tests

@modelcontextprotocol/server-github

GitHub API operations: search repos, list issues, get file contents, user info.

mcpspec test examples/collections/servers/github.yaml

Chrome DevTools

11 tests

chrome-devtools-mcp

Browser automation: navigate, screenshot, evaluate JS, network, console, accessibility.

mcpspec test examples/collections/servers/chrome-devtools.yaml

CI/CD Configurations

GitHub Actions

YAML

Complete workflow with test, audit, and quality gate steps.

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

jobs:
  mcpspec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install -g mcpspec

      - name: Run tests
        run: mcpspec test --ci --reporter junit --output results.xml

      - name: Security audit
        run: mcpspec audit "npx my-server" --mode passive --fail-on high

      - name: Quality gate
        run: mcpspec score "npx my-server" --min-score 80

      - uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: results.xml
mcpspec ci-init --platform github --checks test,audit,score

GitLab CI

YAML

GitLab CI job with JUnit artifact reporting.

mcpspec:
  image: node:22
  stage: test
  script:
    - npm install -g mcpspec
    - mcpspec test --ci --reporter junit --output results.xml
    - mcpspec audit "npx my-server" --mode passive --fail-on high
  artifacts:
    when: always
    paths:
      - results.xml
    reports:
      junit: results.xml
    expire_in: 1 week
mcpspec ci-init --platform gitlab --checks test,audit

Shell Script

Bash

Portable shell script for any CI system or local use.

#!/bin/bash
set -euo pipefail

echo "=== MCPSpec CI ==="

# Run tests
mcpspec test --ci --reporter junit --output results.xml
echo "Tests passed"

# Security audit
mcpspec audit "npx my-server" --mode passive --fail-on high
echo "Audit passed"

# Quality gate
mcpspec score "npx my-server" --min-score 80
echo "Score check passed"

echo "=== All checks passed ==="
mcpspec ci-init --platform shell --checks test,audit,score

End-to-End Workflows

Record, Replay, Mock

Record a session once. Replay it to catch regressions. Mock it for CI. No API keys required.

# 1. Record a session against your real server
mcpspec record start "npx my-server"
# In the REPL:
#   .call get_user {"id": "1"}
#   .call list_items {}
#   .call create_item {"name": "test"}
#   .save my-api

# 2. Replay against a new version — catch regressions
mcpspec record replay my-api "npx my-server-v2"

# 3. Start a mock server (drop-in replacement)
mcpspec mock my-api

# 4. Generate standalone .js file for CI
mcpspec mock my-api --generate ./mocks/server.js

# 5. Use mock in your test suite
mcpspec test --server "node ./mocks/server.js"

CI Gate: Test + Audit + Score

Full quality pipeline: run tests, audit for vulnerabilities, and enforce a minimum quality score.

# 1. Generate CI config with all checks
mcpspec ci-init --platform github \
  --checks test,audit,score \
  --fail-on medium \
  --min-score 80

# 2. Or run manually:

# Run tests with JUnit output
mcpspec test --ci --reporter junit --output results.xml

# Security audit (passive = safe for production)
mcpspec audit "npx my-server" --fail-on medium

# Quality gate with badge generation
mcpspec score "npx my-server" --min-score 80 --badge ./badge.svg

# Performance baseline
mcpspec bench "npx my-server" --iterations 50