FastMCP

https://gofastmcp.com/
Admin
FastMCP is a Python framework for building Model Context Protocol (MCP) servers and clients that...
Tokens:789,298
Snippets:6,517
Trust Score:8.8
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install psutil and run the system monitor example

Source: https://gofastmcp.com/apps/examples

Install the `psutil` dependency and run the system monitor example with the dev server. The app reads live CPU, memory, and disk stats, auto-refreshes via `SetInterval`, and accumulates up to 100 data points.

```bash
pip install psutil
fastmcp dev apps examples/apps/system_monitor/system_monitor_server.py

```

--------------------------------

### Install FastMCP apps and run the sales dashboard example

Source: https://gofastmcp.com/apps/examples

Install the FastMCP apps extra and run the sales dashboard example with the dev server. The dev UI lets you pick a tool and fill in arguments; in a real deployment the LLM provides those arguments from conversation context.

```bash
pip install "fastmcp[apps]"
fastmcp dev apps examples/apps/sales_dashboard/sales_dashboard_server.py

```

--------------------------------

### fastmcp install examples

Source: https://gofastmcp.com/cli/install-mcp

Command-line examples for installing MCP servers with fastmcp. Covers basic installs, explicit entrypoints, environment variables, env files, Python version and requirements, and custom config paths. Note that goose installs only accept --name, --with, and --python, and deeplinks cannot carry environment variables.

```bash
# Basic install with auto-detected server instance
fastmcp install claude-desktop server.py

# Install from fastmcp.json
fastmcp install claude-desktop fastmcp.json

# Explicit entrypoint with dependencies
fastmcp install claude-desktop server.py:my_server \
  --name "My Analysis Server" \
  --with pandas

# With environment variables
fastmcp install claude-code server.py \
  --env API_KEY=secret \
  --env DEBUG=true

# With env file
fastmcp install cursor server.py --env-file .env

# Specific Python version and requirements file
fastmcp install claude-desktop server.py \
  --python 3.11 \
  --with-requirements requirements.txt

# With custom config path (claude-desktop only)
fastmcp install claude-desktop server.py \
  --config-path "C:\Users\username\AppData\Local\Packages\Claude_xyz\LocalCache\Roaming\Claude"
```

--------------------------------

### Low-level SDK v2 server setup

Source: https://gofastmcp.com/getting-started/upgrading/from-low-level-sdk-v2

Before: the low-level Server class requires opening a transport, connecting streams, building initialization options, and running an event loop. This example shows the stdio transport setup.

```python
import asyncio

from mcp.server.lowlevel.server import Server
from mcp.server.stdio import stdio_server

server = Server("my-server")  # plus every on_* handler

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            server.create_initialization_options(),
        )

asyncio.run(main())

```

--------------------------------

### Install server with fastmcp install

Source: https://gofastmcp.com/cli/install-mcp

Registers a server with an MCP client. The first example installs server.py for Claude Desktop. The second installs with pandas and matplotlib for Claude Code. The third installs the current directory as an editable package for Cursor. Requires `uv` to be installed and available in the system PATH.

```bash
fastmcp install claude-desktop server.py
fastmcp install claude-code server.py --with pandas --with matplotlib
fastmcp install cursor server.py --with-editable .

```

--------------------------------

### ClerkProvider setup example

Source: https://gofastmcp.com/python-sdk/fastmcp-server-auth-providers-clerk

Shows how to configure a FastMCP server with Clerk OAuth using ClerkProvider. Requires a Clerk domain, client ID, client secret, and base URL.

```python
from fastmcp import FastMCP
from fastmcp.server.auth.providers.clerk import ClerkProvider

auth = ClerkProvider(
    domain="saving-primate-16.clerk.accounts.dev",
    client_id="your-clerk-client-id",
    client_secret="your-clerk-client-secret",
    base_url="https://my-server.com",
)

mcp = FastMCP("My Protected Server", auth=auth)
```

--------------------------------

### run_dev_apps

Source: https://gofastmcp.com/python-sdk/fastmcp-cli-apps_dev

Starts the full dev environment for a FastMCPApp server. Starts the user's MCP server on _mcp_port_, starts the Prefab dev UI on _dev_port_ (with an /mcp proxy to the user's server), then opens the browser.

```APIDOC
## run_dev_apps

### Description
Starts the full dev environment for a FastMCPApp server. Starts the user's MCP server on _mcp_port_, starts the Prefab dev UI on _dev_port_ (with an /mcp proxy to the user's server), then opens the browser.

### Function Signature
```python
run_dev_apps(server_spec: str) -> None
```

### Parameters
- **server_spec** (str) - Required - The specification of the server to start.

### Returns
None

```

--------------------------------

### Install OpenTelemetry packages and bootstrap auto-instrumentation

Source: https://gofastmcp.com/servers/telemetry

Installs the OpenTelemetry distro and OTLP exporter, then runs `opentelemetry-bootstrap -a install` to configure the SDK automatically.

```bash
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

```

--------------------------------

### Install with requirements file

Source: https://gofastmcp.com/integrations/claude-code

Use --with-requirements to install dependencies from a requirements.txt file.

```bash
fastmcp install claude-code server.py --with-requirements requirements.txt

```

--------------------------------

### Run the media picker example

Source: https://gofastmcp.com/apps/examples

Run the media picker example with the dev server. The model finds videos and passes YouTube links; the server verifies each link through oEmbed before showing it.

```bash
fastmcp dev apps examples/apps/media_picker/media_picker_server.py

```

--------------------------------

### Build and run with a pre-built environment

Source: https://gofastmcp.com/cli/running

Two-step workflow: first build the environment with `fastmcp project prepare` (slow, does dependency resolution), then run the server with `fastmcp run` using the prepared environment (fast, no install step). The prepared directory contains `pyproject.toml`, `.venv`, and `uv.lock` for reproducibility.

```bash
# Step 1: Build the environment (slow, does dependency resolution)
fastmcp project prepare fastmcp.json --output-dir ./env

# Step 2: Run using the prepared environment (fast, no install step)
fastmcp run fastmcp.json --project ./env

```

--------------------------------

### Install client-only package

Source: https://gofastmcp.com/clients/client-only-package

Install the fastmcp-slim package with the client extra to get MCP client functionality without the full server stack.

```bash
pip install "fastmcp-slim[client]"

```

--------------------------------

### Example FastAPI Application

Source: https://gofastmcp.com/integrations/fastapi

A complete FastAPI e-commerce API with CRUD operations for products. This base application is used by all subsequent examples in the guide.

```python
# Copy this FastAPI server into other code blocks in this guide

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

# Models
class Product(BaseModel):
    name: str
    price: float
    category: str
    description: str | None = None

class ProductResponse(BaseModel):
    id: int
    name: str
    price: float
    category: str
    description: str | None = None

# Create FastAPI app
app = FastAPI(title="E-commerce API", version="1.0.0")

# In-memory database
products_db = {
    1: ProductResponse(
        id=1, name="Laptop", price=999.99, category="Electronics"
    ),
    2: ProductResponse(
        id=2, name="Mouse", price=29.99, category="Electronics"
    ),
    3: ProductResponse(
        id=3, name="Desk Chair", price=299.99, category="Furniture"
    ),
}
next_id = 4

@app.get("/products", response_model=list[ProductResponse])
def list_products(
    category: str | None = None,
    max_price: float | None = None,
) -> list[ProductResponse]:
    """List all products with optional filtering."""
    products = list(products_db.values())
    if category:
        products = [p for p in products if p.category == category]
    if max_price:
        products = [p for p in products if p.price <= max_price]
    return products

@app.get("/products/{product_id}", response_model=ProductResponse)
def get_product(product_id: int):
    """Get a specific product by ID."""
    if product_id not in products_db:
        raise HTTPException(status_code=404, detail="Product not found")
    return products_db[product_id]

@app.post("/products", response_model=ProductResponse)
def create_product(product: Product):
    """Create a new product."""
    global next_id
    product_response = ProductResponse(id=next_id, **product.model_dump())
    products_db[next_id] = product_response
    next_id += 1
    return product_response

@app.put("/products/{product_id}", response_model=ProductResponse)
def update_product(product_id: int, product: Product):
    """Update an existing product."""
    if product_id not in products_db:
        raise HTTPException(status_code=404, detail="Product not found")
    products_db[product_id] = ProductResponse(
        id=product_id,
        **product.model_dump(),
    )
    return products_db[product_id]

@app.delete("/products/{product_id}")
def delete_product(product_id: int):
    """Delete a product."""
    if product_id not in products_db:
        raise HTTPException(status_code=404, detail="Product not found")
    del products_db[product_id]
    return {"message": "Product deleted"}

```

--------------------------------

### Pre-build environment with fastmcp project prepare

Source: https://gofastmcp.com/deployment/server-configuration

Creates a persistent uv project with dependencies pre-installed and then uses it to run the server, separating slow setup from fast execution.

```bash
# Create a persistent environment
fastmcp project prepare fastmcp.json --output-dir ./env

# Use the pre-built environment to run the server
fastmcp run fastmcp.json --project ./env

```

--------------------------------

### Run the sales dashboard example

Source: https://gofastmcp.com/apps/examples

Run the sales dashboard example with the dev server. This app shows what you can build with a single `app=True` tool and Prefab's chart and data components.

```bash
fastmcp dev apps examples/apps/sales_dashboard/sales_dashboard_server.py

```

--------------------------------

### Connect to FastMCP server and use client

Source: https://gofastmcp.com/python-sdk/fastmcp-client-client

Shows how to create a Client instance with a URL, use it as an async context manager, list resources, and call a tool.

```python
# Connect to FastMCP server
client = Client("http://localhost:8080")

async with client:
    # List available resources
    resources = await client.list_resources()

    # Call a tool
    result = await client.call_tool("my_tool", {"param": "value"})

```

--------------------------------

### Install FastMCP with apps extra

Source: https://gofastmcp.com/apps/quickstart

Install the 'fastmcp[apps]' package to get Prefab, the Python component library used for building app UIs.

```bash
pip install "fastmcp[apps]"

```

--------------------------------

### call_command usage examples

Source: https://gofastmcp.com/python-sdk/fastmcp-cli-client

Example invocations for call_command: calling a tool with key=value arguments, reading a resource URI, getting a prompt with --prompt, and passing complex JSON via --input-json.

```bash
fastmcp call server.py greet name=World
fastmcp call server.py resource://docs/readme
fastmcp call server.py analyze --prompt data='[1,2,3]'
fastmcp call http://server/mcp create --input-json '{"tags": ["a","b"]}'
```

--------------------------------

### Example project directory structure

Source: https://gofastmcp.com/servers/providers/filesystem

Directory structure of the example filesystem provider project. Shows the recommended organization with a server entry point and separate components for tools, resources, and prompts.

```text
examples/filesystem-provider/
├── server.py                    # Server entry point
└── components/
    ├── tools/
    │   ├── greeting.py          # greet, farewell tools
    │   └── calculator.py        # add, multiply tools
    ├── resources/
    │   └── config.py            # Static and templated resources
    └── prompts/
        └── assistant.py         # code_review, explain prompts


```

--------------------------------

### Add tags via RouteMap

Source: https://gofastmcp.com/integrations/openapi

Use RouteMap with mcp_tags to add custom tags to components from matching routes. The example adds tags to POST endpoints, GET detail endpoints, and GET list endpoints.

```python
from fastmcp.server.providers.openapi import RouteMap, MCPType

mcp = FastMCP.from_openapi(
    openapi_spec=spec,
    client=client,
    route_maps=[
        # Add custom tags to all POST endpoints
        RouteMap(
            methods=["POST"],
            pattern=r".*",
            mcp_type=MCPType.TOOL,
            mcp_tags={"write-operation", "api-mutation"}
        ),
        
        # Add different tags to detail view endpoints
        RouteMap(
            methods=["GET"],
            pattern=r".*\{.*\}.*",
            mcp_type=MCPType.RESOURCE_TEMPLATE,
            mcp_tags={"detail-view", "parameterized"}
        ),
        
        # Add tags to list endpoints
        RouteMap(
            methods=["GET"],
            pattern=r".*",
            mcp_type=MCPType.RESOURCE,
            mcp_tags={"list-data", "collection"}
        ),
    ],
)

```

--------------------------------

### Minimal server setup with FileSystemProvider

Source: https://gofastmcp.com/servers/providers/filesystem

Minimal server entry point that sets up a FilesystemDemo MCP server with a FileSystemProvider pointing to the components directory. Run with fastmcp run examples/filesystem-provider/server.py or inspect with fastmcp inspect examples/filesystem-provider/server.py.

```python
from pathlib import Path

from fastmcp import FastMCP
from fastmcp.server.providers import FileSystemProvider

provider = FileSystemProvider(
    root=Path(__file__).parent / "components",
    reload=True,
)

mcp = FastMCP("FilesystemDemo", providers=[provider])


```

--------------------------------

### Start a task with call_tool_task

Source: https://gofastmcp.com/clients/tasks

Use `call_tool_task` to start a task and get a `ToolTask` handle immediately. Requires the server to run the tool as a task (tool must be `task=True` and the tasks extension registered), otherwise raises `ToolError`.

```python
from fastmcp import Client
from fastmcp_tasks import call_tool_task

async with Client(server, mode="auto") as client:
    task = await call_tool_task(client, "slow_computation", {"duration": 10})
    print(f"Task started: {task.task_id}")

    # Do other work while it runs...

    result = await task.result()

```

--------------------------------

### Complete example: OAuth-protected MCP server with path prefix

Source: https://gofastmcp.com/deployment/http

A full working example combining all steps: defining routing structure, creating the GitHub auth provider, defining a tool, generating the MCP app, retrieving discovery routes, assembling the Starlette app, and running with uvicorn.

```python
from fastmcp import FastMCP
from fastmcp.server.auth.providers.github import GitHubProvider
from starlette.applications import Starlette
from starlette.routing import Mount
import uvicorn

# Define routing structure
ROOT_URL = "http://localhost:8000"
MOUNT_PREFIX = "/api"
MCP_PATH = "/mcp"

# Create OAuth provider
auth = GitHubProvider(
    client_id="your-client-id",
    client_secret="your-client-secret",
    base_url=f"{ROOT_URL}{MOUNT_PREFIX}",
    # issuer_url defaults to base_url - path-aware discovery works automatically
)

# Create MCP server
mcp = FastMCP("Protected Server", auth=auth)

@mcp.tool
def analyze(data: str) -> dict:
    return {"result": f"Analyzed: {data}"}

# Create MCP app
mcp_app = mcp.http_app(path=MCP_PATH)

# Get discovery routes for root level
well_known_routes = auth.get_well_known_routes(mcp_path=MCP_PATH)

# Assemble the application
app = Starlette(
    routes=[
        *well_known_routes,
        Mount(MOUNT_PREFIX, app=mcp_app),
    ],
    lifespan=mcp_app.lifespan,
)

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

```

--------------------------------

### Configure CodeMode discovery tools with ListTools and GetSchemas

Source: https://gofastmcp.com/servers/transforms/code-mode

CodeMode includes built-in discovery tools (Search, GetSchemas, GetTags, ListTools). The Search example shows limiting results. The GetTags examples show tag browsing and literal parameter rendering. The ListTools example shows a custom CodeMode setup with ListTools and GetSchemas.

```python
Search(default_limit=5)  # return at most 5 results per search

```

```python
- math (3 tools)
- text (2 tools)
- untagged (1 tool)

```

```python
- `sort` (string, one of "top"/"recent", default "recent")

```

```python
from fastmcp.experimental.transforms.code_mode import CodeMode, ListTools, GetSchemas

code_mode = CodeMode(
    discovery_tools=[ListTools(), GetSchemas()],
)

```

--------------------------------

### Full contact manager example with FastMCPApp

Source: https://gofastmcp.com/apps/fastmcp-app

Complete example combining entry point, backend tools, Pydantic form, manual form, state, actions, and multi-visibility. Shows how to define tools with @app.tool() and a UI with @app.ui(), then mount the app on a FastMCP server.

```python
from __future__ import annotations

from typing import Literal

from prefab_ui.actions import SetState, ShowToast
from prefab_ui.actions.mcp import CallTool
from prefab_ui.app import PrefabApp
from prefab_ui.components import (
    Badge, Button, Column, ForEach, Form,
    Heading, Input, Muted, Row, Separator, Text,
)
from prefab_ui.rx import RESULT, Rx
from pydantic import BaseModel, Field
from fastmcp import FastMCP, FastMCPApp

contacts_db: list[dict] = [
    {"name": "Arthur Dent", "email": "arthur@earth.com", "category": "Customer"},
    {"name": "Ford Prefect", "email": "ford@betelgeuse.org", "category": "Partner"},
]


class ContactModel(BaseModel):
    name: str = Field(title="Full Name", min_length=1)
    email: str = Field(title="Email")
    category: Literal["Customer", "Vendor", "Partner", "Other"] = "Other"


app = FastMCPApp("Contacts")


@app.tool()
def save_contact(data: ContactModel) -> list[dict]:
    """Save a new contact and return the updated list."""
    contacts_db.append(data.model_dump())
    return list(contacts_db)


@app.tool()
def search_contacts(query: str) -> list[dict]:
    """Filter contacts by name or email."""
    q = query.lower()
    return [
        c for c in contacts_db
        if q in c["name"].lower() or q in c["email"].lower()
    ]


@app.tool(model=True)
def list_contacts() -> list[dict]:
    """Return all contacts. Visible to both the model and the UI."""
    return list(contacts_db)


@app.ui()
def contact_manager() -> PrefabApp:
    """Open the contact manager."""
    with Column(gap=6, css_class="p-6") as view:
        Heading("Contacts")

        with ForEach("contacts") as contact:
            with Row(gap=2, align="center"):
                Text(contact.name, css_class="font-medium")
                Muted(contact.email)
                Badge(contact.category)

        Separator()

        Heading("Add Contact", level=3)
        Form.from_model(
            ContactModel,
            on_submit=CallTool(
                "save_contact",
                on_success=[
                    SetState("contacts", RESULT),
                    ShowToast("Contact saved!", variant="success"),
                ],
                on_error=ShowToast("Failed to save", variant="error"),
            ),
        )

        Separator()

        Heading("Search", level=3)
        with Form(
            on_submit=CallTool(
                "search_contacts",
                arguments={"query": Rx("query")},
                on_success=SetState("contacts", RESULT),
            )
        ):
            Input(name="query", placeholder="Search by name or email...")
            Button("Search")

    return PrefabApp(view=view, state={"contacts": list(contacts_db)})


mcp = FastMCP("Contacts Server", providers=[app])

if __name__ == "__main__":
    mcp.run()

```

--------------------------------

### Declare dependencies with command-line flags

Source: https://gofastmcp.com/cli/install-mcp

Specifies server dependencies directly via command-line flags. The first example installs pandas and sqlalchemy>=2.0 for Claude Desktop. The second installs the current directory as editable and uses a requirements.txt file for Cursor.

```bash
fastmcp install claude-desktop server.py --with pandas --with "sqlalchemy>=2.0"
fastmcp install cursor server.py --with-editable . --with-requirements requirements.txt

```

--------------------------------

### Advanced Configuration with Requirements and Output

Source: https://gofastmcp.com/integrations/mcp-json-configuration

Installs a server with a custom name, a requirements file, a project directory, and an environment variable. The output shows the generated JSON with `--project`, `--with-requirements`, and `env`.

```bash
fastmcp install mcp-json ml_server.py \
  --name "ML Analysis Server" \
  --with-requirements requirements.txt \
  --project /home/user/ml-project \
  --env GPU_DEVICE=0

```

```json
{
  "ML Analysis Server": {
    "command": "uv",
    "args": [
      "run",
      "--project",
      "/home/user/ml-project",
      "--with",
      "fastmcp",
      "--with-requirements",
      "/home/user/requirements.txt",
      "fastmcp",
      "run",
      "/home/user/ml_server.py"
    ],
    "env": {
      "GPU_DEVICE": "0"
    }
  }
}

```

--------------------------------

### Single-server MCP configuration

Source: https://gofastmcp.com/clients/client-only-package

Client-only installs support single-server MCP configuration. This example passes a configuration dictionary with an mcpServers key to the Client constructor.

```python
from fastmcp import Client

config = {
    "mcpServers": {
        "weather": {
            "url": "https://weather.example.com/mcp"
        }
    }
}

client = Client(config)

```

--------------------------------

### Client-only supported transports

Source: https://gofastmcp.com/clients/client-only-package

Client-only installs support remote and subprocess transports. This example shows creating a client for a remote MCP server and a local server over stdio.

```python
from pathlib import Path
from fastmcp import Client

# Remote MCP server
http_client = Client("https://example.com/mcp")

# Local MCP server over stdio
stdio_client = Client(Path("my_server.py"))

```

--------------------------------

### Install with project directory

Source: https://gofastmcp.com/integrations/claude-code

Use --project to run your server within a specific project context, telling uv to use the project's configuration files and virtual environment.

```bash
fastmcp install claude-code server.py --project /path/to/my-project

```

--------------------------------

### MCPServerConfig.prepare

Source: https://gofastmcp.com/python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config

Prepares environment and source for execution. When output_dir is provided, creates a persistent uv project; otherwise does ephemeral caching.

```APIDOC
## MCPServerConfig.prepare

### Description
Prepares environment and source for execution. When output_dir is provided, creates a persistent uv project. When output_dir is None, does ephemeral caching (for backwards compatibility).

### Method
prepare

### Signature
prepare(self, skip_source: bool = False, output_dir: Path | None = None) -> None

### Parameters
- **skip_source** (bool) - Optional - Skip source preparation if True.
- **output_dir** (Path | None) - Optional - Directory to create the persistent uv project in.

### Returns
None
```

--------------------------------

### Environment editable packages configuration

Source: https://gofastmcp.com/deployment/server-configuration

Specifies a list of paths to packages to install in editable/development mode. Useful for local development and supports multiple packages for monorepo setups.

```json
"editable": ["."]
```

```json
"editable": [".", "../shared-lib", "/path/to/another-package"]
```

--------------------------------

### Install with individual packages

Source: https://gofastmcp.com/integrations/claude-code

Use the --with flag to specify packages your server needs. You can use this flag multiple times.

```bash
fastmcp install claude-code server.py --with pandas --with requests

```

--------------------------------

### Access FastMCP server instance via ctx.fastmcp

Source: https://gofastmcp.com/servers/context

Shows how to access the underlying FastMCP server instance using the ctx.fastmcp property, for example to get the server name.

```python
@mcp.tool
async def my_tool(ctx: Context) -> None:
    # Access the FastMCP server instance
    server_name = ctx.fastmcp.name
    ...
```

--------------------------------

### Filesystem source configuration example

Source: https://gofastmcp.com/deployment/server-configuration

Example JSON configuration for a filesystem source, specifying the type, path, and entrypoint. The path is resolved relative to the configuration file's location.

```json
"source": {
  "type": "filesystem",
  "path": "src/server.py",
  "entrypoint": "mcp"
}
```

--------------------------------

### fastmcp dev apps command examples

Source: https://gofastmcp.com/cli/running

Launches a browser-based preview UI for servers with Prefab App tools. The first command uses default ports (MCP port 8000, dev port 8080); the second specifies custom ports. Requires `fastmcp[apps]` installed via `pip install "fastmcp[apps]"`.

```bash
fastmcp dev apps server.py
fastmcp dev apps server.py:mcp --mcp-port 9000 --dev-port 9090
```

--------------------------------

### Full environment configuration example

Source: https://gofastmcp.com/deployment/server-configuration

Complete example of the environment configuration object with type, python, dependencies, and editable fields.

```json
"environment": {
  "type": "uv",
  "python": ">=3.10",
  "dependencies": ["pandas", "numpy"],
  "editable": ["."]
}
```

--------------------------------

### Clone and set up the repository

Source: https://gofastmcp.com/development/contributing

Clones the FastMCP repository, installs dependencies with uv, and installs commit hooks using prek.

```bash
git clone https://github.com/YOUR-USERNAME/fastmcp.git
cd fastmcp
uv sync
uv run prek install

```

--------------------------------

### Generate stdio command with fastmcp install stdio

Source: https://gofastmcp.com/cli/install-mcp

Outputs the shell command an MCP host would use to start your server over stdio. The output is shown in the comment. Use --copy to copy to clipboard.

```bash
fastmcp install stdio server.py
# Output: uv run --with fastmcp fastmcp run /absolute/path/to/server.py
```

--------------------------------

### new

Source: https://gofastmcp.com/python-sdk/fastmcp-client-client

Creates a new client instance with the same configuration but fresh session state.

```APIDOC
## new

### Description
Create a new client instance with the same configuration but fresh session state. This creates a new client with the same transport, handlers, and configuration, but with no active session. Useful for creating independent sessions that don’t share state with the original client.

### Method
Method

### Signature
`new(self) -> Client[ClientTransportT]`

### Returns
- **Client[ClientTransportT]** - A new Client instance with the same configuration but disconnected state.
```

--------------------------------

### Create MCP server from OpenAPI spec

Source: https://gofastmcp.com/integrations/openapi

Use FastMCP.from_openapi() to convert an OpenAPI specification into an MCP server. Requires an HTTP client (httpx2.AsyncClient) and the OpenAPI spec as a dictionary. The example shows a basic setup with a public API.

```python
import httpx2
from fastmcp import FastMCP

# Create an HTTP client for your API
client = httpx2.AsyncClient(base_url="https://api.example.com")

# Load your OpenAPI spec 
openapi_spec = httpx2.get("https://api.example.com/openapi.json").json()

# Create the MCP server
mcp = FastMCP.from_openapi(
    openapi_spec=openapi_spec,
    client=client,
    name="My API Server"
)

if __name__ == "__main__":
    mcp.run()
```

--------------------------------

### Access request metadata with ctx.request_id and ctx.client_id

Source: https://gofastmcp.com/servers/context

Use ctx.request_id and ctx.client_id to get the current MCP request ID and client ID. client_id may be None if not provided during initialization. The example returns a dict with request information.

```python
@mcp.tool
async def request_info(ctx: Context) -> dict:
    """Return information about the current request."""
    return {
        "request_id": ctx.request_id,
        "client_id": ctx.client_id or "Unknown client"
    }

```

--------------------------------

### Basic Server Installation and Output

Source: https://gofastmcp.com/integrations/mcp-json-configuration

Installs a basic MCP server and shows the generated JSON configuration. The output uses `uv run` with the `fastmcp` package.

```bash
fastmcp install mcp-json dice_server.py

```

```json
{
  "Dice Server": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "fastmcp",
      "fastmcp", 
      "run",
      "/home/user/dice_server.py"
    ]
  }
}

```

--------------------------------

### get_server() -> FastMCP

Source: https://gofastmcp.com/python-sdk/fastmcp-server-dependencies

Gets the current FastMCP server instance directly. In a background-task worker the tasks extension's resolver is consulted first, so a mounted-child task resolves to the child server rather than the root that started the worker.

```APIDOC
## get_server

### Description
Get the current FastMCP server instance directly. In a background-task worker the tasks extension's resolver is consulted first, so a mounted-child task resolves to the child server rather than the root that started the worker (#3571).

### Signature
```python
get_server() -> FastMCP
```

### Returns
- The active FastMCP server.

### Raises
- `RuntimeError`: If no server in context.
```

--------------------------------

### Basic lifespan with @lifespan decorator

Source: https://gofastmcp.com/servers/lifespan

Defines a lifespan that runs setup once when the server starts and teardown when it stops. The yielded dict becomes the lifespan context. Always use try/finally for cleanup to ensure it runs even if the server is cancelled.

```python
from fastmcp import FastMCP
from fastmcp.server.lifespan import lifespan

@lifespan
async def app_lifespan(server):
    # Setup: runs once when server starts
    print("Starting up...")
    try:
        yield {"started_at": "2024-01-01"}
    finally:
        # Teardown: runs when server stops
        print("Shutting down...")

mcp = FastMCP("MyServer", lifespan=app_lifespan)
```

--------------------------------

### Install otel-desktop-viewer on macOS

Source: https://gofastmcp.com/servers/telemetry

Install the lightweight single-binary tool for local trace visualization using Homebrew, or download from GitHub releases.

```bash
# macOS
brew install nico-barbas/brew/otel-desktop-viewer

# Or download from GitHub releases
```

--------------------------------

### ApiKeyAuth middleware: check API keys for protected tools

Source: https://gofastmcp.com/servers/middleware

Middleware that checks the x-api-key HTTP header against a set of valid keys for protected tools. Raises ToolError for invalid keys; unprotected tools pass through. Includes FastMCP setup and example tools.

```python
from fastmcp import FastMCP
from fastmcp.server.middleware import Middleware, MiddlewareContext
from fastmcp.server.dependencies import get_http_headers
from fastmcp.exceptions import ToolError

class ApiKeyAuth(Middleware):
    def __init__(self, valid_keys: set[str], protected_tools: set[str]):
        self.valid_keys = valid_keys
        self.protected_tools = protected_tools

    async def on_call_tool(self, context: MiddlewareContext, call_next):
        tool_name = context.message.name

        if tool_name not in self.protected_tools:
            return await call_next(context)

        headers = get_http_headers() or {}
        api_key = headers.get("x-api-key")

        if api_key not in self.valid_keys:
            raise ToolError(f"Invalid API key for protected tool: {tool_name}")

        return await call_next(context)

mcp = FastMCP("Secure Server")
mcp.add_middleware(ApiKeyAuth(
    valid_keys={"key-1", "key-2"},
    protected_tools={"delete_user", "admin_panel"}
))

@mcp.tool
def delete_user(user_id: str) -> str:
    return f"Deleted user {user_id}"

@mcp.tool
def get_user(user_id: str) -> str:
    return f"User {user_id}"  # Not protected

```

--------------------------------

### Install with --copy flag

Source: https://gofastmcp.com/integrations/mcp-json-configuration

Copies the generated configuration directly to the clipboard. Requires the `pyperclip` Python package; if missing, an error with installation instructions is shown.

```bash
fastmcp install mcp-json server.py --copy

```

--------------------------------

### AuthProvider.get_well_known_routes

Source: https://gofastmcp.com/python-sdk/fastmcp-server-auth-auth

Get well-known discovery routes for this authentication provider. This is a utility method that filters get_routes() to return only well-known discovery routes (those starting with /.well-known/). Well-known routes provide OAuth metadata and discovery endpoints that clients use to discover authentication capabilities.

```APIDOC
## AuthProvider.get_well_known_routes

### Description
Get well-known discovery routes for this authentication provider. This is a utility method that filters get_routes() to return only well-known discovery routes (those starting with /.well-known/). Well-known routes provide OAuth metadata and discovery endpoints that clients use to discover authentication capabilities. These routes should be mounted at the root level of the application to comply with RFC 8414 and RFC 9728.

### Method
get_well_known_routes(self, mcp_path: str | None = None) -> list[Route]

### Parameters
- **mcp_path** (str | None) - Optional - The path where the MCP endpoint is mounted (e.g., "/mcp"). This is used to construct path-scoped well-known URLs.

### Returns
- list[Route] - List of well-known discovery routes (typically mounted at root level)
```

--------------------------------

### Configuration and runtime result example

Source: https://gofastmcp.com/deployment/server-configuration

Shows a configuration with placeholders and the resulting runtime values after interpolation, illustrating how placeholders are replaced with actual environment variable values.

```json
// Configuration
{
  "deployment": {
    "env": {
      "API_URL": "https://api.${ENVIRONMENT}.example.com",
      "DB_HOST": "${DB_HOST}"
    }
  }
}

// Result at runtime
{
  "API_URL": "https://api.production.example.com",
  "DB_HOST": "db.example.com"
}

```

--------------------------------

### apps function signature

Source: https://gofastmcp.com/python-sdk/fastmcp-cli-cli

Previews a FastMCPApp UI in the browser. Starts the MCP server from SERVER_SPEC on --mcp-port, launches a local dev UI on --dev-port with a tool picker and AppBridge host, then opens the browser automatically. Requires fastmcp[apps] to be installed (prefab-ui).

```python
apps(server_spec: str) -> None
```
Tokens:
Raw