Server Configuration with fastmcp.json

New in version: 2.11.4 FastMCP supports declarative configuration through fastmcp.json files. This is the canonical and preferred way to configure FastMCP projects, providing a single source of truth for server settings, dependencies, and deployment options that replaces complex command-line arguments.

Overview

The fastmcp.json configuration file allows you to define all aspects of your FastMCP server in a structured, shareable format. Instead of remembering command-line arguments or writing shell scripts, you declare your server’s configuration once and use it everywhere. When you have a fastmcp.json file, running your server becomes as simple as:

# Run the server using the configuration
fastmcp run fastmcp.json

# Or if fastmcp.json exists in the current directory
fastmcp run

This configuration approach ensures reproducible deployments across different environments, from local development to production servers. It works seamlessly with Claude Desktop, VS Code extensions, and any MCP-compatible client.

JSON Schema Support

FastMCP provides JSON schemas for IDE autocomplete and validation. Add the schema reference to your fastmcp.json for enhanced developer experience:

{
  "$schema": "https://gofastmcp.com/schemas/fastmcp_config/v1.json",
  "entrypoint": {
    "file": "server.py",
    "object": "mcp"
  }
}

Two schema URLs are available:

Version-specific: https://gofastmcp.com/schemas/fastmcp_config/v1.json
Latest version: https://gofastmcp.com/schemas/fastmcp_config/latest.json

Modern IDEs like VS Code will automatically provide autocomplete suggestions, validation, and inline documentation when the schema is specified.

File Structure

The fastmcp.json file has three main sections, each controlling a different aspect of your server:

{
  "$schema": "https://gofastmcp.com/schemas/fastmcp_config/v1.json",
  "entrypoint": {
    "file": "server.py",
    "object": "mcp"
  },
  "environment": {
    // Python environment and dependencies
  },
  "deployment": {
    // Runtime configuration
  }
}

Only the entrypoint field is required. The environment and deployment sections are optional and provide additional configuration when needed.

Configuration Fields

Entrypoint

The entrypoint specifies which Python file and object contains your FastMCP server. This field is required and supports multiple formats to accommodate different project structures.

Entrypoint Configuration

entrypoint

object | string

required

The server entry point. Can be specified in three formats:Object format (recommended): Explicit file and object specification

"entrypoint": {
  "file": "src/server.py",
  "object": "mcp"
}

String with object: File path with colon and object name

"entrypoint": "src/server.py:app"

String format: Simple path to Python file (searches for common names: mcp, server, app)

"entrypoint": "server.py"

Show Path Resolution

File paths are resolved relative to the configuration file’s location
If your fastmcp.json is in a project root and references src/server.py, FastMCP will look for the server at <project_root>/src/server.py
When no object is specified, FastMCP automatically searches for common server names: mcp, server, or app

Environment

The environment section configures Python dependencies and version requirements. When specified, FastMCP uses uv to create an isolated environment for your server, ensuring reproducible deployments across different systems.

Environment Configuration

environment

object

Optional Python environment configuration. When any field is specified, FastMCP automatically creates an isolated environment using uv.

Show Environment Fields

python

string

Python version constraint. Examples:

Exact version: "3.12"
Minimum version: ">=3.10"
Version range: ">=3.10,<3.13"

dependencies

list[str]

List of pip packages with optional version specifiers (PEP 508 format).

"dependencies": ["pandas>=2.0", "requests", "httpx"]

requirements

string

Path to a requirements.txt file, resolved relative to the config file location.

"requirements": "requirements.txt"

project

string

Path to a project directory containing pyproject.toml for uv project management.

"project": "."

editable

string

Path to a package to install in editable/development mode.

"editable": "./my-package"

When environment configuration is provided, FastMCP:

Creates an isolated Python environment using uv
Installs the specified dependencies
Runs your server in this clean environment

Deployment

The deployment section controls runtime configuration including transport protocol, networking, logging, and environment variables.

Deployment Configuration

deployment

object

Optional runtime configuration for the server.

Show Deployment Fields

transport

string

default:"stdio"

Protocol for client communication:

"stdio": Standard input/output for desktop clients
"http": Network-accessible HTTP server
"sse": Server-sent events

host

string

default:"127.0.0.1"

Network interface to bind (HTTP transport only):

"127.0.0.1": Local connections only
"0.0.0.0": All network interfaces

port

integer

default:"3000"

Port number for HTTP transport.

path

string

default:"/mcp/"

URL path for the MCP endpoint when using HTTP transport.

log_level

string

default:"INFO"

Server logging verbosity. Options:

"DEBUG": Detailed debugging information
"INFO": General informational messages
"WARNING": Warning messages
"ERROR": Error messages only
"CRITICAL": Critical errors only

env

object

Environment variables to set when running the server. Supports ${VAR_NAME} syntax for runtime interpolation.

"env": {
  "API_KEY": "secret-key",
  "DATABASE_URL": "postgres://${DB_USER}@${DB_HOST}/mydb"
}

cwd

string

Working directory for the server process. Relative paths are resolved from the config file location.

args

list[str]

Command-line arguments to pass to the server, passed after -- to the server’s argument parser.

"args": ["--config", "server-config.json"]

Usage with CLI Commands

FastMCP automatically detects and uses fastmcp.json files, making server execution simple and consistent:

# Auto-detect fastmcp.json in current directory
cd my-project
fastmcp run  # No arguments needed!

# Or specify a configuration file explicitly
fastmcp run prod.fastmcp.json

The configuration file works with all FastMCP commands:

run - Start the server in production mode
dev - Launch with the Inspector UI for development
inspect - View server capabilities and configuration
install - Install to Claude Desktop, Cursor, or other MCP clients

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.

Custom Naming Patterns

You can use different configuration files for different environments:

fastmcp.json - Default configuration
dev.fastmcp.json - Development settings
prod.fastmcp.json - Production settings
test_fastmcp.json - Test configuration

Any file with “fastmcp.json” in the name is recognized as a configuration file.

Examples

A minimal configuration for a simple server:

{
  "$schema": "https://gofastmcp.com/schemas/fastmcp_config/v1.json",
  "entrypoint": {
    "file": "server.py",
    "object": "mcp"
  }
}

This configuration explicitly specifies the server object name (app), making it clear which object contains your FastMCP server. Uses all defaults: STDIO transport, no special dependencies, standard logging.

CLI Override Behavior

Command-line arguments take precedence over configuration file values, allowing ad-hoc adjustments without modifying the file:

# Config specifies port 3000, CLI overrides to 8080
fastmcp run fastmcp.json --port 8080

# Config specifies stdio, CLI overrides to HTTP
fastmcp run fastmcp.json --transport http

# Add extra dependencies not in config
fastmcp run fastmcp.json --with requests --with httpx

This precedence order enables:

Quick testing of different settings
Environment-specific overrides in deployment scripts
Debugging with increased log levels
Temporary configuration changes

Best Practices

When using fastmcp.json for your projects, consider these recommendations: Version Control: Always commit your fastmcp.json to version control. It’s essential project documentation that ensures others can run your server correctly. Environment Variables: Use the env field for configuration values instead of hardcoding them in your Python code. For sensitive values, consider using environment variable references or separate secret management. Dependency Management: Specify exact versions for production dependencies to ensure reproducible builds:

{
  "dependencies": [
    "pandas==2.1.0",
    "requests==2.31.0"
  ]
}

Path Resolution: Remember that paths in the configuration are relative to the config file location. Use relative paths for portability:

{
  "entrypoint": "./src/server.py",
  "environment": {
    "requirements": "./requirements.txt"
  }
}

Development Workflow: Use separate configuration files for different environments rather than constantly modifying a single file. The CLI’s override behavior makes it easy to switch between configurations.

Environment Variable Interpolation

The env field in deployment configuration supports runtime interpolation of environment variables using ${VAR_NAME} syntax. This enables dynamic configuration based on your deployment environment:

{
  "deployment": {
    "env": {
      "API_URL": "https://api.${ENVIRONMENT}.example.com",
      "DATABASE_URL": "postgres://${DB_USER}:${DB_PASS}@${DB_HOST}/myapp",
      "CACHE_KEY": "myapp_${ENVIRONMENT}_${VERSION}"
    }
  }
}

When the server starts, FastMCP replaces ${ENVIRONMENT}, ${DB_USER}, etc. with values from your system’s environment variables. If a variable doesn’t exist, the placeholder is preserved as-is. Example: If your system has ENVIRONMENT=production and DB_HOST=db.example.com:

// 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"
}

This feature is particularly useful for:

Deploying the same configuration across development, staging, and production
Keeping sensitive values out of configuration files
Building dynamic URLs and connection strings
Creating environment-specific prefixes or suffixes

Migrating from CLI Arguments

If you’re currently using command-line arguments or shell scripts, migrating to fastmcp.json simplifies your workflow. Here’s how common CLI patterns map to configuration: CLI Command:

uv run --with pandas --with requests \
  fastmcp run server.py \
  --transport http \
  --port 8000 \
  --log-level INFO

Equivalent fastmcp.json:

{
  "$schema": "https://gofastmcp.com/schemas/fastmcp_config/v1.json",
  "entrypoint": {
    "file": "server.py",
    "object": "mcp"
  },
  "environment": {
    "dependencies": ["pandas", "requests"]
  },
  "deployment": {
    "transport": "http",
    "port": 8000,
    "log_level": "INFO"
  }
}

Now simply run:

fastmcp run  # Automatically finds and uses fastmcp.json

The configuration file approach provides better documentation, easier sharing, and consistent execution across different environments while maintaining the flexibility to override settings when needed.

Get Started

Servers

Clients

Integrations

Patterns

Tutorials

Server Configuration with fastmcp.json

Overview

JSON Schema Support

File Structure

Configuration Fields

Entrypoint

Entrypoint Configuration

Environment

Environment Configuration

Deployment

Deployment Configuration

Usage with CLI Commands

Custom Naming Patterns

Examples

CLI Override Behavior

Best Practices

Environment Variable Interpolation

Migrating from CLI Arguments

Get Started

Servers

Clients

Integrations

Patterns

Tutorials

​Overview

​JSON Schema Support

​File Structure

​Configuration Fields

​Entrypoint

Entrypoint Configuration

​Environment

Environment Configuration

​Deployment

Deployment Configuration

​Usage with CLI Commands

​Custom Naming Patterns

​Examples

​CLI Override Behavior

​Best Practices

​Environment Variable Interpolation

​Migrating from CLI Arguments

Overview

JSON Schema Support

File Structure

Configuration Fields

Entrypoint

Environment

Deployment

Usage with CLI Commands

Custom Naming Patterns

Examples

CLI Override Behavior

Best Practices

Environment Variable Interpolation

Migrating from CLI Arguments