If you found this by searching "MCP Inspector not connecting" or "how to test my MCP server," you're in the right place. And if your server compiles clean but you have no idea whether it actually behaves correctly until a real client blows up on it - that's exactly what this article is for.
MCP Inspector gives you a complete, transport-aware debugging loop for any MCP server you're building or maintaining. But only if you configure transport type, paths, and auth correctly from the start. Get those three things wrong and you'll spend an hour chasing a connection error that has nothing to do with your server code.
What breaks before you even connect
- MCP Inspector surfaces tools, resources, and prompts separately - so you can validate each protocol primitive independently.
- Wrong transport type produces silent timeouts, not useful errors; this is where most setup tickets originate.
- HTTP servers require the
/mcppath segment - omitting it causes routing failures even when the server responds to pings.- A passing Inspector test confirms clean connection and correct schemas, not that your production client will behave identically.
Prerequisites for Running MCP Inspector
Get these in place before you touch Inspector. Missing any one of them produces a different, confusing failure mode for each.
Node.js and npm installed
Inspector is launched via
npx, which ships with npm. Without Node.js on your machine, the CLI command fails immediately with a "command not found" error that looks like an Inspector problem but isn't. It's a runtime problem.A running MCP server before you connect
This is an open-source developer tool for testing and debugging - it doesn't start your server for you. If the server process isn't already up, Inspector will attempt a connection, time out, and give you an error that looks like a transport misconfiguration. The server has to be alive before Inspector enters the picture.
A modern browser for the GUI
Inspector serves its interface from a local Node process on port 6274. Chrome or Firefox, current version. Older browsers have caused the UI to fail to render. The tool is a browser-based GUI, not a desktop app - that surprises a lot of people the first time.
VS Code with the MCP extension installed (if using the IDE variant)
The bundled Inspector available inside VS Code and similar IDEs requires the extension to be installed before the auto-launch works. Skipping this and expecting the npx path to launch the IDE-integrated variant produces nothing useful.
OAuth credentials ready if your server requires authentication
Client ID, client secret, and redirect URL must be in hand before you connect to an auth-protected server. Trying to sort out credentials after Inspector is already open leads to partial flows, session state confusion, and token errors that look like server problems.
Getting Started: How to Launch MCP Inspector
There are two main ways to start Inspector. The CLI path via npx is the most direct and works everywhere Node is installed. The IDE-integrated path auto-launches inside your development environment if you have the right extension. Both end up serving the same browser-based UI on localhost.
Running MCP Inspector via npx CLI
Open your terminal and run:
npx @modelcontextprotocol/inspector@latest
That's it for the command. What happens next: a local Node process starts, and Inspector serves its browser UI - by default at http://localhost:6274. Your browser should open automatically. If it doesn't, navigate there manually.
The thing people miss at this "getting started" moment is expecting a desktop application. Inspector isn't one. It's a browser tab served from a local server. Which means if you close the terminal, the UI disappears. Keep the process running while you're using the inspector UI.
When you pass a server command directly via CLI, Inspector can also launch the stdio server process for you inline - for example:
npx @modelcontextprotocol/inspector node /absolute/path/to/server.js
That's a useful shortcut when using the MCP Inspector with a local stdio server. The command line becomes the connection.
Running MCP Inspector from an IDE or Bundled Environment
Some environments, including VS Code with the MCP extension installed, bundle Inspector and auto-launch the browser UI when you trigger it from the IDE. The official repository on GitHub is the authoritative source for architecture details and version-specific behavior.
These IDE-integrated variants handle Claude Desktop integration more directly, since the extension knows your workspace context. But the extension must be installed first. Trying to invoke Inspector from VS Code without it produces nothing - no error, no UI, no useful feedback. Install the extension, then trigger.
Choosing the Right Transport: stdio, SSE, and Streamable HTTP
This is where most support tickets originate. Wrong transport type doesn't produce a clear error. It produces a silent timeout or a handshake failure with no message that tells you what went wrong. You'll stare at the connection status spinner and assume the server is down. It probably isn't.
MCP supports three distinct transport modes, and they are not interchangeable. Selecting the wrong one in Inspector is exactly like trying to speak French to someone who only speaks Portuguese - technically the same meeting, but nothing gets communicated.
Configuring stdio Transport: Command, Arguments, and Absolute Paths
Use stdio transport when your MCP server runs as a local child process, started directly by Inspector or a client. The server configuration in Inspector requires two fields: the Command (the executable) and Arguments (any flags or file paths).
The single most common setup mistake I see with stdio: using a relative path instead of an absolute one. Relative paths silently fail to start the server process. The error you get back doesn't say "bad path." It just doesn't connect. Use the full absolute path every time.
A valid stdio configuration looks like this:
| Field | Example value |
|---|---|
| Command | node |
| Arguments | /Users/marcus/projects/crm-mcp/server.js |
| Environment | API_KEY=your_key_here |
Pass environment variables through the Environment field, not by modifying your shell session. Inspector needs to see them at the process level.
Configuring HTTP and SSE Transport: URL Format and the /mcp Path
Use HTTP or SSE transport when your MCP server exposes an HTTP endpoint, either locally or remotely. The Cloudflare Agents documentation explicitly recommends this path for testing remote MCP servers and gateways before connecting them to an agent.
The configurable URL field is straightforward. The trap is the path segment. For servers implementing the MCP protocol over HTTP, the URL must include /mcp at the end:
https://your-server.example.com/mcp
Omitting /mcp causes routing failures that look like connection errors even when the server is fully reachable. The server responds at its root. The MCP protocol endpoint doesn't. You'll get a 404 or a silent timeout depending on how the server handles unrecognized routes. Add the path segment - it's not optional.
If you need to expose custom headers (like an Authorization header for a gateway), Inspector's HTTP transport configuration includes a Headers section. Add them there before connecting.
How to Handle Authentication for OAuth-Secured MCP Servers
Auth failures in MCP Inspector are almost always configuration sequence problems, not server problems. The server is reachable. The credentials exist. But something wasn't entered before the connection attempt, or wasn't entered in the right order, and the token is missing or invalid by the time Inspector makes its first request.
I keep seeing this pattern: someone debugs for 45 minutes assuming the MCP server has a bug, then discovers the proxy session token field was empty the entire time. Client-side auth error messages are often silent or misleading - which means the signal you need is in Inspector, not in your server logs.
Registering the MCP Inspector Client with Your Identity Provider
Before Inspector can complete an OAuth flow, your identity provider needs to know Inspector exists as a client. For Auth0 and similar providers, this means creating an application representing the Inspector client and obtaining its credentials.
You'll need: a Client ID, a Client Secret, and a registered redirect URL. The redirect URL must match exactly what Inspector expects - typically something like http://localhost:6274/oauth/callback. A mismatch here causes the consent flow to fail at the redirect step with a generic error that looks like a permission problem.
Two registration paths exist:
| Registration type | When to use it | What you configure |
|---|---|---|
| Static client registration | You control the identity provider | Create app manually, set client ID/secret + redirect URL |
| Dynamic client registration (DCR) | Provider supports DCR spec | Inspector negotiates credentials automatically during first connect |
If your identity provider supports DCR, Inspector can handle the registration flow on its own. If not, you're doing static registration. Check your provider's documentation - Auth0 supports both, but DCR requires an explicit configuration flag to enable. Getting this wrong means Inspector arrives with credentials the provider doesn't recognize, and you get a 401 that has nothing to do with your MCP server.
On the permission side: don't disable scopes trying to simplify the setup. The MCP server needs specific scopes to expose its tools correctly. Overly narrow permissions produce partial tool lists and 403 errors mid-session that look like Inspector bugs.
Completing the OAuth Flow and Entering Credentials in Inspector
In the Inspector UI, enter your Client ID, Client Secret, and the proxy session token in the authentication configuration section before clicking Connect. That sequence matters. Clicking Connect first and expecting to enter credentials in a popup is not how the flow works.
Once you click Connect with credentials in place, Inspector triggers the browser-based consent screen. Complete the login and accept the permissions. After that redirect, Inspector holds an active session token and you can proceed to the Tools tab.
The proxy session token is the piece most people overlook. It's separate from the OAuth client credentials. It's what allows Inspector's proxy layer to maintain the session between your browser and the MCP server. Leave it blank and you'll get a "token missing" error even though the server endpoint is perfectly reachable and the OAuth credentials are correct.
That is where the ticket usually starts.
How to Test MCP Servers: Tool Discovery and Running Tools
Once connected, the core testing workflow is three steps: Connect, List Tools, Run Tool. That sequence is the whole thing. What makes it useful is reading what comes back carefully at each step.
A successful connection shows a green status indicator in Inspector with the server name and protocol version visible. If you see that, you haven't finished testing - you've finished connecting. The testing starts now.
Using the Tools Tab to List and Inspect Tool Schemas
Click List Tools in the Tools tab. Inspector sends the MCP tools/list request to your server and renders the response - tool names, descriptions, and the full JSON schema for each tool's parameters.
This is where you validate several things at once. Are the tool names correct? Are the parameter descriptions accurate? Do required parameters show as required in the schema? Is the input schema what your server actually expects?
For servers exposing multiple tool namespaces (common with Ontology MCP servers or any server that wraps multiple backend APIs), the tool list is how you confirm namespace boundaries are working. A schema that shows the wrong parameter type for a tool is a server bug, and you'd rather find it here than in a production agent that silently passes the wrong type and gets back garbage.
Inspect the raw JSON schema directly in Inspector before running anything. It takes 30 seconds and it's caught real bugs that wouldn't have appeared until the third or fourth tool invocation.
Running a Tool and Reading the Response in Real Time
Select a tool from the list. Inspector renders a form based on the tool's input schema - fill in the required parameters, add any optional ones relevant to your test, and click Run Tool.
Inspector displays the raw request payload it sent and the raw response it received. Read both. The request shows you what Inspector actually serialized from your parameter inputs (useful for catching type coercions). The response shows the full server output, including any error payload.
For a practical success criterion: run the same tool twice with identical inputs. The responses should be identical (or deterministically different if the tool queries live data). Inconsistent responses on identical inputs usually indicate a server-side state problem or a race condition in the tool implementation. Run it five times if the tool touches external APIs - rate limit behavior and timeout handling show up in repeated runs in a way they won't in a single test.
Chris Ebert's walkthrough of the AWS Documentation MCP Server in Inspector is a good reference for what a clean tool invocation workflow looks like end-to-end - you can see the search_documentation tool parameters, the schema, and how to interpret the response before wiring the server into an agent.
📊 In practice:
A passing Inspector test confirms clean connection status, correct tool schemas, and consistent tool responses for expected inputs. It does not confirm that your production MCP client - an AI IDE, Claude Desktop, or an agent framework - will handle edge cases the same way. Inspector validates your server's protocol behavior. The client introduces its own interpretation layer.
Debugging MCP Server Errors: Logs, Requests, and Protocol-Level Views
When something fails in Inspector, the tabbed view layout is where you go to figure out where it failed. The tabs aren't decorative. Each one surfaces a different layer of the protocol interaction.
MCP servers expose three primary primitives: resources for context, tools for actions, and prompts for templated interactions. The GitHub community discussion on MCP architecture describes these clearly. Inspector surfaces all three separately, which means you can validate each one independently instead of assuming a working tool list means everything else is fine. It doesn't.
Reading the Error Output Panel and Request/Response Logs
The error output panel shows server-side messages, stderr output, and protocol-level error codes. If a tool invocation fails, look here first. A 401 means an auth token problem. A schema mismatch error means your server is returning a response that doesn't conform to what the tool schema declared. A timeout with no error code usually means the server received the request and stopped responding mid-execution.
The request/response logs show the raw MCP protocol messages, including the initialization handshake. This is where you inspect payloads and protocol-level details in full. If the handshake shows an unexpected capabilities mismatch, that's often the root cause of tools failing to list even when the connection appears green. Check the log before assuming the server code is wrong. The problem is frequently in the negotiation step.
Use the Prompts tab and Resources tab the same way: list them, inspect their schemas, invoke them with test inputs. A server that lists tools correctly but returns malformed resource URIs will fail in specific agent workflows that combine tool calls with context retrieval. Find that now, not after you've wired the server into a production AI workflow.
Iterate by tweaking server code, reconnecting, and re-running. Inspector doesn't persist sessions between server restarts - but reconnecting is fast, and this loop (change code → restart server → reconnect Inspector → re-run tool) is the core development rhythm for any MCP server work.
Troubleshooting Connection Errors and Common Misconfigurations
When the connection fails, work through this list before assuming the server has a bug:
Server not started before connecting
Inspector cannot start your server in most setups. If the process isn't running, the connection will time out. Start the server, confirm it's accepting connections, then open Inspector.
Wrong transport type selected
A stdio server configured as HTTP, or vice versa, produces a failed handshake with no useful diagnostic message. Look at how your server starts - if it's a child process, it's stdio. If it binds to a port, it's HTTP or SSE.
Missing /mcp path segment in the URL
For HTTP/Streamable HTTP transports, the URL must end with
/mcpfor correct protocol routing. A server reachable at its root does not mean the MCP endpoint is reachable.Auth token or proxy session token not entered before connecting
Enter all credentials before clicking Connect. Entering them after a failed connection attempt leaves Inspector in a partial state that sometimes requires a full reload to clear.
Relative path in stdio configuration
Use absolute paths for the server command. Relative paths fail silently during process start, which looks like a connection error.
🤔 Wait.
Inspector validates that your server behaves correctly during an Inspector session. But your production MCP client - whether that's a Claude Desktop setup, an AI IDE, or a custom agent - has its own interpretation of the protocol, its own retry behavior, and its own timeout logic. Developers regularly discover discrepancies only after switching from Inspector to their real client. Inspector is a necessary step, not the final one.
One more thing worth knowing about the debugging loop: if your MCP server handles authenticated calls and you're seeing intermittent auth failures that don't reproduce consistently in Inspector, the issue is often token scope rather than token validity. In Latenode, when engineers wire an MCP server into a multi-step automation workflow, they add a JavaScript node that logs the exact token, scopes, and request body on every call - so when a 401 appears, they have the full context in one place rather than piecing it together from three different logs. That pattern is directly useful here: build the logging into the workflow before you assume the server is broken.
References
- Webfuse - MCP Cheat Sheet (2026) - Model Context Protocol Quick Reference - 13/04/2026
- GitHub Community - Model Context Protocol (MCP): Revolutionizing Developer Workflows - 25/09/2025
- Model Context Protocol Blog - The 2026-07-28 MCP Specification Release Candidate - 21/05/2026
- Cloudflare - Test a Remote MCP Server · Cloudflare Agents docs - 17/05/2026
- Chris Ebert's Blog - Testing MCP Servers with MCP Inspector - 21/11/2025
- Apigene - How to Build, Deploy, and Scale a Python MCP Server (2026) - 11/04/2026
- Apigene - How to Test MCP Servers: Tools, Debugging, and CI - 11/04/2026
