MCP Server CLI Inspector for Model Context Protocol

Overview

The MCP Server CLI Inspector is a lightweight command-line utility for interacting with servers that implement the Model Context Protocol (MCP). It connects to an MCP-compatible server to enumerate, inspect, stream, and export model contexts and the messages/events associated with them. For developers integrating with LLM systems, the inspector makes it easier to debug context composition, audit message history, and reproduce behaviors by turning live context traces into portable artifacts.

The tool is intended for local development, CI troubleshooting, and incident investigation. It provides quick visibility into context state (active contexts, metadata, and message payloads), supports tailing updates in real time, and can dump entire contexts to JSON/JSONL for downstream analysis or replay.

Features

• Connect to any MCP-compatible server via URL and API token
• List and filter available contexts and sessions
• Inspect single context metadata and full message histories
• Stream (tail) live messages from a context
• Export contexts/messages as JSON or JSONL for audits and replays
• Lightweight CLI suitable for scripts and CI pipelines
• Configurable time ranges, limits, and output formats

Installation / Configuration

Install a prebuilt binary (recommended)

• Download the latest release for your platform from the GitHub Releases page, unpack and move to a directory on your PATH:

# example (Mac/Linux)
curl -L -o mcp-inspect.tar.gz https://github.com/wong2/mcp-cli/releases/latest/download/mcp-inspect-linux-amd64.tar.gz
tar -xzf mcp-inspect.tar.gz
chmod +x mcp-inspect
sudo mv mcp-inspect /usr/local/bin/

Install with Go (if a Go module build is available)

go install github.com/wong2/mcp-cli@latest

Docker (run without installing)

docker run --rm -it ghcr.io/wong2/mcp-cli:latest mcp-inspect --help

Configuration

• The CLI supports a per-user config file (YAML or JSON) and environment variables. Create a configuration at ~/.mcp/config.yaml:

# ~/.mcp/config.yaml
server_url: "https://mcp.example.com"
api_key: "sk-REPLACE_WITH_YOUR_KEY"
timeout_seconds: 15

Or set environment variables:

export MCP_SERVER_URL="https://mcp.example.com"
export MCP_API_KEY="sk-REPLACE_WITH_YOUR_KEY"

Command-line flags override config file and environment variables.

Available Tools / Resources

• CLI executable: mcp-inspect — primary interface for interacting with MCP servers
• Config file: ~/.mcp/config.yaml — persistent connection settings and defaults
• Output formats: json, jsonl, pretty (table/text)
• GitHub repo and release artifacts: https://github.com/wong2/mcp-cli
• MCP protocol spec and server implementations: consult your MCP server documentation for endpoints and authentication details

Common commands (summary table)

Use Cases

1. Debugging context composition

• Problem: The model returns unexpected content and you suspect an earlier message injected an unintended instruction.
• Solution: Inspect the context message history to find the offending message.

mcp-inspect inspect ctx_12345 --format pretty

2. Real-time monitoring of a session

• Problem: Watch messages produced by a session as they arrive during an interactive session.
• Solution: Tail context updates.

mcp-inspect watch ctx_12345 --follow

3. Exporting contexts for replay or auditing

• Problem: Compliance requires retaining conversation histories for analysis.
• Solution: Dump a full context to JSONL and store it in your logs bucket.

mcp-inspect dump ctx_12345 --format jsonl > ctx_12345.jsonl

4. Automated CI checks

• Problem: Validate that a model integration sets expected context metadata during tests.
• Solution: Use the CLI in CI to query a test server and assert on context properties.

mcp-inspect inspect ctx_test_001 --json | jq '.metadata.expected_flag == true'

5. Narrow searches by time or metadata

• Problem: Find contexts created within a specific window or by a particular client.
• Solution: Use filtering flags.

mcp-inspect list --since "2026-04-01T00:00:00Z" --until "2026-04-05T00:00:00Z" --metadata client=webapp-1

Tips

• Use –format json or jsonl when you plan to pipe output into tools like jq, grep, or into storage.
• Combine –limit and –since to paginate or bound large exports.
• Store your API key in environment variables or a protected config file; avoid committing keys to source control.

For more details and the latest commands, consult the repository README and the MCP server documentation in your environment.