TUI client

docs/draft/tools/inspector/tui New page · 78 lines, new page

# TUI client ## Choosing servers ## Tabs ## Navigation ## Authorizing an HTTP server ## Requirements

A whole new page. There's nothing to diff it against, so here is what it says.

# TUI client

> The terminal MCP Inspector: navigation, tabs, and keyboard reference

The TUI is the Inspector's terminal interface, with the same interactive exploration of tools, resources, and prompts as the web client. Use it on a remote host over SSH, in a locked-down environment, or when you prefer to stay in the terminal.

```bash theme={null}
npx @modelcontextprotocol/inspector --tui node build/index.js   # with an ad-hoc stdio server
```

<Frame caption="The TUI connected to a server, on the Tools tab, showing a tool's input schema.">
  <img src="https://mintcdn.com/mcp/gk28X8wi_tbRYzej/images/inspector/tui-tools.png?fit=max&auto=format&n=gk28X8wi_tbRYzej&q=85&s=5d11d64f4b98df8c26e7ac048f38576f" width="2986" height="1832" data-path="images/inspector/tui-tools.png" />
</Frame>

## Choosing servers

Unlike the CLI, the TUI has no `--server <name>` flag for picking one entry: it reads its servers from a catalog or config file, loads every server in it, and lets you pick from an on-screen list:

```bash theme={null}
mcp-inspector --tui --catalog mcp.json   # writable catalog, seeded empty if missing (unlike the web client)
mcp-inspector --tui --config mcp.json    # read-only session, errors if absent
```

With neither `--catalog` nor `--config`, and no [ad-hoc target](/docs/draft/tools/inspector/configuration#ad-hoc-targets), it uses the default writable catalog `~/.mcp-inspector/mcp.json`. See [Configuration and flags](/docs/draft/tools/inspector/configuration).

## Tabs

| Tab           | Key | What it shows                                                                               |
| ------------- | --- | ------------------------------------------------------------------------------------------- |
| **Info**      | `i` | Server info, capabilities, and negotiated protocol details.                                 |
| **Auth**      | `a` | OAuth state for the selected server, plus a **Clear OAuth state** action.                   |
| **Resources** | `r` | Browse and read resources.                                                                  |
| **Prompts**   | `m` | List prompts and render them with arguments.                                                |
| **Tools**     | `t` | View tools and execute them with form-like inputs.                                          |
| **Protocol**  | `p` | JSON-RPC request/response/notification history.                                             |
| **Network**   | `n` | HTTP traffic for SSE and [Streamable HTTP](/specification/latest/basic/transports) servers. |
| **Console**   | `o` | `stderr` from a connected stdio server process.                                             |

The accelerators avoid collisions rather than always taking the first letter: **P**rotocol takes `p` so Pro**m**pts takes `m`, and **C**onsole takes `o` because `c` is the global Connect action.

## Navigation

| Key                              | Action                                              |
| -------------------------------- | --------------------------------------------------- |
| `Left` / `Right` arrows or `Tab` | Switch tabs                                         |
| `Up` / `Down` arrows             | Move through the current list                       |
| `Enter`                          | Select an item, execute a tool, or fetch a resource |
| `c`                              | Connect to the selected server                      |
| `d`                              | Disconnect                                          |
| `Esc` or `Ctrl+C`                | Exit                                                |

## Authorizing an HTTP server

1. Select an HTTP or SSE server and press **`c`** to connect.
2. If the server requires authorization, the TUI starts OAuth automatically and opens the authorization URL in a browser.
3. When the browser redirect lands on the TUI's loopback listener, the connection finishes on its own, with no second **`c`**.
4. Use the **Auth** tab to inspect the resulting OAuth state, or to clear it.

The TUI's callback listener defaults to `http://127.0.0.1:6276/oauth/callback`. The port is fixed on purpose: a pre-registered (static) OAuth client, a [Client ID Metadata Document (CIMD)](/specification/latest/basic/authorization/client-registration#client-id-metadata-documents), or an enterprise-managed IdP all need a redirect URI known in advance. Register that URI once and it works across sessions. On a remote host where your browser is on another machine, forward the callback port so the redirect reaches this listener; see [Callback URLs](/docs/draft/tools/inspector/authorization#callback-urls).

The trade-off is that only one TUI OAuth flow can hold the port at a time; a second concurrent flow fails with `EADDRINUSE`. To override it, pass `--callback-url` or set `MCP_OAUTH_CALLBACK_URL`: use a different fixed port per instance, or `http://127.0.0.1:0/oauth/callback` for an OS-assigned ephemeral port when your authorization server registers redirect URIs dynamically.

<Warning>
  Redirect URIs must match **exactly** what you registered. `localhost` and
  `127.0.0.1` are different URIs as far as an authorization server is concerned.
</Warning>

Per-server OAuth fields in the catalog (static client id/secret, scopes, the enterprise-managed flag) are applied automatically. Install-wide settings (CIMD, enterprise IdP) come from `~/.mcp-inspector/storage/client.json`, the same file the web client's **Client Settings** dialog writes. Point at a different one with `--client-config` or `MCP_CLIENT_CONFIG_PATH`.

See [Authorization](/docs/draft/tools/inspector/authorization) for the full picture.

<Frame caption="The Auth tab. It shows the same OAuth fields as the web client's Connection Info, or reports that the server needs no authorization.">
  <img src="https://mintcdn.com/mcp/gk28X8wi_tbRYzej/images/inspector/tui-auth.png?fit=max&auto=format&n=gk28X8wi_tbRYzej&q=85&s=2e5ef574e80e81c4b49fa2ef0eac0528" width="2986" height="1832" data-path="images/inspector/tui-auth.png" />
</Frame>

## Requirements

The TUI needs a real TTY with raw-mode support. It will not run usefully in a headless CI job; use the [CLI](/docs/draft/tools/inspector/cli) there.