fastmcp/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config.mdx

---
title: mcp_server_config
sidebarTitle: mcp_server_config
---

# `fastmcp.utilities.mcp_server_config.v1.mcp_server_config`


FastMCP Configuration File Support.

This module provides support for fastmcp.json configuration files that allow
users to specify server settings in a declarative format instead of using
command-line arguments.


## Functions

### `generate_schema` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L705" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
generate_schema(output_path: Path | str | None = None) -> dict[str, Any] | None
```


Generate JSON schema for fastmcp.json files.

This is used to create the schema file that IDEs can use for
validation and auto-completion.

**Args:**
- `output_path`: Optional path to write the schema to. If provided,
        writes the schema and returns None. If not provided,
        returns the schema as a dictionary.

**Returns:**
- JSON schema as a dictionary if output_path is None, otherwise None


## Classes

### `Environment` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L33" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Configuration for Python environment setup.


**Methods:**

#### `build_uv_run_command` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
build_uv_run_command(self, command: list[str]) -> list[str]
```

Build complete uv run command with environment args and command to execute.

**Args:**
- `command`: Command to execute (e.g., ["fastmcp", "run", "server.py"])

**Returns:**
- Complete command ready for subprocess.run, including "uv" prefix


#### `run_with_uv` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_with_uv(self, command: list[str]) -> None
```

Execute a command using uv run with this environment configuration.

**Args:**
- `command`: Command and arguments to execute (e.g., ["fastmcp", "run", "server.py"])


#### `needs_uv` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
needs_uv(self) -> bool
```

Check if this environment config requires uv to set up.

**Returns:**
- True if any environment settings require uv run


#### `prepare` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prepare(self, output_dir: Path | None = None) -> None
```

Prepare the Python environment using uv.

**Args:**
- `output_dir`: Directory where the persistent uv project will be created.
       If None, creates a temporary directory for ephemeral use.


### `Deployment` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L311" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Configuration for server deployment and runtime settings.


**Methods:**

#### `apply_runtime_settings` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L360" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
apply_runtime_settings(self, config_path: Path | None = None) -> None
```

Apply runtime settings like environment variables and working directory.

**Args:**
- `config_path`: Path to config file for resolving relative paths

Environment variables support interpolation with ${VAR_NAME} syntax.
For example: "API_URL": "https://api.${ENVIRONMENT}.example.com"
will substitute the value of the ENVIRONMENT variable at runtime.


### `MCPServerConfig` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L409" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Configuration for a FastMCP server.

This configuration file allows you to specify all settings needed to run
a FastMCP server in a declarative format.


**Methods:**

#### `validate_source` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L458" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_source(cls, v: dict | FileSystemSource) -> FileSystemSource
```

Validate and convert source to proper format.

Supports:
- Dict format: {"path": "server.py", "entrypoint": "app"}
- FileSystemSource instance (passed through)

No string parsing happens here - that's only at CLI boundaries.
MCPServerConfig works only with properly typed objects.


#### `validate_environment` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L481" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_environment(cls, v: dict | Environment) -> Environment
```

Validate and convert environment to Environment.

Accepts:
- Environment instance
- dict that can be converted to Environment


#### `validate_deployment` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L497" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_deployment(cls, v: dict | Deployment) -> Deployment
```

Validate and convert deployment to Deployment.

Accepts:
- Deployment instance
- dict that can be converted to Deployment


#### `from_file` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L513" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_file(cls, file_path: Path) -> MCPServerConfig
```

Load configuration from a JSON file.

**Args:**
- `file_path`: Path to the configuration file

**Returns:**
- MCPServerConfig instance

**Raises:**
- `FileNotFoundError`: If the file doesn't exist
- `json.JSONDecodeError`: If the file is not valid JSON
- `pydantic.ValidationError`: If the configuration is invalid


#### `from_cli_args` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L536" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_cli_args(cls, source: FileSystemSource, transport: Literal['stdio', 'http', 'sse', 'streamable-http'] | None = None, host: str | None = None, port: int | None = None, path: str | None = None, log_level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] | None = None, python: str | None = None, dependencies: list[str] | None = None, requirements: str | None = None, project: str | None = None, editable: str | None = None, env: dict[str, str] | None = None, cwd: str | None = None, args: list[str] | None = None) -> MCPServerConfig
```

Create a config from CLI arguments.

This allows us to have a single code path where everything
goes through a config object.

**Args:**
- `source`: Server source (FileSystemSource instance)
- `transport`: Transport protocol
- `host`: Host for HTTP transport
- `port`: Port for HTTP transport
- `path`: URL path for server
- `log_level`: Logging level
- `python`: Python version
- `dependencies`: Python packages to install
- `requirements`: Path to requirements file
- `project`: Path to project directory
- `editable`: Path to install in editable mode
- `env`: Environment variables
- `cwd`: Working directory
- `args`: Server arguments

**Returns:**
- MCPServerConfig instance


#### `find_config` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L613" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
find_config(cls, start_path: Path | None = None) -> Path | None
```

Find a fastmcp.json file in the specified directory.

**Args:**
- `start_path`: Directory to look in (defaults to current directory)

**Returns:**
- Path to the configuration file, or None if not found


#### `prepare` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L632" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

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

Prepare 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).

**Args:**
- `skip_source`: Skip source preparation if True
- `output_dir`: Directory to create the persistent uv project in (optional)


#### `prepare_environment` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L653" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prepare_environment(self, output_dir: Path | None = None) -> None
```

Prepare the Python environment.

**Args:**
- `output_dir`: If provided, creates a persistent uv project in this directory.
       If None, just populates uv's cache for ephemeral use.

Delegates to the environment's prepare() method


#### `prepare_source` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L664" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
prepare_source(self) -> None
```

Prepare the source for loading.

Delegates to the source's prepare() method.


#### `run_server` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L671" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
run_server(self, **kwargs: Any) -> None
```

Load and run the server with this configuration.

**Args:**
- `**kwargs`: Additional arguments to pass to server.run_async()
     These override config settings