Transport Modes

Run the ListenHub MCP server over stdio (default) or HTTP, and choose the right one for your client.

The server supports two ways for a client to talk to it: stdio and HTTP. stdio is the default and what almost everyone should use. HTTP is for setups where the client and the server are not the same process.

Which one to use

Mode	Use it when	How the client connects
stdio (default)	A desktop or editor client launches the server for you — Claude Desktop, Cursor, Windsurf, Zed, Cline, Claude CLI, Codex CLI.	`command` + `args` in the client config.
HTTP	The server runs separately (a remote host, a container, a shared dev box) and the client connects over a URL.	A `url` pointing at the server's `/mcp` endpoint.

If you followed Quick Start, you are already on stdio — no extra configuration needed.

stdio mode (default)

The client starts the server as a child process and exchanges messages over standard input/output. Every config sample in Quick Start uses this mode. The pattern is always the same:

{
  "mcpServers": {
    "listenhub": {
      "command": "npx",
      "args": ["-y", "@marswave/listenhub-mcp-server@latest"],
      "env": {
        "LISTENHUB_API_KEY": "your_api_key_here"
      }
    }
  }
}

Because the client owns the process, it passes your API key through env. There is no port and no URL.

HTTP mode

Run the server yourself and let clients connect over the network. HTTP mode exposes two endpoints from the same process:

Streamable HTTP at /mcp — the endpoint most HTTP-capable MCP clients expect.
Server-Sent Events (SSE) at /sse — for clients that use the SSE transport.

Start the server:

export LISTENHUB_API_KEY="your_api_key_here"
npx @marswave/listenhub-mcp-server --transport http --port 3000

set LISTENHUB_API_KEY=your_api_key_here
npx @marswave/listenhub-mcp-server --transport http --port 3000

With --port 3000, the endpoints are:

Streamable HTTP: http://localhost:3000/mcp
SSE: http://localhost:3000/sse

Point the client at the streamable HTTP endpoint:

{
  "mcpServers": {
    "listenhub": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

In HTTP mode the API key lives with the server process (the LISTENHUB_API_KEY you exported before starting it), not in the client config. Anyone who can reach the URL can spend your account's credits, so keep the server on a trusted network and do not expose it publicly without your own access control.

Quick Start

Install Node.js, get an API key, and connect a client over stdio.

Available Tools

Tool names, inputs, and response shapes.