Copy page

Connect MCP clients

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 — the official tool from the MCP project. Best for quick checks and basic OAuth flow validation.
• 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 is the official testing UI from the MCP project. Run it with npx:

Code
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.

MCPJam Inspector

The MCPJam Inspector is a third-party testing and evaluation platform. It runs three ways:

• Hosted web app — open 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 (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/<route> 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.

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 /__zuplo/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.

Related

• Connect clients overview — production MCP clients (Claude Desktop, Cursor, ChatGPT, VS Code).
• Manual OAuth testing — drive the gateway's OAuth endpoints with curl for low-level verification.
• Troubleshooting — symptoms and fixes for the issues you'll hit while testing.