How to Test an MCP Server with MCP Inspector

What is MCP Inspector?

MCP Inspector is a developer tool for connecting to an MCP server and inspecting the protocol interaction. It gives you a graphical web client, a scriptable CLI, and a terminal UI so you can discover capabilities, call them with controlled inputs, inspect results, and troubleshoot failures before an AI client depends on the server.

The current Inspector package is launched with npx and provides three testing surfaces:

The Inspector tests protocol behavior. It does not replace load testing, API contract tests, business-logic tests, security review, or production observability. A successful tools/list call proves that discovery works; it does not prove that every upstream API response is correct under load.

The current official documentation lists Node.js 22.19.0 or newer for the latest Inspector release. Check the MCP Inspector guide and the official Inspector documentation for the version and command details that apply when you run the test.

What should you test before production?

An MCP server is ready for a production trial only after you have tested the complete path, not just whether the process starts. Work through this sequence:

1. Connect to the exact local or remote server endpoint.

2. Complete initialization and confirm the negotiated transport and protocol behavior.

3. Inspect tools, resources, prompts, names, descriptions, and schemas.

4. Call safe capabilities with valid inputs.

5. Call them again with missing, invalid, boundary, and unauthorized inputs.

6. Test API keys, Bearer tokens, and OAuth using the same runtime path users will use.

7. Record and fix connection, authentication, schema, timeout, and upstream API errors.

8. Repeat the critical workflow through the hosted environment and a real MCP-compatible client.

This sequence catches a common failure pattern: a server appears healthy during startup, but the first real tool call fails because a required field, authentication header, resource URI, or upstream response shape was not tested.

How to connect MCP Inspector to an MCP server

Start by identifying the server transport. A local development server may be launched as a process over stdio. A hosted server normally exposes an HTTP-based MCP endpoint. The Inspector supports both patterns, but the command and failure modes are different.

Connect to a local server

For a locally developed Node server, the basic web command looks like this:

npx @modelcontextprotocol/inspector node path/to/server/index.js

The Inspector starts its local interface and prints a browser URL. Open that URL, select the server connection, and wait for initialization to complete. If the server needs its own arguments, environment variables, working directory, or package runner, use the command documented by that server rather than guessing.

Keep local test credentials outside source control. Use a test account or development API, redact tokens in terminal output, and do not copy a production secret into an example configuration just to make the first connection succeed.

Connect to a remote or hosted server

For a remote Streamable HTTP endpoint, pass the server URL and the HTTP transport explicitly:

npx @modelcontextprotocol/inspector \
  --server-url https://mcp.example.com/mcp \
  --transport http

The path matters. A base website URL, an API documentation URL, and an MCP endpoint are not interchangeable. Confirm the exact path, HTTPS certificate, DNS record, and expected transport before investigating tool schemas.

For a hosted server, the default 0mcp endpoint follows the pattern https://yourservername.0mcp.dev/mcp. Use the actual endpoint shown for the server and choose HTTP in Inspector because hosted servers currently use Streamable HTTP.

Connect through a configuration file

If you test the same server repeatedly, a configuration file can make the connection reproducible. Keep the file free of real secrets where possible, use environment variables or the Inspector's runtime settings, and distinguish a writable personal catalog from a read-only configuration supplied by a team.

After connecting, record:

• the server URL or launch command;

• the transport and protocol version used;

• the Inspector version and Node.js version;

• the server version or configuration version;

• the test identity and environment; and

• the time of the test.

That small record makes a later failure easier to compare with a working test.

Inspect tools, resources, and prompts

Do not begin by calling a complicated write operation. First inspect the capability surface and check whether the interface tells a client what it needs to know.

Check tools

For each tool, review:

• the tool name and whether it is unique and action-oriented;

• the description and when the tool should be used;

• required and optional input properties;

• types, formats, enums, defaults, and examples;

• whether the result is structured and predictable; and

• whether the description makes side effects clear.

Start with a safe read tool. Confirm that the generated input form matches the intended schema, then call the tool with a known test record. If the tool changes state, use a disposable record or a test environment and verify the state change independently in the original API.

Common tool problems include a missing required field, a parameter that is presented as a string but consumed as an integer, a vague description that makes similar tools indistinguishable, and a success response that hides an upstream error. An MCP tool can be discoverable and still be unusable if its schema does not match the handler.

Check resources

Resources are read-oriented MCP capabilities identified by a URI or URI template. Test that the server can:

1. list the resources it advertises;

2. read a known valid URI;

3. resolve a valid URI template when parameters are required;

4. reject an invalid or unauthorized URI safely; and

5. return the expected content type and useful content.

Check empty results, missing records, large responses, and tenant boundaries. A resource that is visible in discovery must still enforce the same access rules as the underlying API or data source.

Check prompts

Prompts are reusable message templates or instructions that an MCP client can request. Test that the prompt list is complete, required arguments are clear, optional arguments behave as documented, and the rendered result contains the intended context without secrets or internal debugging data.

If a prompt refers to a tool or resource, test the whole chain. A prompt may render successfully while pointing to a renamed tool, an unavailable resource, or an argument that no longer matches the current server configuration.

Test valid and invalid inputs

Use a test matrix rather than a single successful example. The goal is to confirm that the server accepts the right requests, rejects the wrong ones, and returns errors a person can act on.

Test both the MCP input schema and the upstream API validation. The MCP layer may reject a value before the API sees it, while the API may reject a value that passes the MCP schema. Both behaviors need useful error messages and safe handling.

Test API keys, Bearer tokens, and OAuth

Authentication testing has two boundaries. First, confirm that the MCP client can connect to the MCP endpoint. Then confirm that the credential used for the tool call is accepted by the original API and has the right scope.

API keys

Use a test API key with the smallest useful permission set. Depending on the Inspector client and API, provide the header through client settings or a runtime header such as:

npx @modelcontextprotocol/inspector --cli \
  --server-url https://mcp.example.com/mcp \
  --transport http \
  --header "X-API-Key: <test-api-key>" \
  --method tools/list

The header name is API-specific. Test a valid key, missing key, incorrect key, revoked key, and a key that is valid but lacks access to the selected operation. Do not commit <test-api-key> with a real value or place the secret in a tool argument.

Bearer tokens

Bearer tokens are commonly sent in the Authorization header:

Authorization: Bearer <test-access-token>

Test a valid token, an expired token, a token with the wrong audience, a token with insufficient scope, and a token for the wrong tenant or user. A token can be authentic and still be unauthorized for a tool call. Confirm that the error is handled without returning the token or the full authorization header.

OAuth

If the MCP server or upstream API uses OAuth, test the complete authorization flow rather than pasting a long-lived token once. Verify consent or sign-in, redirect handling, scope selection, access-token expiry, refresh or reauthorization, and revocation.

The current Inspector provides an OAuth flow for supported servers and stores local OAuth state so a session can be reused. Treat that state and any client configuration as sensitive. Use the Inspector authorization settings and the server's own documentation; do not put client secrets or refresh tokens in a repository file.

For an API-backed server using runtime pass-through, existing API authentication continues to be used. The MCP client supplies the runtime API key, Bearer token, or OAuth credential, and the request is passed to the original API. A successful MCP connection is therefore not enough: make a real authenticated tool call and verify the original API's tenant, role, scope, and record authorization.

How to find connection, authentication, and schema errors

Classify the failure before changing configuration. Different layers produce similar-looking errors, but the fix is usually different.

For a missing capability, first confirm that the server actually published the current configuration. Then compare the imported definition, selected operations, and generated capability names. If the definition contains invalid or incomplete schemas, fix the original API specification and republish the version rather than trying to hide the error in the client.

The MCP connection troubleshooting guide and tool discovery troubleshooting guide help isolate the first two layers. For broader failure handling, see the error-handling and debugging guide.

How a hosted Playground fits into testing

For teams using 0mcp, the Playground adds a hosted, product-level test after the protocol-level checks in Inspector. Import a supported OpenAPI, Swagger, or Postman definition, select the operations to expose, publish a server version, and use the Playground to inspect tools, call tools, test resources and prompts, verify authentication, and inspect individual usage logs.

The Playground documentation recommends having a published server version, an AI provider API key when required, and any upstream API credentials needed by the server. That makes the Playground useful for checking the real API-to-MCP path, not just whether a local process responds to tools/list.

Use both tools for different jobs:

When the capability set and test plan are ready, the API-to-MCP page explains the hosted workflow for turning a supported API definition into a focused MCP server.

What MCP Inspector does not prove

Passing Inspector tests is an important release gate, but it is not a complete production certification. Add separate tests for:

• concurrent requests, throughput, latency, and rate-limit behavior;

• upstream API availability, retries, timeouts, and pagination;

• tenant isolation, role changes, field-level access, and destructive actions;

• credential rotation, revocation, expiry, and OAuth reauthorization;

• sensitive data exposure in logs, errors, traces, prompts, and tool results;

• configuration versioning and rollback; and

• the behavior of the actual MCP clients your customers use.

Keep a small repeatable Inspector smoke suite for every server update. Then use the hosted Playground and a representative client for the user workflow. Testing once after generation is not enough if the API definition, selected operations, authentication configuration, or capability descriptions change.

Conclusion

Testing an MCP server means checking the whole path: connection, initialization, capability discovery, schemas, valid and invalid inputs, credentials, authorization, upstream errors, and the user workflow. MCP Inspector gives teams a repeatable way to inspect local or remote servers, while a hosted Playground can validate the published configuration and real API connection.

Run the checklist after every meaningful API, capability, authentication, or configuration change. A server should not be considered production-ready because it starts; it should be ready because its expected behavior and failure modes have been exercised and understood.