Skip to main content

mcp-halflist

CI-first conformance, security, and benchmarking CLI for MCP servers.

Lint your MCP server before your users do.

CI PyPI License Python

What It Does

Point it at any MCP server (stdio or HTTP) and get a scored conformance report, security vulnerability scan (prompt injection, tool poisoning, data exfiltration), and per-tool latency benchmarks. Fully offline, zero API keys, CI-native. One pip install, one command, done.

See It In Action

Terminal output (halflist audit against the official reference server, -n 3 -w 1):

halflist audit output

HTML reports: Check report · Bench report · Audit report

Install

pip install mcp-halflist

macOS users: use python3 instead of python in server commands.

The npx examples below run the official MCP reference server, which needs Node.js 24 or newer.

halflist itself uses the mcp 2.x SDK. The servers you test can be built with any MCP SDK or language.

Quick Start

# Full audit of the official MCP reference server (benchmarks every tool, so it takes a couple of minutes; add -n 3 -w 1 for a faster run)
halflist audit --stdio "npx -y @modelcontextprotocol/server-everything"

# Security scan + conformance check
halflist check --stdio "npx -y @modelcontextprotocol/server-everything"

# Benchmark tool latency
halflist bench --stdio "npx -y @modelcontextprotocol/server-everything" --all

# Pin tools, then verify later for rug pull detection
halflist pin --stdio "npx -y @modelcontextprotocol/server-everything"
halflist check --stdio "npx -y @modelcontextprotocol/server-everything" --verify-pins

# Your own server
halflist audit --stdio "python3 my_server.py"

# HTTP transport (Streamable HTTP with SSE fallback)
halflist check --http http://localhost:8080/mcp
halflist audit --http http://localhost:8080/mcp

# HTTP with auth
halflist check --http https://mcp.example.com/v1 --header "Authorization: Bearer tok123"

# HTTP with OAuth2 client credentials
halflist audit --http https://mcp.example.com/v1 \
  --oauth-token-url https://auth.example.com/token \
  --oauth-client-id my-client \
  --oauth-client-secret my-secret

# OAuth2 PKCE (automatic on 401, opens browser for authorization)
halflist check --http https://mcp.example.com/v1

# OAuth2 PKCE headless mode (prints URL instead of opening browser)
halflist check --http https://mcp.example.com/v1 --no-browser

# Skip automatic OAuth PKCE
halflist check --http https://mcp.example.com/v1 --no-auth

# Custom tool arguments for tools that need specific inputs
# args.json: {"get_user": {"user_id": "abc123"}}
halflist bench --http http://localhost:8080/mcp --tool get_user --args-file args.json

# More real servers to try
halflist check --stdio "npx -y @modelcontextprotocol/server-time"
halflist check --stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"

CI Integration

JUnit XML output works with GitHub Actions, GitLab CI, Jenkins, and any CI system that supports JUnit test reporters:

# Generate JUnit XML for CI test reporters
halflist check --stdio "python3 server.py" --format junit > results.xml
halflist audit --stdio "python3 server.py" --format junit > audit.xml

Commands

Command What it does
halflist check Protocol conformance + security scanning
halflist bench Per-tool latency benchmarking (p50/p95/p99)
halflist audit Combined check + bench in one shot
halflist watch Continuous health monitoring
halflist report Generate markdown, HTML reports, or SVG badges from JSON
halflist pin Save tool hashes for rug pull detection

See the full command reference for all flags and examples.

Security Scanning

halflist scans tool descriptions for prompt injection, data exfiltration instructions, cross-tool manipulation, suspicious encoding (base64, zero-width characters), and rug pull attempts via tool pinning. All scanning runs locally: zero API calls, zero data sharing. Unlike mcp-scan which sends tool descriptions to an external API, halflist runs entirely on your machine.

See security scanning details for the full list of detection patterns.

Debug Logging

# Enable debug output
halflist check --stdio "python3 server.py" --debug

# Save debug log to file
halflist audit --http https://example.com/mcp --debug-log debug.log

# Environment variable (useful in CI)
HALFLIST_LOG_LEVEL=DEBUG halflist audit --stdio "python3 server.py"

Configuration

Create a halflist.toml in your project root:

[server]
transport = "stdio"
command = "python3 my_server.py"

[check]
timeout = 30

[bench]
iterations = 20
args_file = "args.json"

Then just run:

halflist check
halflist audit

CLI flags override config values. Use ${ENV_VAR} for secrets:

[server.oauth]
client_secret = "${MCP_CLIENT_SECRET}"

Config file discovery order: halflist.toml (cwd) > .halflist.toml (cwd) > ~/.halflist/config.toml. Or pass --config path/to/file.toml explicitly.

Output Formats

Terminal (colored, default) · JSON (--format json) · JUnit XML (--format junit) · Markdown · HTML · SVG Badge

See the output format reference for details.

How It Compares

Tool Approach Needs API key Sends data externally
MCP Inspector Interactive browser UI No No
mcp-probe Interactive TUI (Rust) No No
mcp-server-tester LLM-generated tests Yes (Anthropic) Yes
mcp-scan Security scanning Yes (OpenAI for local) Yes (Invariant API)
mcp-halflist CI-first check + security + bench No No

GitHub Action

Add MCP server testing to your CI in 3 lines:

- uses: abhishekhsingh/halflist-action@v1
  with:
    command: "python3 my_server.py"

See halflist-action for full docs.

Development

git clone https://github.com/abhishekhsingh/mcp-halflist.git
cd mcp-halflist
pip install -e ".[dev]"
ruff check src/ tests/
ruff format --check src/ tests/
pytest -v --tb=short

License

MIT

Author

Abhishekh Singh

Metadata

Release files for mcp-halflist 1.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-halflist 1.1.1
File Size Uploaded Provenance Actions
mcp_halflist-1.1.1.tar.gz 425.1 kB With provenance Details for mcp_halflist-1.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-halflist 1.1.1
File Interpreter ABI Platform Actions
mcp_halflist-1.1.1-py3-none-any.whl Python 3 none any Details for mcp_halflist-1.1.1-py3-none-any.whl

Total release size: 476.5 kB

Release files / mcp_halflist-1.1.1.tar.gz

Download URL mcp_halflist-1.1.1.tar.gz
Size 425.1 kB
Tags Source
SHA-256 checksum
How to use checksums
b4341e7441fefa3fd64609b67c75a0e72be2ff0b7f8e0dc6255a2dc92deb21a8
BLAKE2b-256 checksum
How to use checksums
f4c000ffbd9fd9fee6689a054380c49edecf3f35c11c643aa9939476f197ed70
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / mcp_halflist-1.1.1-py3-none-any.whl

Download URL mcp_halflist-1.1.1-py3-none-any.whl
Size 51.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
86ebcec91149db2d4805e52dfd0efcbd5774413a0cf99658d610f4e5a2ccdc69
BLAKE2b-256 checksum
How to use checksums
d580ef8cdb9e52e24e968ba26b757c7ef6951e6c1ced867e543c27e8a37fa1ec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for mcp-halflist 1.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mcp_halflist-1.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page