mirror of
https://github.com/mcp-use/mcp-use.git
synced 2026-09-14 18:06:01 +08:00
Pietro Zullo
1a3dcfd632
* feat(python/server): auto-retry next available port when default is in use Add port availability checking before starting uvicorn. When the requested port is occupied, the server automatically tries the next port (up to 10 retries) instead of crashing. Refs #1161 * test(python/server): add unit tests for port retry helpers Tests for _is_port_available and _find_available_port covering: - Port available/unavailable detection - Skipping to next port when current is in use - RuntimeError when all ports exhausted * docs(python): document automatic port retry in server running docs
165 lines
3.9 KiB
Plaintext
165 lines
3.9 KiB
Plaintext
---
|
|
title: "Running the Server"
|
|
description: "How to run your mcp-use server with different transport methods"
|
|
icon: "play"
|
|
---
|
|
<Info>
|
|
Learn how to run your mcp-use server using different transport methods and configurations.
|
|
</Info>
|
|
|
|
## Basic Usage
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
server.run(transport="stdio")
|
|
```
|
|
|
|
### streamable-http Transport
|
|
|
|
HTTP-based transport for web clients:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
# 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.
|
|
|
|
<Tip>
|
|
The startup output always shows the actual port the server bound to, so you'll know where to connect.
|
|
</Tip>
|
|
|
|
## 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:*`.
|
|
|
|
```python
|
|
# 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")
|
|
```
|
|
|
|
<Warning>
|
|
If you get **421 Misdirected Request** errors behind a proxy, ensure you're using
|
|
`host="0.0.0.0"` (the default).
|
|
</Warning>
|
|
|
|
## Debug Mode
|
|
|
|
Enable debug mode for development features:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
server.run(transport="streamable-http", reload=True)
|
|
```
|
|
|
|
## Production Configuration
|
|
|
|
```python
|
|
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:
|
|
|
|
```bash
|
|
python my_server.py
|
|
```
|
|
|
|
Or use uvicorn directly:
|
|
|
|
```bash
|
|
uvicorn my_server:app --host 0.0.0.0 --port 8000
|
|
```
|