MCP JSON Configuration 🤝 FastMCP

import { VersionBadge } from "/snippets/version-badge.mdx"

FastMCP can generate standard MCP JSON configuration files that work with any MCP-compatible client including Claude Desktop, VS Code, Cursor, and other applications that support the Model Context Protocol.

MCP JSON Configuration Standard

The MCP JSON configuration format is an emergent standard that has developed across the MCP ecosystem. This format defines how MCP clients should configure and launch MCP servers, providing a consistent way to specify server commands, arguments, and environment variables.

Configuration Structure

The standard uses a mcpServers object where each key represents a server name and the value contains the server's configuration:

json

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "VAR": "value"
      }
    }
  }
}

Server Configuration Fields

`command` (required)

The executable command to run the MCP server. This should be an absolute path or a command available in the system PATH.

json

{
  "command": "python"
}

`args` (optional)

An array of command-line arguments passed to the server executable. Arguments are passed in order.

json

{
  "args": ["server.py", "--verbose", "--port", "8080"]
}

`env` (optional)

An object containing environment variables to set when launching the server. All values must be strings.

json

{
  "env": {
    "API_KEY": "secret-key",
    "DEBUG": "true",
    "PORT": "8080"
  }
}

Client Adoption

This format is widely adopted across the MCP ecosystem:

Claude Desktop: Uses ~/.claude/claude_desktop_config.json
Cursor: Uses ~/.cursor/mcp.json
VS Code: Uses workspace .vscode/mcp.json
Other clients: Many MCP-compatible applications follow this standard

Overview

<Note> **For the best experience, use FastMCP's first-class integrations:** [`fastmcp install claude-code`](/integrations/claude-code), [`fastmcp install claude-desktop`](/integrations/claude-desktop), or [`fastmcp install cursor`](/integrations/cursor). Use MCP JSON generation for advanced use cases and unsupported clients. </Note>

The fastmcp install mcp-json command generates configuration in the standard mcpServers format used across the MCP ecosystem. This is useful when:

Working with unsupported clients - Any MCP client not directly integrated with FastMCP
CI/CD environments - Automated configuration generation for deployments
Configuration sharing - Easy distribution of server setups to team members
Custom tooling - Integration with your own MCP management tools
Manual setup - When you prefer to manually configure your MCP client

Basic Usage

Generate configuration and output to stdout (useful for piping):

bash

fastmcp install mcp-json server.py

This outputs the server configuration JSON with the server name as the root key:

json

{
  "My Server": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "fastmcp", 
      "fastmcp",
      "run",
      "/absolute/path/to/server.py"
    ]
  }
}

To use this in a client configuration file, add it to the mcpServers object in your client's configuration:

json

{
  "mcpServers": {
    "My Server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp", 
        "fastmcp",
        "run",
        "/absolute/path/to/server.py"
      ]
    }
  }
}

<Note> When using `--python`, `--project`, or `--with-requirements`, the generated configuration will include these options in the `uv run` command, ensuring your server runs with the correct Python version and dependencies. </Note> <Note> Different MCP clients may have specific configuration requirements or formatting needs. Always consult your client's documentation to ensure proper integration. </Note>

Configuration Options

Server Naming

bash

# Use server's built-in name (from FastMCP constructor)
fastmcp install mcp-json server.py

# Override with custom name
fastmcp install mcp-json server.py --name "Custom Server Name"

Dependencies

Add Python packages your server needs:

bash

# Single package
fastmcp install mcp-json server.py --with pandas

# Multiple packages  
fastmcp install mcp-json server.py --with pandas --with requests --with httpx

# Editable local package
fastmcp install mcp-json server.py --with-editable ./my-package

# From requirements file
fastmcp install mcp-json server.py --with-requirements requirements.txt

You can also use a fastmcp.json configuration file (recommended):

json

{
  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
  "source": {
    "path": "server.py",
    "entrypoint": "mcp"
  },
  "environment": {
    "dependencies": ["pandas", "matplotlib", "seaborn"]
  }
}

Then simply install with:

bash

fastmcp install mcp-json fastmcp.json

Environment Variables

bash

# Individual environment variables
fastmcp install mcp-json server.py \
  --env API_KEY=your-secret-key \
  --env DEBUG=true

# Load from .env file
fastmcp install mcp-json server.py --env-file .env

Python Version and Project Directory

Specify Python version or run within a specific project:

bash

# Use specific Python version
fastmcp install mcp-json server.py --python 3.11

# Run within a project directory
fastmcp install mcp-json server.py --project /path/to/project

Server Object Selection

Use the same file.py:object notation as other FastMCP commands:

bash

# Auto-detects server object (looks for 'mcp', 'server', or 'app')
fastmcp install mcp-json server.py

# Explicit server object
fastmcp install mcp-json server.py:my_custom_server

Clipboard Integration

Copy configuration directly to your clipboard for easy pasting:

bash

fastmcp install mcp-json server.py --copy

<Note> The `--copy` flag requires the `pyperclip` Python package. If not installed, you'll see an error message with installation instructions. </Note>

Usage Examples

Basic Server

bash

fastmcp install mcp-json dice_server.py

Output:

json

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

Production Server with Dependencies

bash

fastmcp install mcp-json api_server.py \
  --name "Production API Server" \
  --with requests \
  --with python-dotenv \
  --env API_BASE_URL=https://api.example.com \
  --env TIMEOUT=30

Advanced Configuration

bash

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

Output:

json

{
  "Production API Server": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "fastmcp",
      "--with",
      "python-dotenv", 
      "--with",
      "requests",
      "fastmcp",
      "run", 
      "/home/user/api_server.py"
    ],
    "env": {
      "API_BASE_URL": "https://api.example.com",
      "TIMEOUT": "30"
    }
  }
}

The advanced configuration example generates:

json

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

Pipeline Usage

Save configuration to file:

bash

fastmcp install mcp-json server.py > mcp-config.json

Use in shell scripts:

bash

#!/bin/bash
CONFIG=$(fastmcp install mcp-json server.py --name "CI Server")
echo "$CONFIG" | jq '."CI Server".command'
# Output: "uv"

UV-Managed Project Dependencies

For servers that live inside a uv-managed project (with pyproject.toml), use the --project flag to run within that project's environment:

bash

fastmcp install mcp-json server.py --project .

Output:

json

{
  "My Server": {
    "command": "uv",
    "args": [
      "run",
      "--project",
      "/absolute/path/to/project",
      "--with",
      "fastmcp",
      "fastmcp",
      "run",
      "/absolute/path/to/project/server.py"
    ]
  }
}

You can also use fastmcp.json with a local project:

json

{
  "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
  "source": {
    "path": "server.py"
  },
  "environment": {
    "project": "."
  }
}

If your server needs additional packages beyond those in pyproject.toml, add them via the dependencies array or --with.

Published Packages with `uvx`

If your team publishes MCP servers as pip packages, you can configure clients to run them with uvx directly instead of uv run. For example, if your package is called my-mcp-server and provides a CLI entry point of the same name:

json

{
  "mcpServers": {
    "My Server": {
      "command": "uvx",
      "args": ["my-mcp-server"]
    }
  }
}

If the package name differs from the CLI command (e.g., package weather-mcp with command weather-server):

json

{
  "mcpServers": {
    "Weather": {
      "command": "uvx",
      "args": ["--from", "weather-mcp", "weather-server"]
    }
  }
}

You can also pin Python versions or add extra dependencies:

json

{
  "mcpServers": {
    "My Server": {
      "command": "uvx",
      "args": [
        "--python", "3.12",
        "--with", "requests",
        "my-mcp-server"
      ]
    }
  }
}

<Note> `fastmcp install mcp-json` generates `uv run` configurations for local development. For published packages, you'll typically write the `uvx` configuration manually or generate it through your own packaging workflow. </Note>

Integration with MCP Clients

The generated configuration works with any MCP-compatible application:

Claude Desktop

<Note> **Prefer [`fastmcp install claude-desktop`](/integrations/claude-desktop)** for automatic installation. Use MCP JSON for advanced configuration needs. </Note> Copy the `mcpServers` object into `~/.claude/claude_desktop_config.json`

Cursor

<Note> **Prefer [`fastmcp install cursor`](/integrations/cursor)** for automatic installation. Use MCP JSON for advanced configuration needs. </Note> Add to `~/.cursor/mcp.json`

VS Code

Add to your workspace's .vscode/mcp.json file

Custom Applications

Use the JSON configuration with any application that supports the MCP protocol

Configuration Format

The generated configuration outputs a server object with the server name as the root key:

json

{
  "<server-name>": {
    "command": "<executable>",
    "args": ["<arg1>", "<arg2>", "..."],
    "env": {
      "<ENV_VAR>": "<value>"
    }
  }
}

To use this in an MCP client, add it to the client's mcpServers configuration object.

Fields:

command: The executable to run (always uv for FastMCP servers)
args: Command-line arguments including dependencies and server path
env: Environment variables (only included if specified)

<Warning> **All file paths in the generated configuration are absolute paths**. This ensures the configuration works regardless of the working directory when the MCP client starts the server. </Warning>

Requirements

uv: Must be installed and available in your system PATH
pyperclip (optional): Required only for --copy functionality

Install uv if not already available:

bash

# macOS
brew install uv

# Linux/Windows  
curl -LsSf https://astral.sh/uv/install.sh | sh

MCP JSON Configuration Standard

Configuration Structure

Server Configuration Fields

command (required)

args (optional)

env (optional)

Client Adoption

Overview

Basic Usage

Configuration Options

Server Naming

Dependencies

Environment Variables

Python Version and Project Directory

Server Object Selection

Clipboard Integration

Usage Examples

Basic Server

Production Server with Dependencies

Advanced Configuration

Pipeline Usage

UV-Managed Project Dependencies

Published Packages with uvx

Integration with MCP Clients

Claude Desktop

Cursor

VS Code

Custom Applications

Configuration Format

Requirements

`command` (required)

`args` (optional)

`env` (optional)

Published Packages with `uvx`