This guide covers everything about MCP inspector, from basic installation to advanced debugging techniques. You'll learn how to connect to local and remote servers, choose the right transport type, troubleshoot common issues, and integrate Inspector testing into your development workflow.
What is MCP Inspector?
MCP Inspector is an interactive, browser-based developer tool for testing and debugging Model Context Protocol (MCP) servers. Think of it as a Postman equivalent for the MCP world, giving you a direct window into your server's behavior without needing a full-fledged AI client. It allows you to connect to a local or remote MCP server, view the tools it exposes, and call them with specific parameters to see the raw JSON response—a crucial step when transitioning from API to MCP.
It's important to distinguish between the components. MCP is the protocol, the set of rules for communication. An MCP server is the program you build that implements this protocol to expose your API's functionality. MCP Inspector is the testing utility you use to verify your server is behaving correctly, which is especially useful for validating servers generated by creating an MCP server from an OpenAPI spec.
Install and run MCP Inspector
Getting the Inspector running is straightforward since it's available as an npm package. You can run it directly from your terminal without a permanent installation.
Run inspector from npm
The quickest way to launch the Inspector is with npx. This command downloads the latest version of the tool and runs it immediately in your terminal.
After running this, the Inspector UI will be available at http://localhost:6274. It also starts a proxy server on port 6277, which it uses to communicate with local server processes.
Run inspector with local server
To test an MCP server running on your local machine, you can pass the command to start your server directly to the Inspector. The Inspector's proxy will manage running your server process and communicating with it.
For example, if you have a TypeScript server that Stainless created when you generate an MCP server from an OpenAPI spec, the command might look like this (adjust the path if your build outputs elsewhere):
npx @modelcontextprotocol/inspector -- "node" "packages/mcp-server/dist/index.js"
Connect to remote server
If your MCP server is deployed and accessible via a URL, you can connect the Inspector to it directly. In the Inspector UI, select the "Streamable HTTP" transport, enter your server's URL, and add any required authentication headers, like a bearer token.
Choose a transport type
MCP supports different communication layers, or transports, between the client (Inspector) and the server. Choosing the right one depends on where your server is running.
Select STDIO transport
The STDIO (standard input/output) transport is the default for testing local servers. When you provide a command to the Inspector, it runs that command as a child process and communicates with it by writing to its standard input and reading from its standard output. This is the simplest method for local development and debugging.
Select streamable HTTP transport
Streamable HTTP is the modern standard for remote communication. It uses HTTP POST requests for client-to-server messages and is the transport you'll use for any deployed MCP server, such as one running on a Cloudflare Worker. Servers created through converting complex OpenAPI specs to MCP servers often default to this transport for maximum compatibility.
Avoid SSE transport
Server-Sent Events (SSE) is a legacy transport that you will likely not need for new projects. While some older clients or servers might still use it, Streamable HTTP is the recommended approach for any network-based MCP communication.
Test MCP servers with Inspector
Once connected, the Inspector UI provides a clean interface to interact with your server's capabilities. It's organized into clear sections that map directly to the core concepts of MCP.
Call tools
This is the primary function of the Inspector. The "Tools" panel lists all tools exposed by your server. You can select a tool, fill in its input parameters using a form generated from its JSON schema, and click "Call" to see the exact JSON response from the server.
Inspect resources
The "Resources" panel allows you to browse static context provided by the server. This could include things like file contents, database schemas, or other data blobs that the server wants to make available to the LLM without requiring a tool call.
Validate prompts
If your server supports the prompts capability, you can test it here. This panel lets you see the available prompt templates, supply arguments, and preview the final message structure that would be sent to an LLM.
Monitor notifications
The log panel at the bottom of the UI displays all messages exchanged between the Inspector and your server. This is invaluable for debugging, as it shows real-time notifications, requests, responses, and any errors that occur during the session.
When to use MCP Inspector or other tools
MCP Inspector is a powerful tool, but it's part of a larger testing ecosystem. Knowing when to use it versus other tools will make your development workflow more efficient.
Tool | Best For | When to Use |
|---|---|---|
MCP Inspector | Unit & Integration Testing | During initial development to verify tool schemas, test individual tool calls, and debug connection issues. |
AI Clients | End-to-End & User Testing | Once your server is stable, use clients like Claude Desktop or Cursor to test how a real LLM reasons about and uses your tools in a conversational flow. |
CI Automation | Contract & Regression Testing | Use the Inspector's CLI mode or a custom script in your CI/CD pipeline to ensure that changes to your API don't break the MCP server's contract. |
Postman/cURL | Raw API Testing | If your MCP server is a wrapper around a standard REST or GraphQL API, use traditional tools to test the underlying API endpoints directly. |
Fix common MCP Inspector issues
While using the Inspector, you might run into a few common roadblocks. Here’s how to troubleshoot them.
Resolve connection errors
If the Inspector can't connect to your server, first check for port conflicts. Ensure that no other service is using ports 6274 or 6277. If you're running a local server, verify the command path is correct and that your system's firewall isn't blocking the connection.
Resolve transport mismatches
An error message about protocols or transports usually means you've selected the wrong transport type in the Inspector UI. If you're running a local server with a command, you need to use "STDIO". If you're connecting to a URL, you must use "Streamable HTTP".
Resolve authentication failures
For remote servers, a 401 Unauthorized error typically means your bearer token is missing, expired, or incorrect. Double-check the token and ensure you've entered it correctly in the "Headers" section of the Inspector's connection settings. For local servers, make sure any required API keys are correctly set as environment variables for the process.
Resolve schema validation errors
Schema issues can be the trickiest to debug. Some AI clients have unique limitations, like poor support for $ref pointers or union types (anyOf). The Inspector helps you see exactly what schema your server is providing. If you encounter validation errors, it often points to a need to transform your OpenAPI schema to be more compatible—a challenge addressed when converting complex OpenAPI specs to MCP servers, where a robust server generation tool can automate this by detecting the client and adjusting the schema on the fly.
Frequently asked questions about MCP Inspector
Can MCP Inspector test production servers?
Yes, you can connect to any remote server by providing its URL and necessary authentication headers. However, be cautious about running it against a live production environment, as it bypasses typical client-side safeguards.
Does MCP Inspector work with every MCP client?
MCP Inspector is a reference client for the protocol itself. It helps you verify that your server is compliant, but different AI clients (like Cursor or Claude) may have their own quirks or limitations in how they interpret schemas, which the Inspector won't simulate.
How do I test Stainless-generated MCP servers?
For a server generated by Stainless, you'll typically find it in the packages/mcp-server directory of your TypeScript SDK. You can run it locally using the "STDIO" transport or deploy it and connect remotely using its "Streamable HTTP" URL.
Is MCP Inspector secure for sensitive data?
The Inspector is a developer tool and should be used in trusted environments. While it uses a session token for security, it's best to avoid testing with production-level sensitive data and to ensure the Inspector's ports are not exposed to the public internet.
Ready to build your own MCP server from an OpenAPI spec? Get started for free.
This guide covers everything about MCP inspector, from basic installation to advanced debugging techniques. You'll learn how to connect to local and remote servers, choose the right transport type, troubleshoot common issues, and integrate Inspector testing into your development workflow.
What is MCP Inspector?
MCP Inspector is an interactive, browser-based developer tool for testing and debugging Model Context Protocol (MCP) servers. Think of it as a Postman equivalent for the MCP world, giving you a direct window into your server's behavior without needing a full-fledged AI client. It allows you to connect to a local or remote MCP server, view the tools it exposes, and call them with specific parameters to see the raw JSON response—a crucial step when transitioning from API to MCP.
It's important to distinguish between the components. MCP is the protocol, the set of rules for communication. An MCP server is the program you build that implements this protocol to expose your API's functionality. MCP Inspector is the testing utility you use to verify your server is behaving correctly, which is especially useful for validating servers generated by creating an MCP server from an OpenAPI spec.
Install and run MCP Inspector
Getting the Inspector running is straightforward since it's available as an npm package. You can run it directly from your terminal without a permanent installation.
Run inspector from npm
The quickest way to launch the Inspector is with npx. This command downloads the latest version of the tool and runs it immediately in your terminal.
After running this, the Inspector UI will be available at http://localhost:6274. It also starts a proxy server on port 6277, which it uses to communicate with local server processes.
Run inspector with local server
To test an MCP server running on your local machine, you can pass the command to start your server directly to the Inspector. The Inspector's proxy will manage running your server process and communicating with it.
For example, if you have a TypeScript server that Stainless created when you generate an MCP server from an OpenAPI spec, the command might look like this (adjust the path if your build outputs elsewhere):
npx @modelcontextprotocol/inspector -- "node" "packages/mcp-server/dist/index.js"
Connect to remote server
If your MCP server is deployed and accessible via a URL, you can connect the Inspector to it directly. In the Inspector UI, select the "Streamable HTTP" transport, enter your server's URL, and add any required authentication headers, like a bearer token.
Choose a transport type
MCP supports different communication layers, or transports, between the client (Inspector) and the server. Choosing the right one depends on where your server is running.
Select STDIO transport
The STDIO (standard input/output) transport is the default for testing local servers. When you provide a command to the Inspector, it runs that command as a child process and communicates with it by writing to its standard input and reading from its standard output. This is the simplest method for local development and debugging.
Select streamable HTTP transport
Streamable HTTP is the modern standard for remote communication. It uses HTTP POST requests for client-to-server messages and is the transport you'll use for any deployed MCP server, such as one running on a Cloudflare Worker. Servers created through converting complex OpenAPI specs to MCP servers often default to this transport for maximum compatibility.
Avoid SSE transport
Server-Sent Events (SSE) is a legacy transport that you will likely not need for new projects. While some older clients or servers might still use it, Streamable HTTP is the recommended approach for any network-based MCP communication.
Test MCP servers with Inspector
Once connected, the Inspector UI provides a clean interface to interact with your server's capabilities. It's organized into clear sections that map directly to the core concepts of MCP.
Call tools
This is the primary function of the Inspector. The "Tools" panel lists all tools exposed by your server. You can select a tool, fill in its input parameters using a form generated from its JSON schema, and click "Call" to see the exact JSON response from the server.
Inspect resources
The "Resources" panel allows you to browse static context provided by the server. This could include things like file contents, database schemas, or other data blobs that the server wants to make available to the LLM without requiring a tool call.
Validate prompts
If your server supports the prompts capability, you can test it here. This panel lets you see the available prompt templates, supply arguments, and preview the final message structure that would be sent to an LLM.
Monitor notifications
The log panel at the bottom of the UI displays all messages exchanged between the Inspector and your server. This is invaluable for debugging, as it shows real-time notifications, requests, responses, and any errors that occur during the session.
When to use MCP Inspector or other tools
MCP Inspector is a powerful tool, but it's part of a larger testing ecosystem. Knowing when to use it versus other tools will make your development workflow more efficient.
Tool | Best For | When to Use |
|---|---|---|
MCP Inspector | Unit & Integration Testing | During initial development to verify tool schemas, test individual tool calls, and debug connection issues. |
AI Clients | End-to-End & User Testing | Once your server is stable, use clients like Claude Desktop or Cursor to test how a real LLM reasons about and uses your tools in a conversational flow. |
CI Automation | Contract & Regression Testing | Use the Inspector's CLI mode or a custom script in your CI/CD pipeline to ensure that changes to your API don't break the MCP server's contract. |
Postman/cURL | Raw API Testing | If your MCP server is a wrapper around a standard REST or GraphQL API, use traditional tools to test the underlying API endpoints directly. |
Fix common MCP Inspector issues
While using the Inspector, you might run into a few common roadblocks. Here’s how to troubleshoot them.
Resolve connection errors
If the Inspector can't connect to your server, first check for port conflicts. Ensure that no other service is using ports 6274 or 6277. If you're running a local server, verify the command path is correct and that your system's firewall isn't blocking the connection.
Resolve transport mismatches
An error message about protocols or transports usually means you've selected the wrong transport type in the Inspector UI. If you're running a local server with a command, you need to use "STDIO". If you're connecting to a URL, you must use "Streamable HTTP".
Resolve authentication failures
For remote servers, a 401 Unauthorized error typically means your bearer token is missing, expired, or incorrect. Double-check the token and ensure you've entered it correctly in the "Headers" section of the Inspector's connection settings. For local servers, make sure any required API keys are correctly set as environment variables for the process.
Resolve schema validation errors
Schema issues can be the trickiest to debug. Some AI clients have unique limitations, like poor support for $ref pointers or union types (anyOf). The Inspector helps you see exactly what schema your server is providing. If you encounter validation errors, it often points to a need to transform your OpenAPI schema to be more compatible—a challenge addressed when converting complex OpenAPI specs to MCP servers, where a robust server generation tool can automate this by detecting the client and adjusting the schema on the fly.
Frequently asked questions about MCP Inspector
Can MCP Inspector test production servers?
Yes, you can connect to any remote server by providing its URL and necessary authentication headers. However, be cautious about running it against a live production environment, as it bypasses typical client-side safeguards.
Does MCP Inspector work with every MCP client?
MCP Inspector is a reference client for the protocol itself. It helps you verify that your server is compliant, but different AI clients (like Cursor or Claude) may have their own quirks or limitations in how they interpret schemas, which the Inspector won't simulate.
How do I test Stainless-generated MCP servers?
For a server generated by Stainless, you'll typically find it in the packages/mcp-server directory of your TypeScript SDK. You can run it locally using the "STDIO" transport or deploy it and connect remotely using its "Streamable HTTP" URL.
Is MCP Inspector secure for sensitive data?
The Inspector is a developer tool and should be used in trusted environments. While it uses a session token for security, it's best to avoid testing with production-level sensitive data and to ensure the Inspector's ports are not exposed to the public internet.
Ready to build your own MCP server from an OpenAPI spec? Get started for free.
This guide covers everything about MCP inspector, from basic installation to advanced debugging techniques. You'll learn how to connect to local and remote servers, choose the right transport type, troubleshoot common issues, and integrate Inspector testing into your development workflow.
What is MCP Inspector?
MCP Inspector is an interactive, browser-based developer tool for testing and debugging Model Context Protocol (MCP) servers. Think of it as a Postman equivalent for the MCP world, giving you a direct window into your server's behavior without needing a full-fledged AI client. It allows you to connect to a local or remote MCP server, view the tools it exposes, and call them with specific parameters to see the raw JSON response—a crucial step when transitioning from API to MCP.
It's important to distinguish between the components. MCP is the protocol, the set of rules for communication. An MCP server is the program you build that implements this protocol to expose your API's functionality. MCP Inspector is the testing utility you use to verify your server is behaving correctly, which is especially useful for validating servers generated by creating an MCP server from an OpenAPI spec.
Install and run MCP Inspector
Getting the Inspector running is straightforward since it's available as an npm package. You can run it directly from your terminal without a permanent installation.
Run inspector from npm
The quickest way to launch the Inspector is with npx. This command downloads the latest version of the tool and runs it immediately in your terminal.
After running this, the Inspector UI will be available at http://localhost:6274. It also starts a proxy server on port 6277, which it uses to communicate with local server processes.
Run inspector with local server
To test an MCP server running on your local machine, you can pass the command to start your server directly to the Inspector. The Inspector's proxy will manage running your server process and communicating with it.
For example, if you have a TypeScript server that Stainless created when you generate an MCP server from an OpenAPI spec, the command might look like this (adjust the path if your build outputs elsewhere):
npx @modelcontextprotocol/inspector -- "node" "packages/mcp-server/dist/index.js"
Connect to remote server
If your MCP server is deployed and accessible via a URL, you can connect the Inspector to it directly. In the Inspector UI, select the "Streamable HTTP" transport, enter your server's URL, and add any required authentication headers, like a bearer token.
Choose a transport type
MCP supports different communication layers, or transports, between the client (Inspector) and the server. Choosing the right one depends on where your server is running.
Select STDIO transport
The STDIO (standard input/output) transport is the default for testing local servers. When you provide a command to the Inspector, it runs that command as a child process and communicates with it by writing to its standard input and reading from its standard output. This is the simplest method for local development and debugging.
Select streamable HTTP transport
Streamable HTTP is the modern standard for remote communication. It uses HTTP POST requests for client-to-server messages and is the transport you'll use for any deployed MCP server, such as one running on a Cloudflare Worker. Servers created through converting complex OpenAPI specs to MCP servers often default to this transport for maximum compatibility.
Avoid SSE transport
Server-Sent Events (SSE) is a legacy transport that you will likely not need for new projects. While some older clients or servers might still use it, Streamable HTTP is the recommended approach for any network-based MCP communication.
Test MCP servers with Inspector
Once connected, the Inspector UI provides a clean interface to interact with your server's capabilities. It's organized into clear sections that map directly to the core concepts of MCP.
Call tools
This is the primary function of the Inspector. The "Tools" panel lists all tools exposed by your server. You can select a tool, fill in its input parameters using a form generated from its JSON schema, and click "Call" to see the exact JSON response from the server.
Inspect resources
The "Resources" panel allows you to browse static context provided by the server. This could include things like file contents, database schemas, or other data blobs that the server wants to make available to the LLM without requiring a tool call.
Validate prompts
If your server supports the prompts capability, you can test it here. This panel lets you see the available prompt templates, supply arguments, and preview the final message structure that would be sent to an LLM.
Monitor notifications
The log panel at the bottom of the UI displays all messages exchanged between the Inspector and your server. This is invaluable for debugging, as it shows real-time notifications, requests, responses, and any errors that occur during the session.
When to use MCP Inspector or other tools
MCP Inspector is a powerful tool, but it's part of a larger testing ecosystem. Knowing when to use it versus other tools will make your development workflow more efficient.
Tool | Best For | When to Use |
|---|---|---|
MCP Inspector | Unit & Integration Testing | During initial development to verify tool schemas, test individual tool calls, and debug connection issues. |
AI Clients | End-to-End & User Testing | Once your server is stable, use clients like Claude Desktop or Cursor to test how a real LLM reasons about and uses your tools in a conversational flow. |
CI Automation | Contract & Regression Testing | Use the Inspector's CLI mode or a custom script in your CI/CD pipeline to ensure that changes to your API don't break the MCP server's contract. |
Postman/cURL | Raw API Testing | If your MCP server is a wrapper around a standard REST or GraphQL API, use traditional tools to test the underlying API endpoints directly. |
Fix common MCP Inspector issues
While using the Inspector, you might run into a few common roadblocks. Here’s how to troubleshoot them.
Resolve connection errors
If the Inspector can't connect to your server, first check for port conflicts. Ensure that no other service is using ports 6274 or 6277. If you're running a local server, verify the command path is correct and that your system's firewall isn't blocking the connection.
Resolve transport mismatches
An error message about protocols or transports usually means you've selected the wrong transport type in the Inspector UI. If you're running a local server with a command, you need to use "STDIO". If you're connecting to a URL, you must use "Streamable HTTP".
Resolve authentication failures
For remote servers, a 401 Unauthorized error typically means your bearer token is missing, expired, or incorrect. Double-check the token and ensure you've entered it correctly in the "Headers" section of the Inspector's connection settings. For local servers, make sure any required API keys are correctly set as environment variables for the process.
Resolve schema validation errors
Schema issues can be the trickiest to debug. Some AI clients have unique limitations, like poor support for $ref pointers or union types (anyOf). The Inspector helps you see exactly what schema your server is providing. If you encounter validation errors, it often points to a need to transform your OpenAPI schema to be more compatible—a challenge addressed when converting complex OpenAPI specs to MCP servers, where a robust server generation tool can automate this by detecting the client and adjusting the schema on the fly.
Frequently asked questions about MCP Inspector
Can MCP Inspector test production servers?
Yes, you can connect to any remote server by providing its URL and necessary authentication headers. However, be cautious about running it against a live production environment, as it bypasses typical client-side safeguards.
Does MCP Inspector work with every MCP client?
MCP Inspector is a reference client for the protocol itself. It helps you verify that your server is compliant, but different AI clients (like Cursor or Claude) may have their own quirks or limitations in how they interpret schemas, which the Inspector won't simulate.
How do I test Stainless-generated MCP servers?
For a server generated by Stainless, you'll typically find it in the packages/mcp-server directory of your TypeScript SDK. You can run it locally using the "STDIO" transport or deploy it and connect remotely using its "Streamable HTTP" URL.
Is MCP Inspector secure for sensitive data?
The Inspector is a developer tool and should be used in trusted environments. While it uses a session token for security, it's best to avoid testing with production-level sensitive data and to ensure the Inspector's ports are not exposed to the public internet.
Ready to build your own MCP server from an OpenAPI spec? Get started for free.