AgenticBook
Back to Handbook
Chapter 05 · Hands-on LabIssue 02 · November 2026

Debug an MCP server with MCP Inspector

A repeatable local workflow for connecting to a reference server, inspecting its advertised surface, testing calls, and checking the security boundaries before you ship.

01

Start with a reference server

Use a harmless local example first; do not begin by connecting an unknown remote server or production credential.

The MCP project’s maintained server repository includes a Memory reference server that can be launched through npx. The project explicitly says its reference implementations are educational examples, not production-ready services. Use it to learn the handshake and tool inspection workflow, then replace it with your own server and threat model before relying on it.

  • Use a disposable local environment and a non-sensitive test dataset.
  • Confirm the package name and setup command against the repository README before running it.
  • Treat the server process as code with the permissions of the account that launches it.
Editor's takeaway

A reference server is a protocol-learning aid, not a security review or a production dependency approval.

02

Inspect, call, and record the protocol surface

A successful connection is only the first check; inspect what the server exposes and how it behaves at the edges.

Launch the Inspector web interface, connect to the local stdio server, and enumerate tools, resources, and prompts. For each tool, check the input schema, required fields, returned content, and error behavior. Test one valid call, one invalid argument, an empty result, a slow response, and a large response. If the server will be used in automation, use the Inspector CLI and a repeatable fixture rather than relying only on screenshots or manual clicks.

  • Record the server version, transport, capabilities, and test date.
  • Verify the server cannot read or write paths outside its intended scope.
  • Capture the request and response shape with secrets and personal data redacted.
Editor's takeaway

Test the contract and boundary conditions, not just whether the UI displays a green connected state.

03

Handle Inspector secrets deliberately

Developer tooling can store credentials; a local test UI is still part of your security boundary.

The Inspector README says OAuth tokens, client secrets, and stdio environment values are stored in the OS keychain when available. On headless or keychain-less environments, the fallback file may be unencrypted unless a key is provided. Do not use real production credentials in shared demos, containers, recorded sessions, or CI unless you have configured and verified the secret store for that environment.

  • Use short-lived, least-privilege credentials for integration tests.
  • Check the Inspector secret-storage documentation before using it over SSH or inside a container.
  • Avoid committing config files or terminal transcripts that contain tokens.
Editor's takeaway

Before testing a server, decide where the test client will store credentials and who can read them.

Launch a local reference server and Inspector

# Launch the MCP Inspector Web UI
npx @modelcontextprotocol/inspector

# In the UI, add a local stdio server with:
# command: npx
# args: -y @modelcontextprotocol/server-memory

# Scriptable CLI for a built stdio server (replace the entry point)
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

The Inspector starts the configured stdio process. Replace node build/index.js with your server entry point and check the current README for config and CLI options.

Primary sources

First-party repositories and documentation used for this chapter. Check the upstream README and release notes before implementation.

More chapters