MCP Inspector: Debugging Your MCP Servers Made Easy

Learn how to use the MCP Inspector to test, debug, and interact with your MCP servers. This beginner-friendly guide includes step-by-step instructions, practical examples, and troubleshooting tips.

1. Introduction

Welcome to the fourth installment in our Model Context Protocol (MCP) series! So far, we’ve covered:

1. Getting Started with Model Context Protocol – An introduction to MCP concepts
2. Building MCP Servers with Spring Boot AI – How to implement MCP servers
3. Building MCP Clients with Spring AI – How to create MCP clients and integrate MCP servers in client applications

Today, we’re diving into an essential tool for MCP developers: The MCP Inspector. Whether you’re just getting started with MCP or you’ve been following our series, the Inspector will become your new best friend for testing and debugging MCP servers.

2. What is the MCP Inspector?

The MCP Inspector is a developer tool specifically designed for testing and debugging Model Context Protocol servers. Think of it as your Swiss Army knife for working with MCP servers – it allows you to:

• Send requests to your MCP servers
• View server responses
• Debug issues in your MCP implementation

It offers a visual interface (UI) that lets you test, debug, and explore your servers without needing to write complex client code or custom scripts for every test.

3. Why Use the MCP Inspector?

Before diving into how to use the Inspector, let’s understand why it’s valuable:

1. Test Easily: Run server functions right from the UI—no need to write extra code.
2. Debug Faster: View request and response details to quickly find issues.
3. Explore the Server: See what features or “tools” the server offers.
4. Speed Up Development: Try out changes instantly as you build.
5. Check Standards: Make sure your server follows the MCP protocol correctly.

4. Getting Started with MCP Inspector

Now that you’re ready to dive in, let’s look at how to launch MCP Inspector, run it with server arguments or environment variables, and start interacting with your server through the UI.

4.1. Prerequisites

• Node.js: Ensure you have Node.js installed (version ^22.7.5 or later recommended). Check with node -v.
• An MCP server to test. We’ll be using both the Filesystem MCP server and our custom Spring Boot AI MongoDB MCP server)

4.2. Installation

There’s no need to install MCP Inspector permanently. Instead, you can use npx to run it directly. This approach ensures you always have the latest version.

4.3. Basic Launch Command

The core idea is to run the Inspector, telling it how to start your MCP server:

npx @modelcontextprotocol/inspector <command_to_start_your_server> <arg1> <arg2>

This command does two things:

• Launches the Inspector’s backend proxy (usually on port 6277) and frontend UI.
• Starts your MCP server process.

Accessing the UI: Once launched, open your web browser and navigate to http://127.0.0.1:6274 (unless you customize the port). This is where you’ll interact with the Inspector.

4.4. Running MCP Inspector with Arguments and Environment Variables

You can pass both arguments and environment variables to your MCP server:

✅  Passing arguments only:

Use this format to pass arguments directly to your MCP server.

npx @modelcontextprotocol/inspector <command_to_start_your_server> <arg1> <arg2>

✅  Passing environment variables only:

Use the -e flag to pass environment variables to your MCP server.

npx @modelcontextprotocol/inspector -e key=value -e key2=$VALUE2 <command_to_start_your_server>

✅  Passing both:

Combine environment variables and arguments to fully configure your MCP server at startup.

npx @modelcontextprotocol/inspector -e key=value -e key2=$VALUE2 <command_to_start_your_server> <arg1> <arg2>

✅  Using -- to separate inspector flags from server arguments:

Use — to clearly separate Inspector-specific options from server-specific flags and arguments.

npx @modelcontextprotocol/inspector -e key=value -- <command_to_start_your_server> -e server-flag

5. Understanding MCP Inspector Components

When you run MCP Inspector, it launches two components:

1. MCP Inspector (MCPI) client UI – Default port: 6274
   • The web interface where you interact with your MCP server
2. MCP Proxy (MCPP) server – Default port: 6277
   • Acts as an intermediary between your UI and the actual MCP server

These port numbers are derived from the T9 dialpad mapping of MCPI and MCPP, making them easy to remember.

✅  If you need to customize these ports:

CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector <command_to_start_your_server>

👉 Here, CLIENT_PORT=8080 means the UI will be available on port 8080, and SERVER_PORT=9000 means the proxy server will run on port 9000.

6. Working with Configuration Files

For more complex setups or when working with multiple MCP servers, MCP Inspector supports configuration files. This is especially helpful when you want to store and switch between different server configurations easily.

To use a configuration file:

npx @modelcontextprotocol/inspector --config path/to/config.json --server <server-name>

👉 Important Notes:

• It is mandatory to pass the --server <server-name> flag when using a configuration file.
• Only one server can be specified at a time using the --server flag.
• The server-name should match one of the keys defined in your configuration file (like filesystem or spring-boot-ai-mongo-mcp-server in the example below).

Here’s an example configuration file:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/bunty/mcp-demo"
      ]
    },
    "spring-boot-ai-mongo-mcp-server": {
      "command": "java",
      "args": [
        "-jar",
        "/Users/bunty/mcp-demo/spring-boot-ai-mongo-mcp-server-0.0.1-SNAPSHOT.jar"
      ],
      "env": {
        "MONGO_HOST": "localhost",
        "MONGO_PORT": "27017"
      }
    }
  }
}

In this example, we’ve defined two server configurations:

• A Filesystem MCP server
• Our Spring Boot AI MongoDB MCP server

7. Exploring the MCP Inspector UI

Once you’ve started the inspector, open your browser and navigate to the UI (typically at http://localhost:6274). Let’s explore the key features:

7.1. Connection Setup

The left panel of the UI allows you to configure how to connect to your MCP server:

1. Transport Type: Select the transport mechanism (STDIO is the default)
2. Command: Enter the command to run (e.g., npx / node / java / uvx)
3. Arguments: Specify the command-line arguments
4. Environment Variables: Set environment variables for your server
5. Configuration: Access advanced configuration options

After configuring these settings, click the “Connect” button to establish a connection to your MCP server.

Connection Setup – MCP Inspector

7.2. Main Interface Tabs

After connecting, you’ll see several tabs in the main interface:

1. Resources: Browse and explore all available resources on the MCP server. View metadata such as MIME types and descriptions, inspect resource content, and test subscriptions for dynamic resources
2. Prompts: Work with available prompt templates. View their arguments and descriptions, test them with custom inputs, and preview the generated messages for quick iteration and debugging
3. Tools: Interact with the tools provided by your MCP server
4. Ping: Check if your server is responsive
5. Sampling: When the server triggers an LLM sampling request, it will appear here for your review and approval
6. Roots: Configuring root directories that servers can access

Main Interface Tabs – MCP Inspector

7.3. Ping Functionality

The Ping tab allows you to check if your MCP server is responsive:

1. Navigate to the “Ping” tab
2. Click the “Ping Server” button
3. If successful, you’ll receive some response (can be empty) that can be viewed in the History section
4. If unsuccessful, you’ll see an error message or a timeout

This feature is particularly useful when troubleshooting connectivity issues or verifying server health.

Ping Functionality – MCP Inspector

7.4. History and Server Notifications

The bottom section of the UI displays:

1. History: A chronological log of all your interactions with the server
   • Each entry includes the request and response
   • You can expand entries to see detailed information
   • This helps you track what you’ve done and debug issues
2. Server Notifications: Notifications from the server
   • Presents all logs recorded from the server
   • Shows notifications received from the server

History and Server Notifications – MCP Inspector

7.5. Using the Tools Tab

The Tools tab is particularly useful for testing server functionality:

1. Click on the “Tools” tab
2. Click on “List Tools” button
3. You’ll see a list of available tools on the left > select a tool to view its details
4. Provide input if required
5. Click “Run Tool” to execute
6. Verify the output

Using the Tools Tab – MCP Inspector

8. Practical Example: Testing the Filesystem MCP Server

Let’s walk through a practical example using the Filesystem MCP server:

Step 1: Start the Inspector:

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /Users/bunty/mcp-demo

This command launches the MCP Inspector and starts the Filesystem server pointing to your specified directory.

Step 2: Connect to the Server:

• Open http://127.0.0.1:6274 in your browser and click the “Connect” button.
• Since we already specified the server configuration while starting MCP Inspector, no additional configuration is needed.

Step 3: List Available Tools

• Go to the “Tools” tab
• Click “List Tools” to see all tools provided by the server

Step 4: Test Capability 1 – Check Allowed Directories

• Select the list_allowed_directories tool
• Click “Run Tool”
• The result will show which directories are accessible to the server

Step 5: Test Capability 2 – Read a File

• Select the read_file tool
• Enter the file path in the parameters field
• Click “Run Tool”
• The file content will appear in the result panel

Similarly, you can test all the other capabilities that are offered by the Filesystem MCP Server

Output:

List Allowed Directories – MCP InspectorRead File – MCP Inspector

9. Practical Example: Testing Our Spring Boot AI MongoDB MCP Server

Now let’s test our custom Spring Boot AI MongoDB MCP server that we built in a previous tutorial:

Step 1: Start the Inspector:

npx @modelcontextprotocol/inspector -e MONGO_HOST=localhost -e MONGO_PORT=27017 java -jar /Users/bunty/mcp-demo/spring-boot-ai-mongo-mcp-server-0.0.1-SNAPSHOT.jar

This command launches the MCP Inspector and starts the Spring AI MongoDB MCP server with the specified MongoDB host and port.

Step 2: Connect to the Server:

• Open http://127.0.0.1:6274 in your browser and click the “Connect” button.
• Since the server configuration is already specified during startup, no additional setup is needed.

Step 3: List Available Tools

• Go to the “Tools” tab
• Click “List Tools” to view the tools available in the Spring AI MongoDB MCP server
  

Step 4: Test Capability 1 – List Available Databases

• Select the listDatabases tool
• Click “Run Tool”
• The result will show all the available databases

Step 5: Test Capability 2 – List Collections

• Select the listCollections tool that will list the available collections within the specified database
• Enter the database name
• Click “Run Tool”
• The rsult will show all the available collections under the specified database

Similarly, you can test all the other capabilities that are offered by Spring AI MongoDB MCP Server

Output:

List Databases – MCP InspectorList Collections – MCP Inspector

10. CLI Mode: Using MCP Inspector from the Command Line

Besides the web interface, MCP Inspector also offers a CLI (Command Line Interface) mode. This lets you interact with MCP servers directly from your terminal, which is great for automating tasks and writing scripts.

10.1. Basic Lauch Command

npx @modelcontextprotocol/inspector --cli <command_to_start_your_server> --method <method_name> [--additional-args]

📝 Note: –method is mandatory in CLI mode to specify which server method (tool, resource, etc.) you want to invoke.

Real example with Filesystem MCP server:

Start the Filesystem server and list tools:

npx @modelcontextprotocol/inspector --cli npx -y @modelcontextprotocol/server-filesystem --method tools/list /Users/bunty/mcp-demo

10.2. Use a Configuration File

Start the Filesystem server configured in the provided config.json file and list tools:

npx @modelcontextprotocol/inspector --cli --config config.json --server filesystem --method tools/list

10.3. Use a specific tool

Invokes a tool with required parameters and shows the result.

npx @modelcontextprotocol/inspector --cli npx -y @modelcontextprotocol/server-filesystem /Users/bunty/mcp-demo --method tools/call --tool-name read_file --tool-arg path=/Users/bunty/mcp-demo/test-folder-1/test-file.txt

Flags:

• –method flag specifies the operation (tools/call)
• –tool-name indicates which tool to run (read_file)
• –tool-arg provides the tool parameter (path to the file)

The above command will launch the Filesystem MCP server in CLI mode and use the read_file tool to read and display the contents of test-file.txt located inside test-folder-1.

10.4. List available resources:

Retrieves all resources from the server if available.

npx @modelcontextprotocol/inspector --cli npx -y @modelcontextprotocol/server-filesystem /Users/bunty/mcp-demo --method resources/list

Flags:

• –method flag specifies the operation to perform (resources/list), which fetches metadata like MIME types and descriptions for each resource.

10.5. List available prompts:

List all available prompts from the server if available.

npx @modelcontextprotocol/inspector --cli npx -y @modelcontextprotocol/server-filesystem /Users/bunty/mcp-demo --method prompts/list

Flags:

• –method prompts/list flag specifies the operation to list all available prompt templates

10.6. Connect to a remote server

You can also connect to MCP servers running elsewhere:

npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com

You can perform all operations similarly, like listing tools, executing tools, listing resources, and more, just as you would with a local server.

11. Browser (UI) vs. Command Line (CLI): Which One Should You Use?

Both ways of using the Inspector are useful! Here’s a simple guide on when to pick which:

If you’re just getting started, the web UI might be easier. But as you become more familiar with MCP, the CLI mode offers powerful capabilities for automation and integration with your development workflow.

12. Video Tutorial

If you prefer visual learning, check out our step-by-step video tutorial demonstrating how to use the MCP Inspector tool. We cover all the essential commands with practical examples – from basic commands to passing environment variables, using configuration files, and working with CLI mode.

📺 Watch on YouTube:

13. Things to Consider

When working with MCP Inspector, consider these important factors:

1. Security: The MCP Inspector is a development tool. Be cautious about the data you send and the servers you connect to.
2. Resource Usage: Running both your server and the Inspector can consume significant resources. Be mindful of memory and CPU usage.
3. Configuration Management: Keep your configuration files organized, especially when working with multiple MCP servers.
4. Network Considerations: The Inspector uses local ports for communication. Ensure these ports are not blocked by firewalls or other security measures.
5. Timeout Handling: Adjust timeout settings in the Configuration panel if your server operations take too long and result in timeouts.

14. FAQs

15. Conclusion

MCP Inspector is a handy tool for developers working with the Model Context Protocol. It makes it easy to test, debug, and interact with MCP servers using a simple and user-friendly interface. With this guide, you now have a clear understanding of how to use MCP Inspector to check your server setups—whether you’re using the filesystem server, Spring Boot AI, or something else. As you continue working with MCP, this tool will be your go-to companion for verifying functionality and staying aligned with protocol standards.

16. Learn More