MCP Inspector: debug an unlob connection

Run it

npx @modelcontextprotocol/inspector

It opens a browser UI. Choose Streamable HTTP, then:

URL:     https://api.unlob.com/mcp
Header:  x-api-key: ulb_…

Connect. List Tools should show the profile’s tools: two on ?profile=grounding, all of them by default.

What it is for

Every other MCP client fails the same way: an empty tool list and no error. The Inspector shows you the actual frames — the initialize result, the negotiated protocol version, the raw responses — so you find out which step failed instead of guessing.

The decision it gives you is binary and useful:

Inspector lists the tools → the server and your key are both fine. The problem is in the other client’s configuration.
Inspector fails too → it is the server, the key, or the network, and the frame it shows you says which.

Doing this first saves more time than any amount of re-reading a config file.

Call a tool

Pick web_search, set query to something, and run it. You will see both the text content block and the structuredContent — the same payload, parsed, for clients that can use it.

It is also the fastest way to read a tool’s schema while writing a prompt, since it renders inputSchema directly.

The stdio server

To inspect a locally running stdio server instead, choose STDIO and give it the command. Useful when self-hosting against a local index.

Reading a `429` in the response pane

Call a tool against an exhausted key and the Inspector shows you the raw error rather than a generic client failure — which is exactly the detail an ordinary client swallows. Look for the retry-after header in the frame:

Present — a per-minute rate limit. The call will succeed again in about the number of seconds named.
Absent — the key is hard-capped and out of credits for that call. No amount of retrying in the Inspector or anywhere else changes that until the billing period rolls over.

This is the fastest way to settle an argument about which one you are looking at, because every other client in this section just reports “the tool failed” and leaves you guessing. 402, if you see it, means the account itself is suspended — a different failure again, and Rate limits and credits covers all three in one table.

Comparing the client you are debugging

Run the same tool call in the Inspector and in the client that is failing, side by side. Same arguments, same key. If the Inspector’s response body matches what your other client eventually does — once it produces one at all — the server is not the problem, and the difference is in how that client renders or discards the result. If the two responses genuinely differ, save both frames before reporting it; a “the tools are listed, but one client saw ten” report is far easier to act on with the actual JSON than with a description of it.

This is worth doing before assuming a bug in your own agent code, too. Every framework guide on this site — the LangChain, CrewAI, Mastra and Pydantic AI pages among them — routes through the same tools and the same server, so a schema mismatch or a missing field that shows up in one framework’s tool call almost always shows up in the Inspector’s raw call as well, which tells you in one step whether the framework’s adapter is misreading a correct response or the server sent something unexpected in the first place.