mcp-probe

Quality checker for MCP servers. Validates protocol handshake, discovery, optional tool-call dry-runs, and response latency in one command.

The npm audit for the MCP ecosystem — because awesome-mcp-servers lists 200+ servers and there was no way to know if they actually worked.

npx @k08200/mcp-probe @modelcontextprotocol/server-memory

mcp-probe  @modelcontextprotocol/server-memory
────────────────────────────────────────────────────
  ✓  Target resolution
     npx --yes @modelcontextprotocol/server-memory
  ✓  MCP protocol handshake  1392ms
     memory-server v0.6.3
  ✓  Tools discovery  33ms
     Found 9 tools
  ✓  Tool schema validation
     All tool schemas are valid
────────────────────────────────────────────────────
  Server   memory-server v0.6.3
  Caps     tools

  Tools
    ▸ create_entities  Create multiple new entities in the knowledge graph
    ▸ create_relations  Create multiple new relations between entities
    ▸ add_observations  Add new observations to existing entities
    ▸ delete_entities  Delete entities and their associated relations
    ▸ read_graph  Read the entire knowledge graph
    ▸ search_nodes  Search for nodes in the knowledge graph
    ▸ ...and 3 more

  ✓  PASS  1455ms total

---

Install

# No install needed
npx @k08200/mcp-probe <target>

# Or install globally
npm install -g @k08200/mcp-probe

Usage

# Check an npm package
mcp-probe @modelcontextprotocol/server-memory

# Check a server that requires arguments (e.g. directories to serve)
mcp-probe @modelcontextprotocol/server-filesystem /tmp /Users/me/projects

# Check a local server file
mcp-probe ./my-server.js

# JSON output for CI / scripting
mcp-probe @scope/server --output json

# Custom timeout (default: 10000ms)
mcp-probe @scope/server --timeout 30000

# Call tools with generated minimal inputs
mcp-probe @scope/server --probe-tools

# Call tools with real sample inputs from a sidecar file
mcp-probe @scope/server --tools-file .mcp-probe.json

What it checks

Check	Description
Target resolution	Can the package be located and spawned?
MCP protocol handshake	Does the server respond to initialize? Measures connect latency.
Tools discovery	Does tools/list return results? Measures list latency.
Tool schema validation	Are all tool schemas well-formed?
Resources discovery	Runs resources/list when the server advertises resources.
Prompts discovery	Runs prompts/list when the server advertises prompts.
Tool call dry-run	Optional tools/call checks via --probe-tools or --tools-file.

Tool call dry-runs

Discovery proves that a server starts and registers tools. It does not prove that the tools actually work in an agent loop. Use --probe-tools to call every discovered tool.

By default, mcp-probe generates minimal inputs from each tool schema. That catches broken call paths, but real CI gates should prefer a sidecar file with meaningful sample inputs:

{
  "tools": {
    "logs_query": {
      "input": {
        "query": "service:web status:error",
        "timeframe": "1h"
      },
      "expect": {
        "not_error_code": [401, 403]
      }
    }
  }
}

Save this as .mcp-probe.json in your project root and run:

mcp-probe @your-org/datadog-mcp --probe-tools

Or pass an explicit path:

mcp-probe @your-org/datadog-mcp --tools-file ./ci/mcp-tools.json

Sidecar inputs are used first; generated minimal inputs are fallback only. Auth and permission failures such as 401/403 are surfaced as warnings so CI can distinguish "OAuth handoff needed" from transport or runtime failure.

Exit codes

Code	Meaning
0	All checks passed (or warnings only)
1	One or more checks failed

CI integration

# .github/workflows/mcp-probe.yml
- name: Validate MCP server
  run: npx @k08200/mcp-probe @your-org/your-mcp-server
  timeout-minutes: 2

JSON output

mcp-probe @modelcontextprotocol/server-memory --probe-tools --output json

{
  "target": "@modelcontextprotocol/server-memory",
  "timestamp": "2026-05-17T12:00:00.000Z",
  "overallStatus": "pass",
  "checks": [
    { "name": "Target resolution", "status": "pass", "message": "npx --yes @modelcontextprotocol/server-memory" },
    { "name": "MCP protocol handshake", "status": "pass", "message": "memory-server v0.6.3", "latencyMs": 1392 },
    { "name": "Tools discovery", "status": "pass", "message": "Found 9 tools", "latencyMs": 33 },
    { "name": "Tool schema validation", "status": "pass", "message": "All tool schemas are valid" },
    { "name": "Tool call dry-run", "status": "pass", "message": "9 passed (2 sidecar, 7 auto)" }
  ],
  "serverInfo": { "name": "memory-server", "version": "0.6.3", "capabilities": ["tools"] },
  "tools": [{ "name": "create_entities", "description": "Create multiple new entities in the knowledge graph" }],
  "toolCallResults": [
    { "tool": "read_graph", "status": "pass", "latencyMs": 41, "source": "auto" }
  ],
  "totalLatencyMs": 1455
}

Status values

Status	Icon	Meaning
pass	✓	Check succeeded
warn	⚠	Non-fatal issue (e.g. no tools registered)
fail	✗	Check failed — exits with code 1

Roadmap

• HTTP/SSE transport support
• Batch checking from a file (mcp-probe --list servers.txt)
• Badge generation (mcp-probe --badge > badge.json)
• Structured stderr conventions for MCP server authors
• Server-specific recipe examples for Datadog, Supabase, and Gmail MCP servers

Contributing

Issues and PRs are welcome. See CONTRIBUTING.md.

License

MIT