McpLense 0.1.0

McpLense

McpLense is a .NET tool for debugging Model Context Protocol (MCP) servers.

It can:

• inspect one or many servers in a single run
• browse them in an interactive TUI
• list tools, resources, prompts, and resource templates
• call tools, read resources, and resolve prompts
• connect from a config file, an HTTP/SSE URL, or a stdio command
• emit output as text, json, or dumpify
• show live progress for tool calls when servers emit progress notifications

Install

From NuGet:

dotnet tool install --global McpLense

From a local package while developing:

dotnet pack src/McpLense -c Release
dotnet tool install --global --add-source ./src/McpLense/bin/Release McpLense

Quick start

# Inspect a public remote MCP server (context7) over streamable-http
mcplense inspect --url https://mcp.context7.com/mcp

# List its tools as JSON
mcplense tools --url https://mcp.context7.com/mcp --format json

# Open the TUI against an mcp.json config
mcplense tui --config mcp.json

Commands

mcplense inspect
mcplense tui
mcplense tools
mcplense resources
mcplense prompts
mcplense call <tool-name>
mcplense read <uri-or-template>
mcplense prompt <prompt-name>

Targets

You can point mcplense at a server in three different ways: a config file, a URL, or a stdio command.

Config file

Works with the common mcpServers shape:

{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"]
    },
    "remote": {
      "url": "https://example.com/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

It also supports a custom servers array:

{
  "servers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"],
      "cwd": ".",
      "env": {
        "NODE_ENV": "development"
      }
    }
  ]
}

URL

mcplense inspect --url https://localhost:3000/mcp
mcplense inspect --url https://localhost:3000/mcp --transport streamable-http
mcplense inspect --url https://localhost:3000/sse --transport sse
mcplense inspect --url https://localhost:3000/mcp --header Authorization="Bearer token"

Stdio command

mcplense inspect --command npx --command-arg -y --command-arg @modelcontextprotocol/server-everything

Or use -- to pass the server command through directly:

mcplense inspect -- npx -y @modelcontextprotocol/server-everything

Transports

--transport selects how mcplense talks to a URL-based MCP server.

--transport is ignored for stdio targets and config-file entries that already declare their transport.

Remote MCP servers

mcplense can talk to any publicly reachable MCP server over HTTPS. For example, the context7 public MCP endpoint:

# auto-detect transport
mcplense inspect --url https://mcp.context7.com/mcp --format json

# call resolve-library-id
mcplense call resolve-library-id \
  --url https://mcp.context7.com/mcp \
  --args '{"libraryName":"spectre.console"}'

Headers and authentication

Pass --header NAME=VALUE once per header. Quoting differs by shell:

PowerShell (Windows / pwsh):

$env:CTX7_TOKEN = "your-token-here"
mcplense inspect --url https://mcp.context7.com/mcp `
  --header "Authorization=Bearer $env:CTX7_TOKEN"

bash / zsh:

export CTX7_TOKEN=your-token-here
mcplense inspect --url https://mcp.context7.com/mcp \
  --header "Authorization=Bearer $CTX7_TOKEN"

In a config file, headers go under the server entry:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer ${CTX7_TOKEN}"
      }
    }
  }
}

Environment variable expansion in config values is not done by mcplense; substitute before invocation, or pass headers via --header.

Examples

Inspect all servers in a config:

mcplense inspect --config mcp.json

Open the interactive TUI:

mcplense tui --config mcp.json

Inspect one server from a config:

mcplense inspect --config mcp.json --server everything

List tools as JSON:

mcplense tools --config mcp.json --server everything --format json

List tools as Dumpify text:

mcplense tools --config mcp.json --server everything --format dumpify

Call a tool:

mcplense call echo --config mcp.json --server everything --args '{"message":"hello"}'

Call a tool and show progress events:

mcplense call trigger-long-running-operation --args '{"duration":5,"steps":5}' -- npx -y @modelcontextprotocol/server-everything

Read a resource template:

mcplense read docs://articles/{id} --config mcp.json --server docs --args '{"id":"getting-started"}'

Resolve a prompt:

mcplense prompt code_review --url https://localhost:3000/mcp --args '{"language":"csharp","code":"Console.WriteLine(1);"}'

Use Dumpify output:

mcplense inspect --config mcp.json --format dumpify

dotnet run examples

Run from the repo root using --project src/McpLense, or cd into src/McpLense first.

Inspect a stdio MCP server and keep text output:

dotnet run --project src/McpLense -- inspect -- npx -y @modelcontextprotocol/server-everything

Inspect the same server as JSON:

dotnet run --project src/McpLense -- inspect --format json -- npx -y @modelcontextprotocol/server-everything

Inspect the same server with Dumpify output:

dotnet run --project src/McpLense -- inspect --format dumpify -- npx -y @modelcontextprotocol/server-everything

View only tools:

dotnet run --project src/McpLense -- tools --format json -- npx -y @modelcontextprotocol/server-everything

Open the TUI directly:

dotnet run --project src/McpLense -- tui -- npx -y @modelcontextprotocol/server-everything

If you have a config file instead:

dotnet run --project src/McpLense -- inspect --config mcp.json --server everything --format json

Notes

• inspect, tools, resources, and prompts can run against multiple config servers at once.
• call, read, and prompt require exactly one selected server.
• call enables live progress output by default; use --progress false to disable it.
• Exit code is non-zero if any requested server fails or if a tool call reports isError: true.

Project layout

McpLense/
├─ src/
│  ├─ McpLense.slnx                 # Solution (XML format)
│  └─ McpLense/                     # CLI / TUI / MCP integration
│     ├─ Cli/                       # Argument parsing
│     ├─ Tui/                       # Spectre.Console TUI
│     ├─ Mcp/                       # Executor + target resolver
│     ├─ Output/                    # text / json / dumpify renderers
│     └─ Models/                    # Reports, parsed commands, options
├─ tests/
│  ├─ McpLense.UnitTests/           # In-process unit tests (no I/O)
│  ├─ McpLense.IntegrationTests/    # Real stdio + in-process HTTP MCP server
│  ├─ McpLense.E2ETests/            # Subprocess CLI tests + public MCP smoke
│  ├─ McpLense.TestServer/          # Stdio MCP test server
│  ├─ McpLense.TestServer.Shared/   # Tools/resources/prompts shared by both
│  └─ McpLense.TestHttpServer/      # HTTP/SSE MCP test server
├─ Directory.Build.props
├─ Directory.Packages.props         # Central package management
├─ NuGet.config                     # Pinned to nuget.org
├─ global.json                      # Pinned .NET SDK
├─ coverlet.runsettings             # Coverage settings
└─ .github/workflows/ci.yml         # Build + test + coverage matrix

Contributing

Build and test locally:

dotnet build src/McpLense.slnx -c Release
dotnet test  src/McpLense.slnx -c Release

The McpLense.E2ETests project includes optional smoke tests that hit a public remote MCP server (currently context7). They are skipped by default. To enable them:

PowerShell:

$env:MCPLENSE_PUBLIC_SMOKE = "1"
dotnet test src/McpLense.slnx -c Release --filter "FullyQualifiedName~PublicMcpSmokeTests"

bash:

MCPLENSE_PUBLIC_SMOKE=1 dotnet test src/McpLense.slnx -c Release \
  --filter "FullyQualifiedName~PublicMcpSmokeTests"

Coverage is collected via coverlet.runsettings and rendered as an HTML report on Linux CI runs (uploaded as the coverage-report-html artifact, with a Markdown summary in the GitHub Actions job summary).

License

Unlicense.