> ## Documentation Index
> Fetch the complete documentation index at: https://mcpjam-mintlify-docs-update-pr-3444-1785050029015.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Here's a list of all ways to start MCPJam

MCPJam Inspector runs three ways: a hosted web app, a desktop app for Mac and Windows, or via your terminal. The web app is HTTPS-only and has no install. Terminal and Desktop support HTTP/S and local STDIO servers.

<CardGroup cols={3}>
  <Card title="Web App" icon="globe" href="https://app.mcpjam.com">
    Open [app.mcpjam.com](https://app.mcpjam.com). HTTPS only. No install. Share servers with your team.
  </Card>

  <Card title="Desktop App" icon="monitor">
    Download for [Mac](https://github.com/MCPJam/inspector/releases/latest/download/MCPJam.Inspector.dmg) or [Windows](https://github.com/MCPJam/inspector/releases/latest/download/MCPJam-Inspector-Setup.exe). HTTP/S and local STDIO.
  </Card>

  <Card title="Terminal" icon="terminal">
    `npx @mcpjam/inspector@latest`. HTTP/S and local STDIO.
  </Card>
</CardGroup>

### Which one do I need?

| Capability | Web App | Desktop | Terminal (`npx`) | Docker |
| - | :-: | :-: | :-: | :-: |
| Install required | None | Mac/Windows download | Node.js | Docker + Git |
| HTTPS MCP servers | ✓ | ✓ | ✓ | ✓ |
| HTTP MCP servers | — | ✓ | ✓ | ✓ |
| Local STDIO servers | — | ✓ | ✓ | ✓ (with `--` args) |
| Skills | — | ✓ | ✓ | ✓ |
| Shareable server URLs | ✓ | — | — | — |
| Always on latest version | ✓ | Re-download to update | Per-run (`@latest`) | Rebuild from source |

If your server is local (running on `localhost`), the web app cannot reach it — pick **Desktop** or **Terminal**. If you want teammates to one-click into the same server, pick **Web App**.

## Web app

Go to [app.mcpjam.com](https://app.mcpjam.com) in your browser. No install required. The web app accepts HTTPS MCP server URLs only — for HTTP or local STDIO servers, use the desktop or terminal options below. See [Hosted App](/hosted/overview) for more.

## Desktop app

Download the installer for your OS and run it:

* [Mac](https://github.com/MCPJam/inspector/releases/latest/download/MCPJam.Inspector.dmg)
* [Windows](https://github.com/MCPJam/inspector/releases/latest/download/MCPJam-Inspector-Setup.exe)

The desktop app supports HTTP/S and local STDIO servers, and does not require Node.js.

## Terminal

Run the command in your terminal:

<CodeGroup>
  ```bash npm theme={"theme":"css-variables"}
  npx @mcpjam/inspector@latest
  ```

  ```bash pnpm theme={"theme":"css-variables"}
  pnpm dlx @mcpjam/inspector@latest
  ```

  ```bash yarn theme={"theme":"css-variables"}
  yarn dlx @mcpjam/inspector@latest
  ```

  ```bash bun theme={"theme":"css-variables"}
  bunx @mcpjam/inspector@latest
  ```
</CodeGroup>

After installing the package, you should see a link to `localhost`. Open that link up to see the inspector.

<Info>
  **Widget rendering (Chromium):** On first startup, Inspector automatically downloads and installs the Playwright Chromium browser needed to render widgets. This happens in the background — you'll see download progress in the terminal. No manual `playwright install` step is required. Docker images already include Chromium and are unaffected.

  If the download fails, the browser pane shows the reason and retries automatically (after 30 seconds, then 2 minutes, then 10 minutes). You can also click **Retry now** at any time to restart the download immediately. After three automatic retries, only **Retry now** will trigger another attempt.
</Info>

### From your editor (VS Code, Cursor, Windsurf)

There is no dedicated editor extension — and you don't need one. Open your editor's integrated terminal, run the same `npx @mcpjam/inspector@latest` command, and click the printed `localhost` link. The inspector runs alongside your dev server in any editor that has a terminal pane.

If you want the inspector to auto-launch from your project's `dev` script (so it boots whenever you start your server), see [Launch from Code](/inspector/launch-from-code).

## Docker

There is no published image — build one from source, then run it bound to localhost for security:

```bash theme={"theme":"css-variables"}
git clone https://github.com/MCPJam/inspector.git
cd inspector
docker build -t mcpjam/mcp-inspector:local -f mcpjam-inspector/Dockerfile .
docker run -p 127.0.0.1:6274:6274 mcpjam/mcp-inspector:local
```

Open the private link printed in the container logs to sign in. The plain address shows instructions to open or paste that link. If you already have that tab open, pasting the link into the address bar signs you in without a reload. Keep `-p 127.0.0.1:6274:6274` for local-only access. On macOS/Windows, connect to host MCP servers via `http://host.docker.internal:PORT` instead of `127.0.0.1`.

### Accessing over the network

A native (`npx`) install binds to localhost. You can reach a remote installation through SSH forwarding (`ssh -L 6274:127.0.0.1:6274 user@host`), then open its terminal link at your forwarded address. Keep the `#token=…` part of the link.

For direct LAN access, the Docker image binds `0.0.0.0`. Set `MCPJAM_ALLOWED_HOSTS` to the address you use and publish the port on your network interface:

```bash theme={"theme":"css-variables"}
docker run -p 6274:6274 -e MCPJAM_ALLOWED_HOSTS=192.168.1.50 mcpjam/mcp-inspector:local
```

This publishes the port on all interfaces. Open the printed Network link, or paste the terminal link into the access screen. Allowlisting a host accepts it as a request origin; it does not grant access without the link. Cross-tab continuation works only when both tabs use the same host and port.

For a remapped port, keep the link's `#token=…` part and change the address. Set `MCPJAM_INSPECTOR_FRONTEND_URL=http://devbox.local:8080` to print a fixed address. For IPv6, bracket the allowlist entry: `MCPJAM_ALLOWED_HOSTS=[fd00::50]`. Comma-separate multiple hosts. Wildcards additionally require `MCPJAM_ALLOW_WILDCARD_ORIGINS=true` for request origins.

A restart generates a new link. To keep one across restarts, set `MCPJAM_SESSION_TOKEN` to a strong random URL-safe secret of at least 24 characters. Update `@mcpjam/cli` alongside Inspector; local CLI attachment uses an owner-only runtime file.

<Warning>
  Keep access links private: they grant control of the local Inspector and its connected tools. Set `MCPJAM_LOCAL_COMPUTER_ENABLED=false` and `MCPJAM_LOCAL_BROWSER_ENABLED=false` if you do not need the local shell and browser tools.
</Warning>

### Docker with Arguments

You can pass command-line arguments to the Docker container:

```bash theme={"theme":"css-variables"}
# Launch with STDIO server
docker run -p 127.0.0.1:6274:6274 mcpjam/mcp-inspector:local -- \
  npx -y @modelcontextprotocol/server-everything

# Launch with HTTP server
docker run --rm -p 127.0.0.1:6274:6274 mcpjam/mcp-inspector:local -- \
  --url http://host.docker.internal:8080/mcp \
  --name "HTTP Server" \
  --tab tools
```

For more information check out our docs on [Launch from Code](https://docs.mcpjam.com/inspector/launch-from-code)

<Warning>
  **Important for macOS/Windows users:**

  * Access the app via `http://127.0.0.1:6274` (not `localhost`)
  * When connecting to MCP servers on your host machine, use `http://host.docker.internal:PORT` instead of `http://127.0.0.1:PORT`

  Example:

  ```bash theme={"theme":"css-variables"}
  # Your MCP server runs on host at: http://127.0.0.1:8080/mcp
  # In Docker, configure it as: http://host.docker.internal:8080/mcp
  ```
</Warning>

## Start with STDIO server

This will open the MCPJam inspector and connect to a STDIO using the commands you provided.

<Tabs>
  <Tab title="Python Server">
    ```bash theme={"theme":"css-variables"}
    # Starts MCPJam inspector with a FastMCP server
    npx @mcpjam/inspector@latest uv run fastmcp run /path/to/your/server.py
    ```

    This command assumes [`uv`](https://docs.astral.sh/uv/) is installed and on your PATH. If you see `Unknown command: uv` (fish), `command not found: uv` (bash/zsh), or `'uv' is not recognized` (Windows), install it first:

    ```bash theme={"theme":"css-variables"}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
  </Tab>

  <Tab title="Node.js Server">
    ```bash theme={"theme":"css-variables"}
    # NPX package
    npx @mcpjam/inspector@latest npx -y your-mcp-package

    # Direct Node.js execution
    npx @mcpjam/inspector@latest node /path/to/your/server.js
    ```
  </Tab>
</Tabs>

<Info>
  **Use Absolute Paths**: Always use absolute file paths (e.g.,
  `/Users/yourname/project/server.py`) to avoid path resolution issues.
</Info>

## Start with custom port

This will start the MCPJam inspector with a custom port number. The default port is `6274`.

```bash theme={"theme":"css-variables"}
npx @mcpjam/inspector@latest --port 4000
```

The port must be a valid integer between 1 and 65535. Passing an invalid value (e.g. a string or out-of-range number) exits immediately with an error.

## Start with Ollama

This will open the MCPJam inspector and start an Ollama model with the `ollama serve <model>` command. Make sure you have Ollama installed.

```bash theme={"theme":"css-variables"}
npx @mcpjam/inspector@latest --ollama llama3.2
```

## Start with Configuration File

You can use a configuration file to connect to multiple MCP servers at once:

```bash theme={"theme":"css-variables"}
# Using npx directly
npx @mcpjam/inspector@latest --config path/to/config.json --server myserver

# If running from the repository
npm run build
npm start -- --config path/to/config.json --server myserver
```

<Info>
  **Note**: When using `npm start`, you need the `--` separator to pass
  arguments to the underlying script.
</Info>

All servers in the config get added to your project. By default they all
connect on launch; pass `--server <name>` to only connect that one. If
you're not signed in, we'll send you to sign in and bring you right back.

Example configuration file structure:

```json config.json theme={"theme":"css-variables"}
{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": {
        "HELLO": "Hello MCP!"
      }
    },
    "weather-server": {
      "command": "python",
      "args": ["weather_server.py"],
      "env": {
        "WEATHER_API_KEY": "your-api-key"
      }
    }
  }
}
```

The config parser accepts three equivalent wrapper shapes, so you can paste a config from any of these sources without reformatting:

| Shape | Example |
| - | - |
| `mcpServers` wrapper (MCPJam / Claude Desktop style) | `{ "mcpServers": { "my-server": { ... } } }` |
| `mcp_servers` wrapper (OpenAI plugin style) | `{ "mcp_servers": { "my-server": { ... } } }` |
| Direct server map (OpenAI `.mcp.json` style) | `{ "my-server": { ... } }` |

Declaring both `mcp_servers` and `mcpServers` in the same file is an error. A bare single-server object (top-level `command` or `url` string) is not accepted — wrap it in one of the shapes above.

### Mixing STDIO and HTTP/SHTTP servers

You can mix STDIO and HTTP (Streamable HTTP / SHTTP) server entries in the same config. Transport is determined as follows:

1. If the entry has an explicit `type` or `transport` field, that wins.
2. Otherwise it is inferred from the other fields: `command` means STDIO, `url` means HTTP/SHTTP.

Accepted values for `type`/`transport` are `stdio`, `http`, `sse`, and all common spellings of Streamable HTTP (`streamable-http`, `streamable_http`, `streamableHttp`). An unrecognised value causes that server entry to be skipped.

```json config.json theme={"theme":"css-variables"}
{
  "mcpServers": {
    "local-everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": {
        "HELLO": "Hello MCP!"
      }
    },
    "hosted-weather": {
      "url": "https://weather.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}
```

`headers` on HTTP entries and `env` on STDIO entries are preserved through the import and kept for subsequent connections — re-importing a config will not clear credentials already stored for a server of the same name.

The terminal and desktop installs accept both shapes in the same file. The hosted web app accepts HTTP/SHTTP entries only — STDIO entries are ignored because the hosted runtime cannot spawn local processes.

For per-server `Authorization` headers, see [API keys → Playground BYOK](/reference/api-keys#3-playground-byok-bring-your-own-key).

## Start with Verbose Logging

Enable verbose HTTP request logging for debugging purposes. This is useful when troubleshooting connection issues with MCP servers.

```bash theme={"theme":"css-variables"}
npx @mcpjam/inspector@latest --verbose
```

Or use the short form:

```bash theme={"theme":"css-variables"}
npx @mcpjam/inspector@latest -v
```

<Info>
  Verbose mode logs all HTTP requests made by the inspector, which can help
  diagnose connectivity problems or inspect server communication.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.