inspector/clients/tui

MCP Inspector TUI Client

The Terminal User Interface (TUI) client brings the interactive exploration capabilities of the Web Client directly to your terminal. It is built using Ink to provide a rich, React-like component experience in a command-line environment.

Running the TUI

You can run the TUI client via npx:

npx @modelcontextprotocol/inspector --tui node build/index.js

With Configuration Files

The TUI can load all servers from an MCP catalog/config file. With no source flag it uses the default writable catalog ~/.mcp-inspector/mcp.json (seeded empty if missing):

npx @modelcontextprotocol/inspector --tui --catalog mcp.json   # writable catalog (seeded empty if missing)
npx @modelcontextprotocol/inspector --tui --config mcp.json    # read-only session (errors if absent)

(It does not use --server; all servers in the file are available in the TUI.)

Options

MCP server (which server(s) to connect to)

Options that specify the MCP server(s) (catalog/config file, ad-hoc command/URL, env vars, headers) are shared by the Web, CLI, and TUI and are documented in MCP server configuration: --catalog (writable catalog, seeded empty if missing; default ~/.mcp-inspector/mcp.json or MCP_CATALOG_PATH), --config (read-only session, errors if absent), -e, --cwd, --header, --transport, --server-url, and the positional [target...]. --catalog and --config are mutually exclusive, and neither combines with an ad-hoc target.

TUI-specific (OAuth for HTTP servers)

The TUI supports OAuth for SSE and Streamable HTTP servers. Per-server OAuth fields in mcp.json (static client id/secret, scopes, enterprise-managed flag) are applied automatically when loaded from --catalog or --config. Install-wide settings (CIMD, enterprise IdP) come from ~/.mcp-inspector/storage/client.json — the same file the web Client Settings dialog writes. You can point at a different file with --client-config or MCP_CLIENT_CONFIG_PATH.

OAuth callback URL

The TUI starts a small loopback HTTP server to receive the authorization redirect after you sign in in the browser. Defaults:

Surface	Default callback
Web	http://localhost:6274/oauth/callback (main app server)
TUI	http://127.0.0.1:6276/oauth/callback (dedicated runner port; avoids colliding with web on 6274)

Why a fixed default port? Enterprise-managed auth (EMA), CIMD, and many static OAuth apps require pre-registered redirect URIs. A predictable default (http://127.0.0.1:6276/oauth/callback) lets you register once on the IdP and reuse it across TUI sessions. Dynamic registration (DCR) can use ephemeral ports instead — see below.

Trade-off: only one TUI OAuth flow at a time can listen on the default port. A second instance starting OAuth while another is in progress may fail with EADDRINUSE. Override the listener with --callback-url or MCP_OAUTH_CALLBACK_URL (e.g. a different fixed port per instance, or http://127.0.0.1:0/oauth/callback when the authorization server accepts dynamically registered redirect URIs).

OAuth redirect URIs must match exactly what you register on the authorization server — localhost and 127.0.0.1 are different URIs. Register the TUI default on your OAuth app / IdP when using pre-registered (static), CIMD, or enterprise-managed clients. Override the listener with --callback-url or MCP_OAUTH_CALLBACK_URL; use http://127.0.0.1:0/oauth/callback for an OS-assigned ephemeral port when the authorization server registers redirect URIs dynamically (DCR).

Flags

Option	Env	Description
--client-config <path>	MCP_CLIENT_CONFIG_PATH	Install-level client config (default: ~/.mcp-inspector/storage/client.json).
--client-id <id>	—	OAuth client ID (static client); overrides client.json.
--client-secret <secret>	—	OAuth client secret (confidential clients); overrides client.json.
--client-metadata-url <url>	—	Client ID Metadata Document URL (CIMD); overrides client.json.
--callback-url <url>	MCP_OAUTH_CALLBACK_URL	OAuth redirect/callback listener (default: http://127.0.0.1:6276/oauth/callback). Must bind a loopback host (localhost / 127.0.0.0/8 / [::1]); a non-loopback host hard-errors, since the listener receives the authorization code over plaintext http.

Authenticating in the TUI

1. Select an HTTP/SSE server and press C to connect.
2. If authorization is required, the TUI starts OAuth automatically (browser opens for sign-in).
3. After the callback completes, connect finishes without a second C.
4. Use the Auth tab to inspect OAuth state (same fields as web Connection Info) or Clear OAuth state (disconnects when connected).

See also EMA / enterprise-managed auth and OAuth smoke testing for staging servers and verification steps.

Features

The TUI provides terminal-native tabs and panes for interacting with your MCP server:

• Resources: Browse and read resources exposed by the server.
• Prompts: List and test prompts.
• Tools: View available tools and execute them with form-like inputs.
• Protocol: View JSON-RPC request/response/notification history (matches the web Protocol monitor).
• Network: View HTTP fetch traffic for SSE / Streamable HTTP servers (matches the web Network monitor).
• Console: View stdio stderr from the connected server process (matches the web Console monitor).

Navigation

• Use the Arrow Keys (Left/Right) or Tab to switch between the main tabs (Resources, Tools, Prompts, etc.).
• Use the Arrow Keys (Up/Down) to scroll through lists of items.
• Press Enter to select an item, execute a tool, or fetch a resource.
• Press Escape or Ctrl+C to exit the application.

Development

Like the other clients, the TUI self-validates from its own folder:

npm run validate       # format:check && lint && build && test:coverage
npm test               # run all tests
npm run test:coverage  # run tests under the per-file coverage gate

The repo-root validate:tui just delegates here. eslint.config.js registers react-hooks for the classic rules only (rules-of-hooks + exhaustive-deps); the stricter react-hooks@7 rules are not enforced on the interim component surface (#1501).

Tests live in __tests__/. The coverage gate covers all of src/**, React surface included — the Ink components mount through ink-testing-library (with the ink-scroll-view / ink-form passthrough doubles in __tests__/helpers/), App.tsx mounts against a mock of the @inspector/core surface, and keypresses are driven through stdin. The former interim exclusion of the components and App.tsx was lifted in #1501; the only exclusion left in vitest.config.ts is src/tui-servers.ts, a pure re-export of core's server resolver with no runtime statements of its own (its logic is measured in core/ via the web suite, and tui-servers.test.ts still exercises it behaviorally — it is excluded only so it doesn't surface as a misleading 0/0 row).

Bundling: React-rendering dependencies must be inlined (#1952)

tsup.config.ts splits the TUI's dependencies into bundled (noExternal) and externalized (external). For anything that renders React components, that choice decides which React instance it gets at runtime, and getting it wrong crashes the TUI in a way nothing in this repo can see.

An external package's import "react" resolves from wherever npm placed that package — and npm places it next to a React satisfying its own peer range. ink-form and ink-scroll-view both accept react: ">=18", so a project that installs the Inspector alongside its own React 18 satisfies them: they hoist to that project's root while the Inspector's React 19 nests underneath. The bundle then renders through React 19 while those two call hooks on React 18, whose dispatcher is null — so opening a tool test form (or any scroll view) dies with TypeError: Cannot read properties of null (reading 'useState').

Bundling them removes npm from the decision: their import "react" is emitted into build/index.js, so it resolves from the build directory exactly like the bundle's own. It also pins their transitive deps to what this install resolved — notably ink-select-input@6 via the overrides entry, since npm ignores a dependency's overrides and a consumer install would otherwise pull the React-18-era v5 that ink-form asks for.

ink itself stays external: it can't be bundled (its CJS signal-exit@3 dependency fails ESM interop with Dynamic require of "assert" is not supported), and it doesn't need to be — its react peer is ">=19", which keeps npm from hoisting it next to a React the Inspector couldn't also use.

__tests__/tsupConfig.test.ts enforces this: every dependency declaring a react peer must be in noExternal unless it is listed as external by design. Add a React-rendering dependency, and that test tells you to bundle it.

The ink-form label patch

Bundling ink-form also makes it patchable, which one label needs: the hint under an incomplete form reads "you have not competed yet". It is upstream's string, hardcoded in ink-form/lib/SubmitButton.js with no prop to override, and ink-form was last published in 2024 — so tsup.config.ts corrects it with an esbuild onLoad hook as the file enters the bundle. It is reported upstream as lukasbach/ink-form#14; if a release ever carries the fix, drop the patch.

The hook throws when the string isn't found rather than passing the source through. A silent no-op would let an ink-form upgrade retire the patch without anyone noticing it had stopped applying — or leave a patch aimed at a string that no longer exists. If the build fails there, check whether upstream fixed the typo and delete the patch instead of re-targeting it.