Skip to main content
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 shapeResult
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

OptionNotes
transport"http" or "stdio". Defaults to "http" when port is set, otherwise "stdio".

​
HTTP options

OptionNotes
portHTTP port. Also available through listen(3000). Defaults to 3000 for HTTP.
hostnameHTTP bind address. Defaults to 127.0.0.1.
pathMCP endpoint path for HTTP. Defaults to /mcp.
healthEnable /health or provide { path } for a custom health route. Disabled by default.
debugWrites HTTP transport logs to stderr.
sessionTimeoutHTTP session expiry in milliseconds. Defaults to 60000.
onListenCallback fired after the HTTP server starts. Receives { hostname, port, url }.
corsEnable permissive CORS or provide the typed CorsOptions shape.
maxBodySizeMaximum accepted request body size in bytes in the public type surface.
tlsTLS options in the public type surface.

​
Stdio options

OptionNotes
transportSet to "stdio" to force stdio explicitly.

​
Current implementation caveats

These reflect the current HTTP implementation, not just the public type surface:
OptionCurrent behavior
corsPresent in the type surface. The current HTTP transport always sends a basic permissive CORS response rather than using the full CorsOptions shape.
maxBodySizePresent in the type surface, but not currently enforced by the HTTP transport.
tlsPresent 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