Guides / For developers

Test with the MCP Inspector

Connect the official MCP Inspector to Zorlya to see every request and answer, try tools by hand and find out why a client will not connect.

4 min read. Updated .

To test Zorlya with the MCP Inspector, run npx @modelcontextprotocol/inspector --server-url https://mcp.zorlya.com --transport http, then connect and sign in. The Inspector shows every message and lets you call tools by hand. Registration may be refused, because the Inspector is not on Zorlya’s list of AI apps.

What you need

  • Node 22.19.0 or newer. The Inspector’s documentation names that version.
  • A Zorlya account and a browser, because the Inspector signs in the way any client does.

Open it

The Inspector runs through npx, so there is nothing to install:

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

It prints an address with a per-launch token and opens it in your browser. The --transport http option selects Streamable HTTP, which is what Zorlya speaks. For a script or a CI job there is a command line mode with the same connection:

npx @modelcontextprotocol/inspector --cli https://mcp.zorlya.com --transport http --method tools/list

Sign in

Connect, and the Inspector follows the same steps as Sign in with OAuth by hand:

  1. It calls https://mcp.zorlya.com, gets 401 with resource_metadata, and reads the two discovery documents.
  2. It registers itself through dynamic client registration.
  3. It opens Zorlya’s Connect page in your browser. You choose the account and the permission level, and sign in.
  4. It receives the code on its own callback address and trades it for tokens.

The Inspector’s callback addresses are loopback http addresses: http://127.0.0.1:6274/oauth/callback for the web client and http://127.0.0.1:6276/oauth/callback for the command line mode, according to its documentation. Zorlya registers only clients whose return address belongs to an AI app on its list. The Inspector is not on the list, and its default callback path, /oauth/callback, is not the path Zorlya allows for any loopback app, which is /callback. So registration is likely refused as it is. Setting --callback-url to a loopback address with the path /callback, such as http://127.0.0.1:6274/callback, would match the entry for Claude Code, and the Connect page would then show the name Claude Code. We have not tried either.

The Inspector keeps your tokens in the operating system keychain when there is one. Without a keychain it writes them to ~/.mcp-inspector/secrets.json, unencrypted unless you supply a key. Treat that file like a password, and clear it with the Inspector’s Clear OAuth state and disconnect action when you are done. Clearing also revokes the grant at Zorlya.

What to try

  • Tools tab. List the tools, pick top_matches, type { "limit": 3 } and run it. The result shows the text and the structured form side by side.
  • Network and Protocol tabs. Watch the request and answer for each call. This is the quickest way to see exactly what your own client should send.
  • Resources and Prompts. Read zorlya://profile and render assess_fit with a job_id from top_matches.
  • A deliberate mistake. Call get_job with no arguments, and call save_job on a read-only grant, which answers 403 with insufficient_scope. Compare what you see with Page results and handle errors.

Protocol era

The Inspector can speak an older or a newer revision of the protocol. Its documented default, legacy, sends a plain initialize, and that is what Zorlya answers. Zorlya accepts the 2026-07-28 revision as well as 2025-06-18 and older ones. With modern, which pins 2026-07-28, the Inspector must send the Mcp-Method header on every request and Mcp-Name on tools/call, resources/read and prompts/get. A missing or mismatched header is refused with the JSON-RPC error -32020. We have not tried modern against Zorlya, so start with legacy.

If it will not connect

Table
What you see Likely cause
404 on the first request MCP is switched off on that instance, or you used a path. The address is https://mcp.zorlya.com with no path. See What the MCP server offers
Registration is refused The callback address does not belong to an AI app on Zorlya’s list
Sign-in does not finish The account has not been approved, or a job seeker account is on Free or Plus. Only an approved account on a plan with AI client access (Pro) can connect
The web client hangs after connecting The Inspector opens a notification stream with GET after initialize, and Zorlya answers 405. The Inspector has a setting called Suppress Notification Stream for servers that cannot serve a second request. Turn it on. We did not test this

What we checked

The Inspector steps, flags, callback addresses and secret storage come from its documentation on modelcontextprotocol.io, read on 2026-10-17. We did not run the Inspector against Zorlya. The server behaviour in the table comes from calls to a local copy of the server.

Sources: