MCP Inspector: How to Test and Debug an MCP Server Step by Step

MCP Inspector: How to Test and Debug an MCP Server Step by Step

To use MCP Inspector, run the command npx @modelcontextprotocol/inspector, choose your server's transport (stdio or HTTP), connect, and call each tool, resource and prompt from the interface while watching the messages exchanged. This confirms schemas, response format, transport and authentication without a language model in the loop, which would only add uncertainty to the test.

Key takeaways

• Inspector is a test client: it isolates the MCP server from the agent and shows exactly what goes in and what comes out.
• Test valid inputs first, then invalid, empty and hostile ones, to check the schema and the error messages.
• Transport failures usually come from a wrong command, polluted stdio output, an incorrect address or a badly configured HTTP session.
• Test authentication with correct, missing, expired and under-privileged credentials.
• Connect the server to an agent only after a short checklist, with action limits and a record of the tests.

What MCP Inspector is and when to use it

The Model Context Protocol (MCP) is an open protocol that defines how AI applications connect to tools and data sources. If you want the big picture, the official MCP introduction on modelcontextprotocol.io is the place to start. MCP Inspector is the testing and debugging tool maintained alongside the project. It acts as an MCP client with a visual interface: it connects to your server, lists what the server exposes and lets you exercise each item by hand.

The main advantage is separating causes. When an agent fails to use a tool, the problem can be in the server, the schema, authentication, transport, the agent's instructions or the model itself. With Inspector, you remove every cause that is not the server. If the tool works there and fails in the agent, the focus shifts to the tool description and the context. If it fails there, the server is not ready yet.

Use Inspector at three moments: while building your own server, while evaluating a third-party server (together with the process in how to audit an MCP server before installing it at your company), and after any change of version, schema or credential.

How to open Inspector: step by step

You need Node.js installed. Inspector runs straight through npx, with no permanent installation. Because the tool keeps evolving, always check the README in the official repository for the version you use, since options and screens can change.

The basic routine is this:

• Run npx @modelcontextprotocol/inspector in the terminal. It starts a local interface and prints the address to open in your browser.
• In recent versions, the terminal also prints a session token for the local proxy. If the page refuses the connection, check that the address you opened includes that token, or that you entered it in the settings.
• In the connection panel, choose the transport type: stdio for servers that run as a local process, or HTTP (streamable HTTP, and SSE on older servers) for remote servers.
• For stdio, enter the command, the arguments and the environment variables. For HTTP, enter the URL and, if needed, authentication headers.
• Click connect and check that initialization finishes successfully. After that, the tools, resources and prompts tabs show what the server declared.

You can also pass the server command directly on Inspector's command line, which makes it easier to repeat the same test. If you have already configured the server in a client, compare it with what we describe in configure MCP in Claude Code: the command and variables that work in Inspector should be the same ones that go into the final configuration.

How to validate tools and schemas

In the tools tab, Inspector lists each tool with its name, description and input schema. In practice, this screen is what the model will see. Read it as if you were the model: does the description say clearly when to use the tool and when not to? Are the parameter names self-explanatory? Are required fields marked?

Anthropic has good material on this in its engineering article on writing effective tools for agents. The core idea is that ambiguous descriptions and overly long responses make a tool harder to use well. Inspector makes these problems visible before any agent is involved.

For each tool, run at least these tests:

• Typical valid input: confirm the response has the expected format and carries only what is needed, with no extra data the agent should not see.
• Missing required field: the server should refuse with a clear error, not with a generic failure or a silent default value.
• Wrong type: text where a number is expected, an empty list, a null value, very long text.
• Out-of-range value: an impossible date, an identifier that does not exist, a negative value where only positive makes sense.
• Hostile input: text with embedded instructions or special characters. This does not prove security, but it shows whether the server treats input as data.
• Repetition: call the same tool twice with the same arguments and check whether the second call duplicates an effect, such as creating two records.

Pay attention to the difference between read tools and write tools. The protocol allows annotations that indicate, for example, that a tool is read-only or destructive, but these are hints for the client, not a security barrier. The real barrier must live in the server and in the permissions of the credential in use. For a broader view of input, output and action validation, see guardrails for AI agents.

Also test resources and prompts, if the server offers them. For resources, check that the listing does not expose more than it should. For prompts, check that arguments are validated and that the generated text does not carry sensitive data.

How to find transport errors

Transport errors are the most frustrating because the symptom is almost always the same: the connection does not open, or drops right after opening. Inspector helps because it shows at which step the failure happens.

With stdio transport, the most common causes are:

• Wrong command or path: the process does not even start. Run the same command manually in the terminal.
• Polluted output: in stdio, standard output carries the protocol messages. Any log, warning or print written there corrupts the communication. Logs should go to the error output.
• Missing environment variables: the server starts but fails when it looks up a key or an address. Check that they were entered in the connection panel.
• Different runtime version: the server works in your terminal and fails in Inspector because the process environment is different.

With HTTP transport, the suspects change:

• Wrong URL or endpoint path, which results in a not found response.
• A transport type chosen in Inspector that differs from what the server implements, for example old SSE against a streamable HTTP server.
• A proxy, load balancer or firewall that closes long connections or buffers streamed responses.
• Missing required headers, such as the authorization header.
• Sessions that expire or get lost when there is more than one server instance behind a load balancer without session affinity.

Use Inspector's notifications area and message history to see the order of events: initialization request, response, tool list. If initialization is never answered, the problem is in transport or in the process. If initialization works and the tool list fails, the problem is in the server implementation.

How to debug authentication and permissions

Remote servers almost always require credentials. Test authentication as a set of cases, not as a single success test. The OWASP Authorization Cheat Sheet recommends denying by default and checking permissions on every request, and those principles guide the tests below.

• No credential: the server should answer with a clear refusal, not partial data.
• Valid credential: the connection works and the tools appear.
• Expired or revoked credential: the refusal should be immediate and the message should not leak internal details.
• Credential with smaller scope: write tools should fail for someone who only has read access.
• Credential from another user or another unit: data that belongs to someone else must not be returned.

If the server uses OAuth, the authorization flow has its own steps (redirect, consent, exchange of code for token, renewal). Google's OAuth 2.0 documentation is a clear reference for understanding each step. Recent versions of Inspector support testing this flow. If yours does not, obtain the token another way and enter it in the authorization header, remembering to use a test credential, never a production one.

A data protection note (LGPD in Brazil): during testing, avoid real customer data whenever you can. Prefer a test database with fictional records. If using real data is unavoidable, limit the credential to the minimum needed and do not keep screenshots or logs containing personal information.

Illustrative scenario and a checklist before connecting to an agent

Illustrative scenario: a services company builds an MCP server with two tools, one that checks the status of an order and another that changes the delivery date. In Inspector, the status check works. When testing the change with a date in the past, the server accepts and saves it. When testing with an order number belonging to another customer using the same credential, the change also goes through. No agent was needed to find two serious problems: missing domain validation and missing ownership checks on the order. Both are fixed in the server, and the same tests are repeated until the refusal appears.

Use this checklist before the integration:

• Every tool has a clear name, a description that says when to use it, and a schema with required fields marked.
• Each tool was tested with valid, missing, wrong-type, out-of-range and repeated input.
• Responses carry only the necessary fields and have a controlled size, so they do not consume the agent's context window for no reason.
• Error messages are clear to the model and do not expose internal details.
• Transport was tested in the real environment, not only on the development machine.
• Authentication was tested in the five cases: no credential, valid, expired, smaller scope and another user.
• Write tools have an action limit, human confirmation when the risk justifies it, and a record of who asked for what.
• The test script is saved so it can be repeated after every server change.

After the integration, remember that the agent can call tools in sequence and repeat calls. Step and time limits are still necessary, as we explain in AI agent infinite loop: step limits, time and budget caps.

How the map, limit, pilot and hand over method applies

Inspector fits well into the working method we follow in AI projects. In map, you list which tools the server exposes and which business process each one touches. In limit, you define which actions stay available, with which credential and with which human approval. In pilot, you use the Inspector test script as a base and follow a real flow with records and an agreed success criterion. In hand over, you give the script, the checklist and the records to the team, who decide whether to expand, adjust or stop. Inspector does not replace evaluations of the agent's behavior. It only ensures that the server underneath the agent is predictable.

Frequently asked questions

Does MCP Inspector work for third-party servers? Yes, and it is one of the best ways to see what a server really exposes before you install it. It shows tools, descriptions and responses, but it does not replace reading the code, reviewing permissions and doing a security analysis.

Can I use Inspector in production? The safest approach is to test in a separate environment, with test credentials and fictional data. If you must diagnose something in production, use a read credential with the smallest possible scope and avoid calling tools that change data.

The tool works in Inspector and fails in the agent. What should I check? Compare the description and schema the model sees, the size of the responses and the agent's instructions. Also confirm that the client configuration uses the same command, the same variables and the same credential you tested. If all of that matches, the problem is in how the model uses the tool, and the path is to adjust descriptions and evaluate behavior with test cases.

Does Inspector test the server's security? It helps find obvious flaws, such as missing validation and access control, but it is not a security audit. Treat it as the first layer of verification and combine it with code review, least-privilege permissions and practices like those in the OWASP Top 10 for LLM applications.

Sources

• Model Context Protocol: introdução
• Anthropic: Writing effective tools for agents
• OWASP: guia de autorização
• Google: OAuth 2.0