listen() Options - Redop

Use listen() to start either the HTTP or stdio transport. For transport selection guidance and common usage patterns, use Listening and Transports.

Overloads

app.listen();
app.listen(3000);
app.listen(3000, "0.0.0.0");
app.listen({
  port: 3000,
  hostname: "0.0.0.0",
  debug: true,
});

Behavior by call shape

Call shape	Result
`listen()`	Starts `stdio`
`listen(3000)`	Starts `http` on port `3000`
`listen(3000, "0.0.0.0")`	Starts `http` with an explicit hostname
`listen({ port: 3000 })`	Starts `http`
`listen({ transport: "stdio" })`	Forces `stdio`
`listen({ transport: "http" })`	Forces `http`

Typical HTTP options

app.listen({
  transport: "http",
  port: 3000,
  hostname: "0.0.0.0",
  path: "/mcp",
  health: { path: "/health" },
  debug: true,
  sessionTimeout: 60_000,
  onListen: ({ url }) => {
    console.log(url);
  },
});

Options

Shared options

Option	Notes
`transport`	`"http"` or `"stdio"`. Defaults to `"http"` when `port` is set, otherwise `"stdio"`.

HTTP options

Option	Notes
`port`	HTTP port. Also available through `listen(3000)`. Defaults to `3000` for HTTP.
`hostname`	HTTP bind address. Defaults to `127.0.0.1`.
`path`	MCP endpoint path for HTTP. Defaults to `/mcp`.
`health`	Enable `/health` or provide `{ path }` for a custom health route. Disabled by default.
`debug`	Writes HTTP transport logs to stderr.
`sessionTimeout`	Legacy HTTP session expiry in milliseconds. Defaults to `60000`. Unused for MCP `2026-07-28`.
`listCache`	Override list/discover cache hints (`ttlMs`, `cacheScope`) for MCP `2026-07-28`.
`onListen`	Callback fired after the HTTP server starts. Receives `{ hostname, port, url }`.
`cors`	Enable permissive CORS or provide the typed `CorsOptions` shape.
`maxBodySize`	Maximum accepted request body size in bytes in the public type surface.
`tls`	TLS options in the public type surface.

Stdio options

Option	Notes
`transport`	Set to `"stdio"` to force stdio explicitly.

Current implementation caveats

These reflect the current HTTP implementation, not just the public type surface:

Option	Current behavior
`cors`	Present in the type surface. The current HTTP transport always sends a basic permissive CORS response rather than using the full `CorsOptions` shape.
`maxBodySize`	Present in the type surface, but not currently enforced by the HTTP transport.
`tls`	Present in the type surface and used when formatting the reported URL, but the current HTTP transport does not start Bun with TLS from this option yet.

Defaults

default transport: stdio without port, otherwise http
default HTTP hostname: 127.0.0.1
default HTTP port: 3000
default MCP path: /mcp
default health route: disabled
default session timeout: 60000