9d5110f8f4
Break up v2_ux.md (1400+ lines) into smaller, focused documents: - v2_ux.md - Core UX (overview, server list, modals) - v2_ux_features.md - Feature screens (Tools, Resources, etc.) - v2_ux_handlers.md - Client handlers, form generation, errors - v2_screenshots.md - Visual reference with Shadcn prototype screenshots Add screenshots from Shadcn prototype to specification/screenshots/. Update navigation headers across all spec files. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
34 KiB
34 KiB
Inspector V2 UX Specification
Brief | V1 Problems | V2 Scope | V2 Tech Stack
UX: Overview | Features | Handlers | Screenshots
Table of Contents
Additional UX Documentation:
- Feature Screens - Tools, Resources, Prompts, Logging, Tasks, History
- Handlers & Patterns - Sampling, Elicitation, Roots, Form Generation, Error Handling
- Visual Reference - Screenshots from the Shadcn prototype
Design Principles
- Single server connection - No multiple concurrent connections (defer to plugins)
- MCPJam-inspired - Use MCPJam Inspector as UX reference model
- Full-width content - Maximize screen real estate for each section
- No sidebar - Deferred until menu becomes cumbersome or extensions multiply
- Progressive disclosure - Show relevant information at each connection stage
- Resizable panels - Allow users to adjust panel sizes on feature screens
Navigation Model
+-------------------------------------------------------------------------------------+
| [Server Name v] (*) Connected (23ms) [Tools] [Resources] [Prompts] [Logs] [Tasks] [History] [Disconnect] |
+-------------------------------------------------------------------------------------+
| |
| Full-width content |
| |
+-------------------------------------------------------------------------------------+
- Menu bar displays server name, connection status with latency, and disconnect button when connected
- Top navigation links to Tools, Resources, Prompts, Logs, Tasks, and History sections
- Connection indicator shows latency from periodic
pingrequests - No sidebar - content areas use full width
Screen Flows
Server List (Home)
Initial screen shown when no server is connected. Displays server cards in a responsive grid (1-2 columns).
+---------------------------------------------------------+
| MCP Inspector |
| [+ Add Server v] |
+---------------------------------------------------------+
| |
| +-------------------------+ +-------------------------+
| | Server Card 1 | | Server Card 2 |
| | (see below) | | (see below) |
| +-------------------------+ +-------------------------+
| |
| +-------------------------+ |
| | Server Card 3 | |
| +-------------------------+ |
| |
+---------------------------------------------------------+
Add Server Options:
- Add manually - Opens form modal for manual configuration
- Import config - Paste/upload internal
mcp.jsonconfig - Import server.json - Import MCP Registry format (Issue #922)
Functionality:
- List servers from
mcp.jsonconfig file - Add/edit/delete servers via CRUD endpoints on proxy
- Responsive grid layout (1 column mobile, 2 columns desktop)
Server Connection Card
Each server in the list is displayed as a card with connection controls and status.
+-----------------------------------------------------------------+
| [Icon] Server Name v1.0.0 |
| STDIO [Via Proxy v] (*) Connected [Toggle] |
+-----------------------------------------------------------------+
| npx -y @modelcontextprotocol/server-everything [Copy] |
+-----------------------------------------------------------------+
| [Server Info] [Settings] [Clone] [Edit] [Remove] |
+-----------------------------------------------------------------+
Connection Mode Dropdown:
- Quick access to switch between Direct and Via Proxy modes without opening Settings
- STDIO servers default to "Via Proxy" (required - cannot connect directly from browser)
- HTTP/SSE servers default to "Direct" (assumes CORS enabled)
- Shows warning text if STDIO + Direct selected: "(STDIO requires proxy)"
With OAuth (shows OAuth Debug button):
+-----------------------------------------------------------------+
| [Icon] Server Name v1.0.0 |
| HTTP [Direct v] (*) Connected [Toggle] |
+-----------------------------------------------------------------+
| https://api.example.com/mcp [Copy] |
+-----------------------------------------------------------------+
| [Server Info] [Settings] [OAuth Debug] [Clone] [Edit] [Remove] |
+-----------------------------------------------------------------+
With Error State:
+-----------------------------------------------------------------+
| [Icon] Server Name v1.0.0 |
| HTTP [Direct v] (!) Failed (3) [Toggle] |
+-----------------------------------------------------------------+
| https://api.example.com/mcp [Copy] |
+-----------------------------------------------------------------+
| [Server Info] [Settings] [Clone] [Edit] [Remove] |
+-----------------------------------------------------------------+
| [!] Connection timeout after 20s |
| [Show more] [View Troubleshooting Guide] |
+-----------------------------------------------------------------+
Status Indicators:
| Status | Indicator | Display |
|---|---|---|
| Connected | Green dot | "Connected" |
| Connecting | Yellow pulsing dot | "Connecting..." |
| Failed | Red dot | "Failed (N)" with retry count |
| Disconnected | Gray dot | "Disconnected" |
Card Actions:
- Toggle switch - Connect/disconnect the server
- Copy - Copy command/URL to clipboard
- Server Info - Opens server info modal
- Settings - Opens server settings modal (see below)
- OAuth Debug - Opens OAuth debugger modal (visible when server uses OAuth)
- Clone - Duplicates server config for creating variants
- Edit - Opens edit server modal
- Remove - Deletes server (with confirmation)
Server Settings Modal
Per-server configuration for connection behavior, headers, metadata, timeouts, and OAuth credentials.
+---------------------------------------------------------------------------+
| Server Settings: my-server [x] |
+---------------------------------------------------------------------------+
| |
| Connection Mode |
| +-----------------------------------------------------------------------+ |
| | Via Proxy v | |
| +-----------------------------------------------------------------------+ |
| Direct - Connect directly to server (requires CORS support) |
| Via Proxy - Route through inspector proxy (required for STDIO) |
| |
| ---------------------------------------------------------------------------
| |
| Custom Headers |
| +-----------------------------------------------------------------------+ |
| | Authorization | Bearer sk-... [Remove]| |
| | X-Custom-Header | custom-value [Remove]| |
| +-----------------------------------------------------------------------+ |
| [+ Add Header] |
| |
| ---------------------------------------------------------------------------
| |
| Request Metadata |
| Metadata sent with every MCP request to this server. |
| +-----------------------------------------------------------------------+ |
| | session_id | abc123 [Remove]| |
| +-----------------------------------------------------------------------+ |
| [+ Add Metadata] |
| |
| ---------------------------------------------------------------------------
| |
| Timeouts |
| +-----------------------------------+-----------------------------------+ |
| | Connection Timeout | Request Timeout | |
| | +-----------------------------+ | +-----------------------------+ | |
| | | 30000 ms| | | 60000 ms| | |
| | +-----------------------------+ | +-----------------------------+ | |
| +-----------------------------------+-----------------------------------+ |
| |
| ---------------------------------------------------------------------------
| |
| OAuth Settings (for servers requiring authentication) |
| +-----------------------------------------------------------------------+ |
| | Client ID | |
| | +-------------------------------------------------------------------+ | |
| | | my-client-id | | |
| | +-------------------------------------------------------------------+ | |
| | | |
| | Client Secret | |
| | +-------------------------------------------------------------------+ | |
| | | ******** [Show/Hide] | | |
| | +-------------------------------------------------------------------+ | |
| | | |
| | Scopes | |
| | +-------------------------------------------------------------------+ | |
| | | read write profile | | |
| | +-------------------------------------------------------------------+ | |
| +-----------------------------------------------------------------------+ |
| |
| [Cancel] [Save Settings] |
+---------------------------------------------------------------------------+
Connection Mode:
- Direct - Browser connects directly to server (requires server to have CORS headers)
- Via Proxy - Route through inspector proxy (required for STDIO transport, useful for CORS-restricted servers)
Custom Headers:
- Key-value pairs sent with every HTTP request to this server
- Useful for API keys, authorization tokens, custom routing
Request Metadata:
- Data included in
_metafield of every MCP request - Per-server isolation (previously stored globally in localStorage)
Timeouts:
- Connection Timeout - Max time to establish connection (ms)
- Request Timeout - Max time for individual requests (ms)
OAuth Settings:
- Pre-configure OAuth credentials for servers requiring authentication
- Client ID and Client Secret for OAuth 2.0 flows
- Scopes to request during authorization
Clone Functionality: The [Clone] button on the server card creates a duplicate configuration, enabling:
- Testing same server with different headers/metadata
- Comparing behavior with different timeout settings
- Maintaining separate OAuth credentials for different environments
Import server.json Modal
Support for importing MCP Registry server.json format for testing servers before publishing.
+-----------------------------------------------------------------------------+
| Import MCP Registry server.json [x] |
+-----------------------------------------------------------------------------+
| |
| Paste server.json content or drag and drop a file: |
| +-------------------------------------------------------------------------+ |
| | { | |
| | "$schema": "https://static.modelcontextprotocol.io/schemas/...", | |
| | "name": "io.github.user/my-server", | |
| | "description": "A sample MCP server", | |
| | "version": "1.0.0", | |
| | "packages": [{ | |
| | "registryType": "npm", | |
| | "identifier": "my-mcp-server", | |
| | "runtimeHint": "npx", | |
| | "transport": { "type": "stdio" }, | |
| | "environmentVariables": [ | |
| | { "name": "API_KEY", "description": "API key", "required": true } | |
| | ] | |
| | }] | |
| | } | |
| +-------------------------------------------------------------------------+ |
| [Browse...] [Clear]|
| |
| --------------------------------------------------------------------------- |
| |
| Validation Results: |
| +-------------------------------------------------------------------------+ |
| | [check] Schema validation passed | |
| | [check] Package found: my-mcp-server (npm) | |
| | [warn] Environment variable API_KEY not set | |
| | [info] Runtime hint: npx | |
| | [info] Transport: stdio | |
| +-------------------------------------------------------------------------+ |
| |
| --------------------------------------------------------------------------- |
| |
| Package Selection (if multiple packages): |
| +-------------------------------------------------------------------------+ |
| | (*) npm: my-mcp-server (npx) | |
| | ( ) pypi: my-mcp-server (uvx) | |
| +-------------------------------------------------------------------------+ |
| |
| Environment Variables: |
| +-------------------------------------------------------------------------+ |
| | API_KEY * Description: API key | |
| | +---------------------------------------------------------------------+ | |
| | | sk-... | | |
| | +---------------------------------------------------------------------+ | |
| | | |
| | OPTIONAL_VAR Description: Optional setting | |
| | +---------------------------------------------------------------------+ | |
| | | | | |
| | +---------------------------------------------------------------------+ | |
| +-------------------------------------------------------------------------+ |
| |
| Server Name (optional override): |
| +-------------------------------------------------------------------------+ |
| | my-server | |
| +-------------------------------------------------------------------------+ |
| |
| [Validate Again] [Cancel] [Add Server] |
+-----------------------------------------------------------------------------+
Browse Button:
- Opens native file picker to select a local
server.jsonfile - Supports
.jsonfile filter - Note: Registry browser may be added as future enhancement or plugin
Schema Validation:
- Validate against official MCP Registry schema
- Show validation errors inline with line numbers
- Highlight issues in the JSON editor
Package Selection:
- If server.json contains multiple packages (npm + pypi), let user choose which to use
- Display registry type, identifier, and runtime hint for each option
Environment Variables:
- Parse
environmentVariablesarray from selected package - Generate form fields for each variable
- Mark required variables with asterisk (*)
- Show description as helper text
- Validate required variables are filled before enabling "Add Server"
Value Verification:
- Check if package exists in registry (npm, pypi)
- Verify environment variables are set (or prompt user)
- For HTTP transport: optionally verify URL is reachable
- For STDIO: verify command is available (e.g.,
npxinstalled)
Server Generation:
- Convert server.json to internal config format
- Construct command from runtime hint + package identifier (e.g.,
npx -y my-mcp-server) - Apply environment variables
- Set transport type from package.transport
server.json to Internal Config Mapping:
| server.json Field | Internal Config Field |
|---|---|
name |
name (display name) |
packages[n].registryType |
Determines command prefix |
packages[n].identifier |
Package name in command |
packages[n].runtimeHint |
Command prefix (npx, uvx, etc.) |
packages[n].transport.type |
transportType |
packages[n].environmentVariables |
env object |
Use Cases:
- MCP authors testing server.json before publishing to registry
- Developers importing servers from registry without manual setup
- Configuration troubleshooting with detailed validation feedback
Server Info (Connected)
Shown as a modal or dedicated screen after successful connection.
+---------------------------------------------------------+
| Server Information [x] |
+---------------------------------------------------------+
| |
| Name: everything-server |
| Version: 1.0.0 |
| Protocol: 2025-11-25 |
| Transport: stdio |
| |
| Server Capabilities Client Capabilities |
| --------------------- --------------------- |
| [check] Tools (4) [check] Sampling |
| [check] Resources (12) [check] Elicitation |
| [check] Prompts (2) [check] Roots (3) |
| [check] Logging [check] Tasks |
| [check] Completions |
| [check] Tasks |
| [x] Experimental |
| |
| Server Instructions |
| ------------------- |
| "This server provides testing tools for MCP..." |
| |
| OAuth Details (if applicable) |
| ------------- |
| Auth URL: https://auth.example.com |
| Scopes: read, write |
| Access Token: eyJhbG... [Copy] [Decode JWT v] |
| |
+---------------------------------------------------------+
Functionality:
- Display server metadata, version, and negotiated protocol version
- Show both server and client capabilities with counts
- Server capabilities: Tools, Resources, Prompts, Logging, Completions, Tasks, Experimental
- Client capabilities: Sampling, Elicitation, Roots, Tasks, Experimental
- Display server instructions if provided
- Show OAuth tokens with copy and JWT decode options
OAuth Debugger
Accessed via [OAuth Debug] button on the server card (visible when server uses OAuth).
+---------------------------------------------------------------------------+
| OAuth Debugger: my-server [x] |
+---------------------------------------------------------------------------+
| |
| OAuth Flow Status |
| +-----------------------------------------------------------------------+ |
| | Step 1: Authorization Request [Completed] | |
| | +-------------------------------------------------------------------+ | |
| | | GET https://auth.example.com/authorize | | |
| | | ?client_id=my-client-id | | |
| | | &redirect_uri=http://localhost:5173/callback | | |
| | | &response_type=code | | |
| | | &scope=read%20write | | |
| | | &state=abc123 | | |
| | +-------------------------------------------------------------------+ | |
| | [Copy URL] | |
| +-----------------------------------------------------------------------+ |
| |
| +-----------------------------------------------------------------------+ |
| | Step 2: Authorization Code [Completed] | |
| | +-------------------------------------------------------------------+ | |
| | | code: xyz789... | | |
| | | state: abc123 (verified) | | |
| | +-------------------------------------------------------------------+ | |
| +-----------------------------------------------------------------------+ |
| |
| +-----------------------------------------------------------------------+ |
| | Step 3: Token Exchange [Completed] | |
| | +-------------------------------------------------------------------+ | |
| | | POST https://auth.example.com/token | | |
| | | grant_type=authorization_code&code=xyz789... | | |
| | +-------------------------------------------------------------------+ | |
| +-----------------------------------------------------------------------+ |
| |
| +-----------------------------------------------------------------------+ |
| | Step 4: Access Token [Active] | |
| | +-------------------------------------------------------------------+ | |
| | | access_token: eyJhbG... [Copy] [Decode] | | |
| | | token_type: Bearer | | |
| | | expires_in: 3600 (expires at 15:32:00) | | |
| | | scope: read write | | |
| | +-------------------------------------------------------------------+ | |
| +-----------------------------------------------------------------------+ |
| |
| +-----------------------------------------------------------------------+ |
| | Refresh Token | |
| | +-------------------------------------------------------------------+ | |
| | | refresh_token: def456... [Copy] | | |
| | +-------------------------------------------------------------------+ | |
| | [Test Refresh Now] | |
| +-----------------------------------------------------------------------+ |
| |
| ---------------------------------------------------------------------------
| |
| Decoded Access Token (JWT) |
| +-----------------------------------------------------------------------+ |
| | Header: | |
| | { "alg": "RS256", "typ": "JWT" } | |
| | | |
| | Payload: | |
| | { | |
| | "sub": "user123", | |
| | "aud": "my-client-id", | |
| | "scope": "read write", | |
| | "exp": 1732990800, | |
| | "iat": 1732987200 | |
| | } | |
| +-----------------------------------------------------------------------+ |
| |
| [Revoke Token] [Start New Flow] |
+---------------------------------------------------------------------------+
Features:
- Flow Visualization - Step-by-step view of OAuth 2.0 flow
- Authorization request URL with all parameters
- Authorization code received
- Token exchange request/response
- Access token details
- Token Display:
- Access token with copy and decode options
- Token type and expiration time
- Refresh token (if available)
- Decoded JWT payload and header
- Actions:
- [Test Refresh Now] - Manually trigger token refresh
- [Revoke Token] - Revoke current access token
- [Start New Flow] - Begin fresh OAuth flow
- [Copy] - Copy tokens/URLs to clipboard
- [Decode] - Show JWT contents
Use Cases:
- Debugging OAuth configuration issues
- Verifying token claims and scopes
- Testing token refresh behavior
- Understanding the full OAuth handshake
MCP Protocol Coverage
This UX specification covers 100% of the MCP 2025-11-25 protocol specification.
Request Methods
| Method | UX Location |
|---|---|
initialize |
Connection flow (implicit) |
ping |
Navigation bar latency display |
tools/list |
Tools Screen |
tools/call |
Tools Screen |
resources/list |
Resources Screen |
resources/templates/list |
Resources Screen (templates section) |
resources/read |
Resources Screen |
resources/subscribe |
Resources Screen |
resources/unsubscribe |
Resources Screen |
prompts/list |
Prompts Screen |
prompts/get |
Prompts Screen |
sampling/createMessage |
Sampling Panel |
elicitation/create |
Elicitation Handler |
completion/complete |
Tools/Prompts autocomplete |
logging/setLevel |
Logging Screen |
roots/list |
Roots Configuration |
tasks/list |
Tasks Screen |
tasks/get |
Tasks Screen |
tasks/result |
Tasks Screen |
tasks/cancel |
Tasks Screen |
Notification Methods
| Notification | UX Location |
|---|---|
notifications/initialized |
Connection flow (implicit) |
notifications/progress |
Tools Screen progress bar, Tasks Screen |
notifications/cancelled |
Tools Screen cancel button |
notifications/message |
Logging Screen |
notifications/tools/list_changed |
Tools Screen indicator |
notifications/resources/list_changed |
Resources Screen indicator |
notifications/prompts/list_changed |
Prompts Screen indicator |
notifications/resources/updated |
Resources Screen subscriptions |
notifications/roots/listChanged |
Roots Configuration |
notifications/task/statusChanged |
Tasks Screen |
notifications/elicitation/complete |
Elicitation Handler (URL mode) |
Capabilities
| Capability | Type | UX Location |
|---|---|---|
tools |
Server | Tools Screen, Server Info |
resources |
Server | Resources Screen, Server Info |
prompts |
Server | Prompts Screen, Server Info |
logging |
Server | Logging Screen, Server Info |
completions |
Server | Forms autocomplete, Server Info |
tasks |
Server | Tasks Screen, Server Info |
experimental |
Server | Experimental Features Panel, Server Info |
sampling |
Client | Sampling Panel, Server Info |
elicitation |
Client | Elicitation Handler, Server Info |
roots |
Client | Roots Configuration, Server Info |
tasks |
Client | Tasks Screen, Server Info |
experimental |
Client | Experimental Features Panel, Server Info |
Content Types
| Content Type | UX Location |
|---|---|
| Text | All screens (default) |
| Image (base64) | Tools results, Prompts messages, Resources |
| Audio (base64) | Tools results, Prompts messages, Resources |
| Resource links | Tools results, embedded display |
| Embedded resources | Prompts messages |
Annotations
| Annotation | UX Location |
|---|---|
| Tool audience | Tools Screen badges |
| Tool hints | Tools Screen description |
| Tool readOnly | Tools Screen indicator |
| Tool destructive | Tools Screen warning |
| Resource audience | Resources Screen badges |
| Resource priority | Resources Screen indicator |