Part 4 of the Journey: Advanced Topics & Deep Dives Previous: Rate Limiting Without State | Next: The Router DDoS Blacklist Crisis

The MCP Inspector Deep Dive: Your Only Debugging Friend

How to actually use the MCP Inspector when console.log is forbidden and debugging feels impossible

Date: September 10, 2025 Author: Myron Koch & Claude Code Category: Essential Developer Tools

The Reality Check

You’ve built your MCP server. It compiles. It starts. Claude Desktop shows it as “connected.”

But does it actually work?

Without console.log, without a debugger, without visible output - how do you know?

Enter the MCP Inspector: Your only window into the MCP void.

What IS the MCP Inspector?

It’s a standalone tool that pretends to be Claude, letting you:

• See all your tools
• Test tool calls
• View actual responses
• See errors (finally!)
• Debug without deploying

Think of it as Postman for MCP servers.

Installation and First Run

# Install globally (do this once)
npm install -g @modelcontextprotocol/inspector

# Or use npx (no installation)
npx @modelcontextprotocol/inspector

But here’s the catch - you need to tell it HOW to run your server:

# WRONG - Inspector doesn't know what to run
npx @modelcontextprotocol/inspector

# RIGHT - Tell it exactly what to run
npx @modelcontextprotocol/inspector node dist/index.js

# For TypeScript development
npx @modelcontextprotocol/inspector tsx src/index.ts

# With environment variables
NETWORK=testnet npx @modelcontextprotocol/inspector node dist/index.js

The Sacred Inspector Workflow

Step 1: Start Your Server in Inspector Mode

cd servers/testnet/ethereum-sepolia-mcp-server
npm run build  # Make sure it's built
npx @modelcontextprotocol/inspector node dist/index.js

Step 2: Open the Inspector UI

[2025-01-15 10:30:00] Starting MCP Inspector...
[2025-01-15 10:30:01] Server started successfully
[2025-01-15 10:30:01] Inspector available at: http://localhost:5173

Open that URL! This is your debugging interface.

The UI Breakdown

┌─────────────────────────────────────────────┐
│  MCP Inspector                              │
├─────────────────────────────────────────────┤
│  Connected to: ethereum-sepolia-mcp-server  │
├─────────────────────────────────────────────┤
│  Tools (47)                   │ Tool Test  │
├────────────────────────────────┴────────────┤
│ ▼ Core Tools                               │
│   • eth_get_balance                        │
│   • eth_get_transaction                    │
│   • eth_get_block                          │
│ ▼ Wallet Tools                             │
│   • eth_create_wallet                      │
│   • eth_import_wallet                      │
└─────────────────────────────────────────────┘

Actually Testing a Tool

Click on eth_get_balance. The test panel appears:

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb3"
}

Click “Run Tool” and see:

{
  "content": [{
    "type": "text",
    "text": "{\n  \"address\": \"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb3\",\n  \"balance\": \"1234567890123456789\",\n  \"formatted\": \"1.234 ETH\"\n}"
  }]
}

Success! But more importantly…

When Things Go Wrong (And They Will)

Scenario 1: Tool Not Appearing

Your tool isn’t in the list? Check:

# In the server terminal (not Inspector UI)
[ERROR] Tool registration failed: eth_send_tx
[ERROR] Reason: Handler not found

Fix: Your tool isn’t registered in index.ts:

const toolHandlers: Record<string, Function> = {
  'eth_get_balance': handleEthGetBalance,
  'eth_send_tx': handleEthSendTx,  // ← Add this!
};

Scenario 2: Tool Crashes

Click run, nothing happens? Check stderr in terminal:

[STDERR] TypeError: Cannot read property 'address' of undefined
[STDERR]   at handleEthGetBalance (dist/tools/core/eth-get-balance.js:5:20)

Fix: Your tool isn’t handling missing parameters:

export async function handleEthGetBalance(args: any, client: any) {
  // Add validation!
  if (!args.address) {
    throw new Error('Address is required');
  }
}

Scenario 3: Wrong Response Format

Tool runs but Inspector shows error:

Invalid response format: Expected object with 'content' array

Fix: MCP has a strict response format:

// WRONG
return { balance: '100' };

// RIGHT
return {
  content: [{
    type: 'text',
    text: JSON.stringify({ balance: '100' }, null, 2)
  }]
};

Advanced Inspector Techniques

1. Testing with Different Inputs

The Inspector saves your test inputs. Build a test suite:

// Save these in inspector-tests.json
{
  "eth_get_balance": [
    { "address": "0x0000000000000000000000000000000000000000" },  // Zero address
    { "address": "0xinvalid" },  // Invalid address
    { "address": "vitalik.eth" },  // ENS name
    { }  // Missing address
  ]
}

2. Watching Server Logs

Run Inspector with stderr visible:

# This shows ALL output, including logger output
npx @modelcontextprotocol/inspector node dist/index.js 2>&1 | tee inspector.log

Now you can see your Winston logs!

3. Testing Complex Tools

For tools that need complex input:

// In Inspector, you can paste complex JSON:
{
  "from": "0x123...",
  "to": "0x456...",
  "value": "1000000000000000000",
  "gasPrice": "20000000000",
  "gasLimit": "21000",
  "nonce": 5,
  "data": "0x"
}

4. Environment-Specific Testing

# Test mainnet
NETWORK=mainnet npx @modelcontextprotocol/inspector node dist/index.js

# Test testnet
NETWORK=testnet npx @modelcontextprotocol/inspector node dist/index.js

# Test with specific RPC
ETH_RPC_URL=https://my.rpc.url npx @modelcontextprotocol/inspector node dist/index.js

The Inspector-Driven Development Workflow

We discovered this pattern that speeds up development 10x:

# Terminal 1: Auto-rebuild on changes
npm run dev  # or: npx tsx watch src/index.ts

# Terminal 2: Inspector
npx @modelcontextprotocol/inspector node dist/index.js

# Terminal 3: File watcher to restart Inspector
nodemon --watch dist --exec "pkill -f inspector; npx @modelcontextprotocol/inspector node dist/index.js"

Now: Edit code → Auto-compile → Inspector restarts → Test immediately

Common Inspector Gotchas

1. “Server failed to start”

# Check if your build is fresh
npm run build

# Check if port is in use
lsof -i :5173  # Inspector's default port

2. “No tools available”

Your server started but didn’t register tools. Check:

• Tools are exported correctly
• Handler functions exist
• No circular dependencies

3. “Timeout waiting for response”

Tool takes too long. Inspector timeout is 30s. Either:

• Optimize your tool
• Add progress messages
• Increase timeout in inspector

4. “Connection refused”

Inspector can’t connect to server:

# Make sure server actually starts
node dist/index.js  # Should NOT exit immediately

Inspector vs Claude Desktop

Use Inspector for development, Claude Desktop for final testing.

The Power Features Nobody Knows

1. Export Tool Definitions

Inspector can export your tool definitions as OpenAPI:

# In Inspector UI, click "Export" → "OpenAPI Spec"
# Generates complete API documentation!

2. Batch Testing

Test multiple tools in sequence:

// Click "Batch Mode" in Inspector
[
  { tool: "eth_get_balance", args: { address: "0x1" } },
  { tool: "eth_get_transaction", args: { hash: "0x2" } },
  { tool: "eth_get_block", args: { number: "latest" } }
]

3. Response Validation

Inspector validates MCP response format automatically:

• ✅ Green: Valid MCP response
• 🟡 Yellow: Valid but warnings
• ❌ Red: Invalid format

The Debugging Checklist

When a tool doesn’t work:

1. Does it appear in Inspector’s tool list?
2. Does clicking it show correct input schema?
3. Does running with valid input return a response?
4. Is the response in correct MCP format?
5. Do errors appear in server terminal?
6. Does it work with edge cases?
7. Does it handle missing parameters?
8. Does it work with maximum values?
9. Does response JSON parse correctly?
10. Does it work in Claude Desktop too?

The Ultimate Inspector Script

Add to every package.json:

{
  "scripts": {
    "inspect": "npm run build && npx @modelcontextprotocol/inspector node dist/index.js",
    "inspect:dev": "npx @modelcontextprotocol/inspector tsx src/index.ts",
    "inspect:mainnet": "NETWORK=mainnet npm run inspect",
    "inspect:testnet": "NETWORK=testnet npm run inspect",
    "inspect:watch": "nodemon --watch src --exec 'npm run inspect:dev'"
  }
}

Now just: npm run inspect:dev

The Reality

Without MCP Inspector, you’re coding blind. With it, you have:

• Immediate feedback
• Error visibility
• Rapid testing
• Confidence your tools work

MCP Inspector isn’t optional. It’s essential.

Master it, and MCP development becomes possible. Ignore it, and you’re debugging in the dark.

References

• Official docs: https://modelcontextprotocol.io/tools/inspector
• Our test suites: /tests/inspector-scenarios/
• Helper scripts: /scripts/inspector-helpers.sh

This is part of our ongoing series documenting architectural patterns and insights from building the Blockchain MCP Server Ecosystem. The Inspector is your lifeline. Treat it with respect.

Related Reading

Prerequisites

• Rate Limiting Without State: The MCP Paradox - Understand the stateless nature of MCP servers, which makes a tool like the Inspector necessary.

Next Steps

• The Router DDoS Blacklist Crisis - See how the Inspector could have helped diagnose a complex network issue faster.

Deep Dives

• The Logger Revolution: Why console.log Will Kill Your MCP Server - The Inspector is where you’ll see the output from the logging system described in this post.
• Error Handling in MCP: Where Do Errors Actually Go? - The Inspector is the primary way to view the well-structured errors you create.