PrefectHQ/fastmcp · error · FileNotFoundError

No server specification or fastmcp.json found

Error message

No server specification or fastmcp.json found

What it means

The fastmcp CLI's load_and_merge_config requires either an explicit server specification argument or a fastmcp.json in the current directory. When neither is found it logs guidance and raises FileNotFoundError, aborting commands like run, inspect, inspector, and worker.

Solutions

1. Pass the server spec explicitly, e.g. `fastmcp run server.py`
2. Create a fastmcp.json in the current directory
3. cd into the project directory that contains fastmcp.json

Example fix

// before
$ fastmcp run
FileNotFoundError: No server specification or fastmcp.json found

// after
$ fastmcp run server.py

from pathlib import Path
spec = server_arg or ("fastmcp.json" if Path("fastmcp.json").exists() else None)
if spec is None:
    sys.exit("pass a server file or create fastmcp.json")

try:
    cfg = load_and_merge_config(server_spec=spec)
except FileNotFoundError:
    logger.error("No fastmcp.json in %s; pass server path explicitly", Path.cwd())
    sys.exit(2)

When it happens

Trigger: Running `fastmcp run` / `fastmcp inspect` etc. without a server argument from a directory that contains no fastmcp.json.

Common situations: Running the CLI from the wrong working directory; forgetting to create fastmcp.json; misspelling the server file path so it isn't recognized as a spec.

Related errors

• At least one of version_gte or version_lt must be specified
• cache_scope requires cache_ttl; a scope without a TTL does…
• Cannot specify both a name as first argument and as keyword…
• CodeMode requires pydantic-monty for the Monty sandbox…
• Configuration file not found

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/3f43d5a374cf79a0. Report an issue: GitHub.

Appendix: source

Thrown at fastmcp_slim/fastmcp/utilities/cli.py:64

    Returns:
        Tuple of (MCPServerConfig, resolved_server_spec)
    """
    config = None
    config_path = None

    # Auto-detect fastmcp.json if no server_spec provided
    if server_spec is None:
        config_path = Path("fastmcp.json")
        if not config_path.exists():
            found_config = MCPServerConfig.find_config()
            if found_config:
                config_path = found_config
            else:
                logger.error(
                    "No server specification provided and no fastmcp.json found in current directory.\n"
                    "Please specify a server file or create a fastmcp.json configuration."
                )
                raise FileNotFoundError("No server specification or fastmcp.json found")

        resolved_spec = str(config_path)
        logger.info(f"Using configuration from {config_path}")
    else:
        resolved_spec = server_spec

    # Load config if server_spec is a .json file
    if resolved_spec.endswith(".json"):
        config_path = Path(resolved_spec)
        if config_path.exists():
            try:
                with open(config_path) as f:
                    data = json.load(f)

                # Check if it's an MCPConfig first (has canonical mcpServers key)
                if "mcpServers" in data:
                    # MCPConfig - we don't process these here, just pass through
                    pass

View on GitHub (pinned to 1f02114297)