URL: https://gofastmcp.com/integrations/mcp-json-configuration
Title: MCP JSON Configuration 🤝 FastMCP - FastMCP

Documentation Index
Fetch the complete documentation index at:
/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
Meet
Prefect Horizon
, the enterprise MCP gateway built by the team behind FastMCP
FastMCP
home page
v3
Prefect Horizon
PrefectHQ/fastmcp
25,596
PrefectHQ/fastmcp
25,596
Search...
Navigation
Integrations
MCP JSON Configuration 🤝 FastMCP
Search the docs...
Ctrl
K
Documentation
Get Started
Welcome!
Installation
Quickstart
Servers
Overview
Core Components
Working with Tools
MCP Providers
Interactivity
Extensibility
Auth
Deployment
Apps
Overview
Quickstart
NEW
FastMCPApp
NEW
Interactive Tools
NEW
Generative UI
NEW
Custom HTML
Reference
Clients
Overview
Client-Only Package
Transports
fastmcp-remote
Operations
UPDATED
Authentication
UPDATED
Integrations
Auth
Web Frameworks
AI Assistants
AI SDKs
MCP.json
More
Settings
CLI
Upgrading
Development
What's New
FAQ
On this page
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
Integrations
MCP JSON Configuration 🤝 FastMCP
Copy page
Generate standard MCP configuration files for any compatible client
Copy page
New in version
2.10.3
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:
{
"
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.
{
"
command
"
:
"
python
"
}
​
args
(optional)
An array of command-line arguments passed to the server executable. Arguments are passed in order.
{
"
args
"
:
[
"
server.py
"
,
"
--verbose
"
,
"
--port
"
,
"
8080
"
]
}
​
env
(optional)
An object containing environment variables to set when launching the server. All values must be strings.
{
"
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
For the best experience, use FastMCP’s first-class integrations:
fastmcp install claude-code
,
fastmcp install claude-desktop
, or
fastmcp install cursor
. Use MCP JSON generation for advanced use cases and unsupported clients.
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):
fastmcp
install
mcp-json
server.py
This outputs the server configuration JSON with the server name as the root key:
{
"
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:
{
"
mcpServers
"
:
{
"
My Server
"
:
{
"
command
"
:
"
uv
"
,
"
args
"
:
[
"
run
"
,
"
--with
"
,
"
fastmcp
"
,
"
fastmcp
"
,
"
run
"
,
"
/absolute/path/to/server.py
"
]
}
}
}
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.
Different MCP clients may have specific configuration requirements or formatting needs. Always consult your client’s documentation to ensure proper integration.
​
Configuration Options
​
Server Naming
# 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:
# 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):
fastmcp.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:
fastmcp
install
mcp-json
fastmcp.json
​
Environment Variables
# 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:
# 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:
# 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:
fastmcp
install
mcp-json
server.py
--copy
The
--copy
flag requires the
pyperclip
Python package. If not installed, you’ll see an error message with installation instructions.
​
Usage Examples
​
Basic Server
fastmcp
install
mcp-json
dice_server.py
Output:
{
"
Dice Server
"
:
{
"
command
"
:
"
uv
"
,
"
args
"
:
[
"
run
"
,
"
--with
"
,
"
fastmcp
"
,
"
fastmcp
"
,
"
run
"
,
"
/home/user/dice_server.py
"
]
}
}
​
Production Server with Dependencies
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
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:
{
"
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:
{
"
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:
fastmcp
install
mcp-json
server.py
>
mcp-config.json
Use in shell scripts:
#!/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:
fastmcp
install
mcp-json
server.py
--project
.
Output:
{
"
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:
fastmcp.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:
{
"
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
):
{
"
mcpServers
"
:
{
"
Weather
"
:
{
"
command
"
:
"
uvx
"
,
"
args
"
:
[
"
--from
"
,
"
weather-mcp
"
,
"
weather-server
"
]
}
}
}
You can also pin Python versions or add extra dependencies:
{
"
mcpServers
"
:
{
"
My Server
"
:
{
"
command
"
:
"
uvx
"
,
"
args
"
:
[
"
--python
"
,
"
3.12
"
,
"
--with
"
,
"
requests
"
,
"
my-mcp-server
"
]
}
}
}
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.
​
Integration with MCP Clients
The generated configuration works with any MCP-compatible application:
​
Claude Desktop
Prefer
fastmcp install claude-desktop
for automatic installation. Use MCP JSON for advanced configuration needs.
Copy the
mcpServers
object into
~/.claude/claude_desktop_config.json
​
Cursor
Prefer
fastmcp install cursor
for automatic installation. Use MCP JSON for advanced configuration needs.
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:
{
"
<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)
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.
​
Requirements
uv
: Must be installed and available in your system PATH
pyperclip
(optional): Required only for
--copy
functionality
Install uv if not already available:
# macOS
brew
install
uv
# Linux/Windows
curl
-LsSf
https://astral.sh/uv/install.sh
|
sh
Pydantic AI 🤝 FastMCP
Previous
Settings
Next
Ctrl
+I
discord
github
website
x
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform
Assistant
Responses are generated using AI and may contain mistakes.
\n\n
\n
\n \n
\n
