Running the Server

Learn how to run your mcp-use server using different transport methods and configurations.

Basic Usage

from mcp_use.server import MCPServer

server = MCPServer(name="My Server")

# Run with stdio transport (for MCP clients)
server.run(transport="stdio")

# Run with HTTP transport (for web clients)
server.run(transport="streamable-http")

Transport Methods

stdio Transport

Standard input/output transport for MCP clients:

server.run(transport="stdio")

streamable-http Transport

HTTP-based transport for web clients:

server.run(
    transport="streamable-http",
    host="0.0.0.0",
    port=8000,
    reload=False,
    debug=False
)

Host and Port Configuration

You can configure host and port either at initialization or when calling run(). Values passed to run() override those set in __init__(), and DNS rebinding protection is automatically reconfigured to match:

# Set defaults at initialization
server = MCPServer(name="My Server", host="0.0.0.0", port=3000)
server.run()  # Uses host="0.0.0.0", port=3000, no DNS protection

# Override at runtime - DNS protection is reconfigured automatically
server.run(host="127.0.0.1", port=8080)  # Switches to localhost with DNS protection

Default Values

Parameter	Default	Description
`host`	`"0.0.0.0"`	Bind address. Use `"127.0.0.1"` for local-only access
`port`	`8000`	Port number

Automatic Port Retry

When the requested port is already in use (e.g., another server is running on port 8000), the server automatically tries the next available port instead of crashing:

Port 8000 is in use, using port 8001 instead.

- Local:        http://0.0.0.0:8001
- MCP:          http://0.0.0.0:8001/mcp

The server tries up to 10 consecutive ports (8000, 8001, …, 8009). If none are available, it raises an error. This makes it easy to run multiple MCP servers simultaneously during development without manually specifying different ports.

The startup output always shows the actual port the server bound to, so you’ll know where to connect.

Cloud and Proxy Deployments

When deploying behind reverse proxies (Cloudflare, nginx, Fly.io, etc.), the server automatically configures DNS rebinding protection based on the host:

host="0.0.0.0" (default): DNS rebinding protection is disabled, allowing any Host header. This is safe when your proxy handles host validation.
host="127.0.0.1": DNS rebinding protection is enabled, only allowing requests with Host: 127.0.0.1:* or Host: localhost:*.

# Cloud deployment (behind proxy) - default, no DNS protection
server = MCPServer(name="My Server")
server.run(transport="streamable-http")

# Local development - auto-enables DNS protection
server = MCPServer(name="My Server", host="127.0.0.1")
server.run(transport="streamable-http")

If you get 421 Misdirected Request errors behind a proxy, ensure you’re using host="0.0.0.0" (the default).

Debug Mode

Enable debug mode for development features:

server = MCPServer(name="My Server", debug=True)

# Debug mode enables:
# - /openmcp.json endpoint
# - /docs endpoint
# - /inspector endpoint
# - Enhanced logging
server.run(transport="streamable-http", debug=True)

Auto-reload

Enable auto-reload during development:

server.run(transport="streamable-http", reload=True)

Production Configuration

server = MCPServer(
    name="My Server",
    host="0.0.0.0",
    port=8000,
)

server.run(
    transport="streamable-http",
    reload=False,
    debug=False
)

Command Line

Run directly with Python:

python my_server.py

Or use uvicorn directly:

uvicorn my_server:app --host 0.0.0.0 --port 8000

Get Started

MCP Server

MCP Client

MCP Agents

Development

Running the Server

Basic Usage

Transport Methods

stdio Transport

streamable-http Transport

Host and Port Configuration

Default Values

Automatic Port Retry

Cloud and Proxy Deployments

Debug Mode

Auto-reload

Production Configuration

Command Line

​Basic Usage

​Transport Methods

​stdio Transport

​streamable-http Transport

​Host and Port Configuration

​Default Values

​Automatic Port Retry

​Cloud and Proxy Deployments

​Debug Mode

​Auto-reload

​Production Configuration

​Command Line

Basic Usage

Transport Methods

stdio Transport

streamable-http Transport

Host and Port Configuration

Default Values

Automatic Port Retry

Cloud and Proxy Deployments

Debug Mode

Auto-reload

Production Configuration

Command Line