add MCP Inspector migration guide#3170
Conversation
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
dosubot
Bot
added
the
size:M
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
Internal previewPreview URL: https://mcp-inspector-pr-3170.up.railway.app |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed across 3 files
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
WalkthroughAdded a documentation page comparing MCP Inspector and MCPJam Inspector, including feature mappings, walkthrough content, server connection steps for HTTP and STDIO transports, and guidance on continued MCP Inspector usage. Added the page to the Get Started navigation and linked it from the getting-started page. Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
ESLint install timed out. The project may have too many dependencies for the sandbox. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/coming-from-mcp-inspector.mdx`:
- Line 7: Update the migration guidance in the page introduction and the
instructions covering http://localhost and STDIO to distinguish hosted MCPJam
from desktop/terminal clients. State that hosted MCPJam supports HTTPS only and
cannot connect to local STDIO, while desktop/terminal clients support local
STDIO; revise the one-to-one configuration claim accordingly.
- Line 41: Update the transport label in the MCP Inspector setup instructions to
use “Streamable HTTP” instead of “SSE/HTTP,” or explicitly identify “SSE/HTTP”
as a legacy compatibility label while preserving the existing URL and selection
guidance.
- Around line 28-29: Update the OAuth terminology in the comparison table around
“Auth configuration” to use “OAuth 2.1” instead of “OAuth 2.0,” including the
flow description where applicable, while preserving the existing authentication
options and links.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 988d3a77-3148-44fd-b8d2-10629a7c15c2
📒 Files selected for processing (3)
docs/coming-from-mcp-inspector.mdxdocs/docs.jsondocs/getting-started.mdx
| | Auth configuration | Before connecting, you set Custom Headers (e.g. an Authorization Bearer token) and OAuth 2.0 Flow fields (Client ID, Client Secret, Redirect URI) in the connection sidebar. | Auth is chosen per server when [adding a server](/inspector/connecting-servers) — No Authentication, Bearer Token, or OAuth 2.0 — and saved with the server entry for reconnects. | | ||
| | OAuth debugging | No dedicated flow view: a bad or missing token fails at connection time with the server's error message (e.g. invalid_token, 401). | [**Guided OAuth Testing**](/inspector/guided-oauth) runs the OAuth exchange step by step — metadata discovery, client registration, auth code, access token — so you can see which step fails. | |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== Relevant file =="
git ls-files 'docs/coming-from-mcp-inspector.mdx'
echo
echo "== OAuth mentions in docs =="
rg -n --hidden --glob 'docs/**' -e 'OAuth 2\.1|OAuth 2\.0|OAuth' .
echo
echo "== Target file excerpt =="
sed -n '1,120p' docs/coming-from-mcp-inspector.mdxRepository: MCPJam/inspector
Length of output: 2017
🌐 Web query:
MCP Inspector OAuth 2.1 terminology current product flow guided OAuth testing docs
💡 Result:
The MCP Inspector is a specialized developer tool used for testing, debugging, and inspecting Model Context Protocol (MCP) servers, including their OAuth 2.1 authentication implementations [1][2][3]. Terminology and Core Concepts The tool aligns with standard OAuth 2.1 framework terminology [4][5]. Key terms include: - Flow: The complete end-to-end authorization process, such as the Authorization Code flow (which now requires PKCE in OAuth 2.1) [6][7]. - Authorization Grant: The credential representing user authorization (e.g., an authorization code) [6][5]. - Dynamic Client Registration (DCR): A method used by MCP servers to automatically register clients [8][3]. - Client ID Metadata Documents (CIMD): A mechanism for clients to share metadata with authorization servers [9][10]. - Protected Resource Metadata: Information discovered by the inspector to facilitate secure connections [3]. Product Flow and Guided Testing The MCP Inspector supports two primary modes for testing OAuth: 1. Standard Connection Flow: - When connecting to an MCP server (typically via Streamable HTTP), the inspector identifies if the server requires authentication by following the WWW-Authenticate challenge [3]. - It discovers OAuth metadata, handles DCR (if supported), and manages the redirection of the user agent to the authorization server for consent [2][8][3]. - Once the user grants consent, the inspector completes the token exchange, stores the access token, and establishes the MCP session [2][3]. 2. Guided/Advanced OAuth Debugging: - Tools like the MCPJam Inspector offer a "Guided OAuth Debugger" designed to visualize the handshake process at every step [9][10]. - This guided flow allows developers to track protocol interactions, verify compliance with different OAuth 2.1 specifications, and debug issues like incorrect redirect URIs, scope mismatches, or token exchange failures [11][10]. - It provides a "Raw" view for inspecting specific JSON-RPC messages and network requests alongside the guided UI that explains the current step and expected behavior [9][10]. For effective testing, ensure your MCP server properly implements metadata discovery and supports standard OAuth 2.1 practices, such as PKCE and strict redirect URI matching [3][4][7]. If authorization fails, the Inspector's logs can reveal issues such as metadata discovery failures, invalid client registration, or 401 Unauthorized errors during the handshake [12][2][3].
Citations:
- 1: https://github.com/modelcontextprotocol/inspector?tab=readme-ov-file
- 2: https://github.com/bitovi/mcp-training/blob/main/training/4-mcp-inspector.md
- 3: https://zuplo.com/docs/mcp-gateway/test-clients
- 4: https://oauth.net/2.1/
- 5: https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/15/
- 6: https://aaronparecki.com/2024/03/29/3/oauth-terminology
- 7: https://drafts.oauth.net/oauth-v2-1/draft-ietf-oauth-v2-1.html
- 8: https://auth0.com/ai/docs/mcp/guides/test-your-mcp-server-with-mcp-inspector
- 9: https://github.com/MCPJam/inspector/blob/main/README.md
- 10: https://www.mcpjam.com/blog/oauth-debugger
- 11: MCP Inspector starts Authorization Code Flow with wrong redirect_uri modelcontextprotocol/inspector#930
- 12: Authenticating error with OAuth2.1 using FastMCP with AzureProvider modelcontextprotocol/inspector#783
Use OAuth 2.1 terminology here. docs/coming-from-mcp-inspector.mdx:28-29 — “OAuth 2.0 Flow fields” is stale; align the comparison text with the current Inspector wording.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/coming-from-mcp-inspector.mdx` around lines 28 - 29, Update the OAuth
terminology in the comparison table around “Auth configuration” to use “OAuth
2.1” instead of “OAuth 2.0,” including the flow description where applicable,
while preserving the existing authentication options and links.
There was a problem hiding this comment.
@prathmeshpatel, that's a sensible simplification — dropping the version number sidesteps future staleness if the spec revs again, and "OAuth" alone still reads clearly in the comparison table. Let's see what @Paoli99 thinks before locking it in.
✏️ Learnings added
Learnt from: prathmeshpatel
Repo: MCPJam/inspector PR: 3170
File: docs/coming-from-mcp-inspector.mdx:28-29
Timestamp: 2026-07-14T00:59:23.126Z
Learning: In docs/coming-from-mcp-inspector.mdx (and similar MCP Inspector vs MCPJam Inspector comparison docs), prefer the generic term "OAuth" instead of version-specific terminology like "OAuth 2.0" or "OAuth 2.1" to avoid staleness as the spec evolves. This preference was expressed by reviewer prathmeshpatel on PR `#3170`.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
prathmeshpatel
left a comment
prathmeshpatel
left a comment
There was a problem hiding this comment.
Thanks for the changes so far! I've got enough blocking enough that its worth a revision
| | Resources & prompts | The Resources and Prompts tabs list what the server exposes; selecting an item fetches and displays its content. | The **Resources** and **Prompts** tabs list each server's resources (with location and mimetype) and prompts (with params); selecting an item reads or fetches its content. | | ||
| | Protocol logs | The History panel records every protocol call (initialize, tools/list, tools/call...) in order; expanding an entry shows the raw JSON request and response. | [**Tracing & debugging**](/inspector/debugging) logs every message sent between MCPJam and your server, tagged with `ERROR` / `WARNING` / `TRACE` levels. | | ||
| | Auth configuration | Before connecting, you set Custom Headers (e.g. an Authorization Bearer token) and OAuth 2.0 Flow fields (Client ID, Client Secret, Redirect URI) in the connection sidebar. | Auth is chosen per server when [adding a server](/inspector/connecting-servers) — No Authentication, Bearer Token, or OAuth 2.0 — and saved with the server entry for reconnects. | | ||
| | OAuth debugging | No dedicated flow view: a bad or missing token fails at connection time with the server's error message (e.g. invalid_token, 401). | [**Guided OAuth Testing**](/inspector/guided-oauth) runs the OAuth exchange step by step — metadata discovery, client registration, auth code, access token — so you can see which step fails. | |
There was a problem hiding this comment.
[do] Would simplify to Not available
| | Protocol logs | The History panel records every protocol call (initialize, tools/list, tools/call...) in order; expanding an entry shows the raw JSON request and response. | [**Tracing & debugging**](/inspector/debugging) logs every message sent between MCPJam and your server, tagged with `ERROR` / `WARNING` / `TRACE` levels. | | ||
| | Auth configuration | Before connecting, you set Custom Headers (e.g. an Authorization Bearer token) and OAuth 2.0 Flow fields (Client ID, Client Secret, Redirect URI) in the connection sidebar. | Auth is chosen per server when [adding a server](/inspector/connecting-servers) — No Authentication, Bearer Token, or OAuth 2.0 — and saved with the server entry for reconnects. | | ||
| | OAuth debugging | No dedicated flow view: a bad or missing token fails at connection time with the server's error message (e.g. invalid_token, 401). | [**Guided OAuth Testing**](/inspector/guided-oauth) runs the OAuth exchange step by step — metadata discovery, client registration, auth code, access token — so you can see which step fails. | | ||
| | Natural-language tool calls | Not available. | The [**LLM Playground**](/inspector/llm-playground) connects a model of your choice to your server; you type a request in plain language and watch which tool the model calls, with what arguments, and what it answers. You can set the system prompt and temperature to simulate an agent. | |
There was a problem hiding this comment.
[do] Feels like we haven't properly called this out but we absolutely should, Clients mimic all capabilities of major AI clients beyond just the model (but notably, including models)
Worth calling out. Taking a pass at Clients page to update and add screenshots would be great too!
| | Manual tool execution | Open the Tools tab, click List Tools, select one, fill its typed arguments in a form, and run it. The result appears as the raw structured content returned by the server. | Open the [**Tools**](/inspector/tools-prompts-resources) tab, search or pick a tool from the list, fill its params, and hit Execute. The return value appears below, and you can save a request to re-run it later with the same params. | | ||
| | Resources & prompts | The Resources and Prompts tabs list what the server exposes; selecting an item fetches and displays its content. | The **Resources** and **Prompts** tabs list each server's resources (with location and mimetype) and prompts (with params); selecting an item reads or fetches its content. | | ||
| | Protocol logs | The History panel records every protocol call (initialize, tools/list, tools/call...) in order; expanding an entry shows the raw JSON request and response. | [**Tracing & debugging**](/inspector/debugging) logs every message sent between MCPJam and your server, tagged with `ERROR` / `WARNING` / `TRACE` levels. | | ||
| | Auth configuration | Before connecting, you set Custom Headers (e.g. an Authorization Bearer token) and OAuth 2.0 Flow fields (Client ID, Client Secret, Redirect URI) in the connection sidebar. | Auth is chosen per server when [adding a server](/inspector/connecting-servers) — No Authentication, Bearer Token, or OAuth 2.0 — and saved with the server entry for reconnects. | |
There was a problem hiding this comment.
We simplify to just OAuth since we support OAuth 2.1 as well. I'd add Cross-App Access support too
| | Auth configuration | Before connecting, you set Custom Headers (e.g. an Authorization Bearer token) and OAuth 2.0 Flow fields (Client ID, Client Secret, Redirect URI) in the connection sidebar. | Auth is chosen per server when [adding a server](/inspector/connecting-servers) — No Authentication, Bearer Token, or OAuth 2.0 — and saved with the server entry for reconnects. | | ||
| | OAuth debugging | No dedicated flow view: a bad or missing token fails at connection time with the server's error message (e.g. invalid_token, 401). | [**Guided OAuth Testing**](/inspector/guided-oauth) runs the OAuth exchange step by step — metadata discovery, client registration, auth code, access token — so you can see which step fails. | |
|
|
||
| ## When to keep using MCP Inspector | ||
|
|
||
| MCP Inspector remains a good fit as a lightweight, zero-setup protocol checker — especially its CLI mode for scripting protocol-level checks in CI with pass/fail exit codes. If all you need is verifying that a server initializes and its tools respond according to the spec, it does the job. |
There was a problem hiding this comment.
[try] would simplify, the "especially its CLI" is interesting given our CLI is so much more robust than inspector's that its not worth calling out specifically
My copy suggestion:
"MCP Inspector remains a good fit as a lightweight protocol and deterministic response checker. If all you need is verifying that a server initializes and its tools respond according to the spec, it does the job!"
| Step through your MCP authorization flow and inspect each stage. Check conformance across protocol versions (03-26, 06-18, 11-25) and client registration paths: Dynamic Client Registration (DCR), client pre-registration, and CIMD. | ||
| </Card> | ||
| <Card title="Coming from MCP Inspector?" icon="arrow-right-left" href="/coming-from-mcp-inspector"> | ||
| Direct feature mapping, comparison video, connection steps for your existing server config, and a short note on when to keep using MCP Inspector. |
There was a problem hiding this comment.
[inquiry] Are you adding the comparison video in this PR or another one?
3 participants
Summary by cubic
Adds a migration guide for users moving from MCP Inspector to MCPJam Inspector. Covers feature mapping, connection steps (HTTP/STDIO and auth), and when to keep using MCP Inspector; linked in docs nav and Getting Started.
docs/coming-from-mcp-inspector.mdxwith a comparison video, feature mapping, connection steps (HTTP, STDIO, auth), HTTPS-only note for the hosted app (desktop/terminal for localhost/STDIO), and CLI/CI guidance.docs.jsonand linked as a card on Getting Started.Written for commit 4e42777. Summary will update on new commits.