mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-23 22:14:18 +02:00
Align CLI, deployment, and config docs (#4259)
* docs: align CLI and deployment docs Generated with Codex. * docs: restore install config support, fix CIMD placeholder, add missing CLI flags * docs: restore contrib guidance, correct --copy availability * docs: remove dead redirect-shadowed pages * Fix stale --path default in run command help * docs: correct Goose flag support, fix README link to moved testing page --------- Co-authored-by: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
This commit is contained in:
Bill Easton
GitHub
parent
d3b7922615
commit
149a7aa2ce
18 changed files with 85 additions and 1334 deletions
|
|
@ -79,17 +79,17 @@ The ASGI approach shines in production environments where you need reliability a
|
|||
|
||||
### Custom Path
|
||||
|
||||
By default, your MCP server is accessible at `/mcp/` on your domain. You can customize this path to fit your URL structure or avoid conflicts with existing endpoints. This is particularly useful when integrating MCP into an existing application or following specific API conventions.
|
||||
By default, your MCP server is accessible at `/mcp` on your domain. You can customize this path to fit your URL structure or avoid conflicts with existing endpoints. This is particularly useful when integrating MCP into an existing application or following specific API conventions.
|
||||
|
||||
```python
|
||||
# Option 1: With mcp.run()
|
||||
mcp.run(transport="http", host="0.0.0.0", port=8000, path="/api/mcp/")
|
||||
mcp.run(transport="http", host="0.0.0.0", port=8000, path="/api/mcp")
|
||||
|
||||
# Option 2: With ASGI app
|
||||
app = mcp.http_app(path="/api/mcp/")
|
||||
app = mcp.http_app(path="/api/mcp")
|
||||
```
|
||||
|
||||
Now your server is accessible at `http://localhost:8000/api/mcp/`.
|
||||
Now your server is accessible at `http://localhost:8000/api/mcp`.
|
||||
|
||||
### Authentication
|
||||
|
||||
|
|
@ -345,7 +345,7 @@ def analyze(data: str) -> dict:
|
|||
return {"result": f"Analyzed: {data}"}
|
||||
|
||||
# Create the ASGI app
|
||||
mcp_app = mcp.http_app(path='/mcp')
|
||||
mcp_app = mcp.http_app(path="/mcp")
|
||||
|
||||
# Create a Starlette app and mount the MCP server
|
||||
app = Starlette(
|
||||
|
|
@ -357,7 +357,7 @@ app = Starlette(
|
|||
)
|
||||
```
|
||||
|
||||
The MCP endpoint will be available at `/mcp-server/mcp/` of the resulting Starlette app.
|
||||
The MCP endpoint will be available at `/mcp-server/mcp` of the resulting Starlette app.
|
||||
|
||||
<Warning>
|
||||
For Streamable HTTP transport, you **must** pass the lifespan context from the FastMCP app to the resulting Starlette app, as nested lifespans are not recognized. Otherwise, the FastMCP server's session manager will not be properly initialized.
|
||||
|
|
@ -376,7 +376,7 @@ from starlette.routing import Mount
|
|||
mcp = FastMCP("MyServer")
|
||||
|
||||
# Create the ASGI app
|
||||
mcp_app = mcp.http_app(path='/mcp')
|
||||
mcp_app = mcp.http_app(path="/mcp")
|
||||
|
||||
# Create nested application structure
|
||||
inner_app = Starlette(routes=[Mount("/inner", app=mcp_app)])
|
||||
|
|
@ -386,7 +386,7 @@ app = Starlette(
|
|||
)
|
||||
```
|
||||
|
||||
In this setup, the MCP server is accessible at the `/outer/inner/mcp/` path.
|
||||
In this setup, the MCP server is accessible at the `/outer/inner/mcp` path.
|
||||
|
||||
### FastAPI Integration
|
||||
|
||||
|
|
|
|||
|
|
@ -240,7 +240,7 @@ if __name__ == "__main__":
|
|||
mcp.run(transport="http") # Health check at http://localhost:8000/health
|
||||
```
|
||||
|
||||
Custom routes are served by the same web server as your MCP endpoint. They're available at the root of your domain while the MCP endpoint is at `/mcp/`. For more complex web applications, consider [mounting your MCP server into a FastAPI or Starlette app](/deployment/http#integration-with-web-frameworks).
|
||||
Custom routes are served by the same web server as your MCP endpoint. They're available at the root of your domain while the MCP endpoint is at `/mcp`. For more complex web applications, consider [mounting your MCP server into a FastAPI or Starlette app](/deployment/http#integration-with-web-frameworks).
|
||||
|
||||
## Alternative Initialization Patterns
|
||||
|
||||
|
|
|
|||
|
|
@ -229,9 +229,10 @@ Environment variables are included in this section because they're runtime confi
|
|||
|
||||
<Expandable title="Deployment Fields">
|
||||
<ParamField body="transport" type="string" default="stdio">
|
||||
Protocol for client communication:
|
||||
Protocol for client communication. `"http"` and `"streamable-http"` both select FastMCP's Streamable HTTP transport:
|
||||
- `"stdio"`: Standard input/output for desktop clients
|
||||
- `"http"`: Network-accessible HTTP server
|
||||
- `"http"`: Network-accessible Streamable HTTP server
|
||||
- `"streamable-http"`: Explicit alias for Streamable HTTP
|
||||
- `"sse"`: Server-sent events
|
||||
</ParamField>
|
||||
|
||||
|
|
@ -241,12 +242,12 @@ Environment variables are included in this section because they're runtime confi
|
|||
- `"0.0.0.0"`: All network interfaces
|
||||
</ParamField>
|
||||
|
||||
<ParamField body="port" type="integer" default="3000">
|
||||
Port number for HTTP transport.
|
||||
<ParamField body="port" type="integer" default="8000">
|
||||
Port number for HTTP transport. If omitted, FastMCP uses the server runtime default.
|
||||
</ParamField>
|
||||
|
||||
<ParamField body="path" type="string" default="/mcp/">
|
||||
URL path for the MCP endpoint when using HTTP transport.
|
||||
<ParamField body="path" type="string" default="/mcp">
|
||||
URL path for the MCP endpoint when using HTTP transport. The default is `/mcp` for Streamable HTTP and `/sse` for SSE.
|
||||
</ParamField>
|
||||
|
||||
<ParamField body="log_level" type="string" default="INFO">
|
||||
|
|
@ -396,20 +397,20 @@ This flag tells FastMCP: "I already have the source code, skip any download/clon
|
|||
|
||||
Note: For filesystem sources (local Python files), this flag has no effect since they don't require preparation.
|
||||
|
||||
The configuration file works with all FastMCP commands:
|
||||
The configuration file works with server-loading commands that explicitly accept FastMCP config files:
|
||||
- **`run`** - Start the server in production mode
|
||||
- **`dev`** - Launch with the Inspector UI for development
|
||||
- **`dev inspector`** - Launch with the Inspector UI for development
|
||||
- **`inspect`** - View server capabilities and configuration
|
||||
- **`install`** - Install to Claude Desktop, Cursor, or other MCP clients
|
||||
- **`install`** - Install to Claude Desktop, Cursor, or another MCP client
|
||||
|
||||
When no file argument is provided, FastMCP searches the current directory for `fastmcp.json`. This means you can simply navigate to your project directory and run `fastmcp run` to start your server with all its configured settings.
|
||||
`run`, `dev inspector`, and `inspect` search the current directory for a file named exactly `fastmcp.json` when you don't pass a file argument, so you can navigate to your project directory and run `fastmcp run` to start your server with all its configured settings. `install` requires an explicit path to the config file — it never searches.
|
||||
|
||||
### CLI Override Behavior
|
||||
|
||||
Command-line arguments take precedence over configuration file values, allowing ad-hoc adjustments without modifying the file:
|
||||
|
||||
```bash
|
||||
# Config specifies port 3000, CLI overrides to 8080
|
||||
# Config specifies port 8000, CLI overrides to 8080
|
||||
fastmcp run fastmcp.json --port 8080
|
||||
|
||||
# Config specifies stdio, CLI overrides to HTTP
|
||||
|
|
@ -434,7 +435,7 @@ You can use different configuration files for different environments:
|
|||
- `prod.fastmcp.json` - Production settings
|
||||
- `test_fastmcp.json` - Test configuration
|
||||
|
||||
Any file with "fastmcp.json" in the name is recognized as a configuration file.
|
||||
Only a file named exactly `fastmcp.json` is auto-detected when you omit the path. Other FastMCP configuration files can use any `.json` name, but you must pass them explicitly.
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
@ -471,7 +472,7 @@ A configuration optimized for local development:
|
|||
"type": "uv",
|
||||
"python": "3.12",
|
||||
"dependencies": ["fastmcp[dev]"],
|
||||
"editable": "."
|
||||
"editable": ["."]
|
||||
},
|
||||
// HOW should it run?
|
||||
"deployment": {
|
||||
|
|
@ -510,7 +511,7 @@ A production-ready configuration with full dependency management:
|
|||
"transport": "http",
|
||||
"host": "0.0.0.0",
|
||||
"port": 3000,
|
||||
"path": "/api/mcp/",
|
||||
"path": "/api/mcp",
|
||||
"log_level": "INFO",
|
||||
"env": {
|
||||
"ENV": "production",
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue