MCPgee
MCPgee
MCPgeeMCPgee

MCP Assert

v1.0.0•Developer Tools•stable

The deterministic testing standard for MCP servers. Connect over real stdio/SSE/HTTP transport, call tools with real arguments, assert results with 18 assertion types defined in YAML. Any language, any transport, no mocks. Single Go binary.

ai-agentsassertionsbuncideveloper-tools
Share:
8
Stars
0
Downloads
0
Weekly
0/5
View on GitHub

What is MCP Assert?

MCP Assert is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to deterministic testing standard for mcp servers. connect over real stdio/sse/http transport, call tools with real arguments, assert results with 18 assertion types defined in yaml. any language, any tr...

The deterministic testing standard for MCP servers. Connect over real stdio/SSE/HTTP transport, call tools with real arguments, assert results with 18 assertion types defined in YAML. Any language, any transport, no mocks. Single Go binary.

This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.

Features

  • The deterministic testing standard for MCP servers. Connect

Use Cases

Deterministic MCP testing
YAML-based assertion framework
blackwell-systems

Maintainer

LicenseMIT
Languagego
Versionv1.0.0
UpdatedMay 22, 2026
Statushealthy
Maintenanceactive

Works with

ClaudeOpenAIwindowsmacoslinux
View SourceBrowse All Servers

Installation

Manual Installation

npx mcp-assert

Configuration

Configuration Details

Config File

claude_desktop_config.json

Performance

Response Metrics

Response Time< 200ms
ThroughputMedium

Resource Usage

Memory UsageLow
CPU UsageLow

How to Set Up and Use MCP Assert

MCP Assert is a deterministic testing framework for MCP servers that connects over real stdio, SSE, or HTTP transport and executes YAML-defined test suites without mocks. It ships as a single Go binary with commands for auditing, fuzzing, snapshot regression, CI integration, and lint — covering 18 assertion types across any language or runtime.

Prerequisites

  • An MCP server running over stdio, SSE, or HTTP that you want to test
  • One of: Go 1.22+, Node.js (for npx), pip (Python), Homebrew, or Docker
  • A test suite directory (e.g. evals/) with YAML assertion files
  • Optional: GitHub Actions or another CI system for automated test runs
1

Install mcp-assert

Choose the installation method that fits your environment. The npm route requires no Go toolchain and works in most CI images. Go install produces a native binary. Homebrew and Docker are also available.

# npm (no Go required)
npx @blackwell-systems/mcp-assert --version

# Go
go install github.com/blackwell-systems/mcp-assert/cmd/mcp-assert@latest

# Homebrew
brew install blackwell-systems/tap/mcp-assert

# Docker
docker run blackwellsystems/mcp-assert --version

# curl installer (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/blackwell-systems/mcp-assert/main/install.sh | sh
2

Audit your MCP server

Run the audit command against your server to classify every exposed tool as healthy, crashed, or timed out. This is the quickest way to verify a server starts and responds correctly before writing assertions.

# Audit a stdio server
mcp-assert audit --server "npx my-mcp-server"

# Audit an HTTP/SSE server
mcp-assert audit --server "http://localhost:3000/sse"
3

Generate an initial test suite

The init command introspects your server via tools/list, captures response snapshots, and writes a YAML test suite ready for editing. Run it once to scaffold assertions for every tool automatically.

mcp-assert init --server "npx my-mcp-server" --output evals/
4

Write YAML assertions

Edit the generated YAML files in evals/ to add meaningful assertions. Each test case specifies a tool name, input arguments, and an assertions block using one of the 18 available assertion types such as equals, contains, json_path, schema, and status.

# evals/my_tool_test.yaml
server:
  command: npx my-mcp-server

tests:
  - name: "returns greeting"
    tool: greet
    arguments:
      name: "World"
    assertions:
      - type: contains
        path: "content[0].text"
        value: "Hello, World"
      - type: status
        value: success
5

Run assertions and integrate with CI

Use 'mcp-assert run' for local development and 'mcp-assert ci' for automated pipelines. The ci command supports pass-rate thresholds, baseline comparisons, and JUnit XML output for test result reporting.

# Local run
mcp-assert run --suite evals/

# CI run with threshold and JUnit output
mcp-assert ci --suite evals/ --threshold 95 --junit results.xml

# GitHub Actions
# - uses: blackwell-systems/mcp-assert-action@v1
#   with:
#     suite: evals/
#     threshold: 95
6

Fuzz and lint your server

The fuzz command sends adversarial inputs to every tool to detect crashes and hangs. The lint command applies 24 static analysis rules to tool schemas and can auto-fix common issues with --fix.

# Fuzz all tools
mcp-assert fuzz --server "npx my-mcp-server"

# Lint tool schemas
mcp-assert lint --server "npx my-mcp-server"

# Auto-fix lint issues
mcp-assert lint --server "npx my-mcp-server" --fix

MCP Assert Examples

Client configuration

GitHub Actions workflow step using the official mcp-assert action with a 95% pass-rate threshold.

{
  "name": "Test MCP server",
  "uses": "blackwell-systems/mcp-assert-action@v1",
  "with": {
    "suite": "evals/",
    "threshold": "95"
  }
}

Prompts to try

Commands to explore mcp-assert capabilities from the terminal.

- "mcp-assert audit --server 'npx @my-org/my-mcp-server' to quickly check all tools are healthy"
- "mcp-assert coverage --suite evals/ to see which tools lack test coverage"
- "mcp-assert watch --suite evals/ --server 'npx my-mcp-server' to re-run tests on file changes"

Troubleshooting MCP Assert

mcp-assert audit hangs indefinitely when connecting to a stdio server

Ensure the server command starts successfully on its own and writes the MCP handshake JSON to stdout within 10 seconds. Add --timeout 30s to increase the connection timeout. Check that the server does not write non-JSON startup messages to stdout.

YAML assertions fail with 'path not found' errors

Use 'mcp-assert snapshot --server ...' to capture an actual response and inspect the real JSON structure. Update the path in your assertion to match the actual response shape from your server.

CI step exits non-zero even though most tests pass

The --threshold flag defaults to 100. Lower it (e.g. --threshold 90) or fix the failing assertions. Use --junit results.xml and inspect the XML report to identify which specific test cases are failing.

Frequently Asked Questions about MCP Assert

What is MCP Assert?

MCP Assert is a Model Context Protocol (MCP) server that deterministic testing standard for mcp servers. connect over real stdio/sse/http transport, call tools with real arguments, assert results with 18 assertion types defined in yaml. any language, any transport, no mocks. single go binary. It connects AI assistants to external tools and data sources through a standardized interface.

How do I install MCP Assert?

Follow the installation instructions on the MCP Assert GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.

Which AI clients work with MCP Assert?

MCP Assert works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.

Is MCP Assert free to use?

Yes, MCP Assert is open source and available under the MIT license. You can use it freely in both personal and commercial projects.

Learn More About MCP Servers

Getting Started with MCP

Set up your first MCP server in minutes

MCP Setup Guide

Configure MCP in Claude, Cursor & VS Code

All MCP Tutorials

18+ hands-on guides for developers

MCP FAQ

40+ answers about Model Context Protocol

MCP Assert Alternatives — Similar Developer Tools Servers

Looking for alternatives to MCP Assert? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.

Ecc

★ 188.2k

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

Javaguide

★ 155.8k

Java 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发

Gemini CLI

★ 104.5k

A secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in

Awesome MCP Servers

★ 87.3k

⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.

MCP Servers

★ 86.0k

Model Context Protocol Servers

CC Switch

★ 77.5k

A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io

Browse More Developer Tools MCP Servers

Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.

Developer ToolsBrowse All Servers

Quick Config Preview

{ "mcpServers": { "mcp-assert": { "command": "npx", "args": ["-y", "mcp-assert"] } } }

Add this to your claude_desktop_config.json or .cursor/mcp.json

Read the full setup guide →

Ready to use MCP Assert?

Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.

33,000+ ServersFree & Open SourceStep-by-Step Guides
Explore All ServersRead Our Guides