# Test clients A regular MCP client like Claude Desktop or Cursor is great for using a gateway, but not for testing one. Test clients show you what's actually on the wire: the OAuth handshake, every JSON-RPC request and response, error payloads, and the tool definitions the gateway returned. Two tools cover most testing needs: - **[MCP Inspector](#mcp-inspector)** — the official tool from the MCP project. Best for quick checks and basic OAuth flow validation. - **[MCPJam Inspector](#mcpjam-inspector)** — a third-party tool with a hosted web app, desktop builds, and deeper OAuth debugging. Best when you want to drive a real chat against the gateway or trace OAuth conformance issues. Both speak Streamable HTTP and complete the gateway's OAuth flow end to end. ## MCP Inspector The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is the official testing UI from the MCP project. Run it with `npx`: ```bash npx @modelcontextprotocol/inspector ``` The inspector opens in your browser. In the **Server connection** pane: 1. Set the transport to **Streamable HTTP**. 2. Paste your MCP route URL — for example `https://my-gateway.zuplo.dev/mcp/linear-v1`. 3. Click **Connect**. The inspector follows the gateway's `WWW-Authenticate` challenge, fetches the Protected Resource Metadata document, registers a client via Dynamic Client Registration, and opens a browser tab for the gateway's consent flow. Once you complete login and consent, the inspector receives an access token and starts the MCP session. From there you can: - Browse **Tools**, **Prompts**, and **Resources** that the upstream exposes through the gateway. - Call a tool with arbitrary arguments and see the raw JSON-RPC response (including any `isError: true` payloads). - Watch the **Notifications** pane for `notifications/tools/list_changed` events. - Step through edge cases — invalid inputs, missing arguments, large payloads — and check how the gateway propagates errors. :::tip The MCP Inspector is great for a quick sanity check. If you need to debug a stuck OAuth flow or test multiple clients at once, the MCPJam Inspector below has deeper tooling for both. ::: ## MCPJam Inspector The [MCPJam Inspector](https://www.mcpjam.com) is a third-party testing and evaluation platform. It runs three ways: - **Hosted web app** — open [app.mcpjam.com](https://app.mcpjam.com) in your browser, no install required. HTTPS MCP server URLs only. - **Terminal** — `npx @mcpjam/inspector@latest`. Requires Node.js 20+. - **Desktop** — download from the [GitHub releases page](https://github.com/MCPJam/inspector/releases) (Mac and Windows builds). For a Zuplo MCP Gateway running in production, the hosted web app is the fastest path. Paste your route URL, complete the gateway's OAuth flow in the popup, and you're connected. For a local `zuplo dev` gateway, use the terminal or desktop builds — they accept `http://127.0.0.1:9000/` URLs that the hosted app rejects. Once connected, MCPJam exposes a few features the official Inspector doesn't: - **OAuth Debugger** with guided conformance checks for the gateway's authorization endpoints — useful when an MCP client is misbehaving and you want to know whether the gateway's responses are spec-compliant. - **Chat** — run a real LLM conversation through the gateway with full trace visibility into every tool call and result. - **Evals** — record tool-call test cases and replay them. - **CLI and SDK** — script tests against the gateway, optionally as part of CI/CD via the [GitHub Action](https://github.com/MCPJam/inspector#cicd-integration). ## What to look for when testing Whichever tool you pick, exercise these gateway behaviors during a smoke test: 1. **Unauthenticated request returns `401`.** Hit the route without a token first; the response should include `WWW-Authenticate: Bearer resource_metadata=...`. If it doesn't, the route is missing an MCP OAuth policy. 2. **OAuth handshake completes.** Confirm the inspector lands on the gateway's `/oauth/setup` consent page (rendered HTML), that the upstream's **Connect** button works, and that the inspector receives an access token. 3. **`tools/list` returns the expected curated set.** If you've attached `mcp-capability-filter-inbound`, verify the filter is working — only allow-listed tools should appear. 4. **Tool calls succeed and errors round-trip.** Run one successful tool call and one that triggers an upstream error to confirm the gateway forwards both correctly. 5. **Connect-required for a fresh user.** Sign in as a different user and verify the first call returns a JSON-RPC connect-required error pointing at the gateway's upstream connect URL. 6. **Reconsent flows.** Revoke the gateway's client in the upstream provider's dashboard, retry the tool call, and confirm the inspector surfaces the `reconsent_required` state. For deeper testing — including manual `curl` walkthroughs of the OAuth flow — see [Manual OAuth testing](./auth/manual-oauth-testing.mdx). ## Related - [Connect clients overview](./connect-clients/overview.mdx) — production MCP clients (Claude Desktop, Cursor, ChatGPT, VS Code). - [Manual OAuth testing](./auth/manual-oauth-testing.mdx) — drive the gateway's OAuth endpoints with `curl` for low-level verification. - [Troubleshooting](./troubleshooting.mdx) — symptoms and fixes for the issues you'll hit while testing.