Skip to main content

Documentation Index

Fetch the complete documentation index at: https://flashmcpdocs.com/llms.txt

Use this file to discover all available pages before exploring further.

FlashMCP servers can be run in different ways depending on your application’s needs, from local command-line tools to persistent web services. This guide covers the primary methods for running your server, focusing on the available transport protocols: STDIO, Streamable HTTP, and SSE.

​
The run() Method

FlashMCP servers can be run directly from Python by calling the run() method on a FlashMCP instance.
For maximum compatibility, it’s best practice to place the run() call within an if __name__ == "__main__": block. This ensures the server starts only when the script is executed directly, not when imported as a module.
my_server.py
from FlashMCP import FlashMCP

mcp = FlashMCP(name="MyServer")

@mcp.tool()
def hello(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run()
You can now run this MCP server by executing python my_server.py. MCP servers can be run with a variety of different transport options, depending on your application’s requirements. The run() method can take a transport argument and other transport-specific keyword arguments to configure how the server operates.

​
The FlashMCP CLI

FlashMCP also provides a command-line interface for running servers without modifying the source code. After installing FlashMCP, you can run your server directly from the command line: 
FlashMCP run server.py
Important: When using FlashMCP run, it ignores the if __name__ == "__main__" block entirely. Instead, it looks for a FlashMCP object named mcp, server, or app and calls its run() method directly with the transport options you specify.This means you can use FlashMCP run to override the transport specified in your code, which is particularly useful for testing or changing deployment methods without modifying the code.
You can specify transport options and other configuration: 
FlashMCP run server.py --transport sse --port 9000
For development and testing, you can use the dev command to run your server with the MCP Inspector: 
FlashMCP dev server.py
See the CLI documentation for detailed information about all available commands and options.

​
Transport Options

Below is a comparison of available transport options to help you choose the right one for your needs:
TransportUse CasesRecommendation
STDIOLocal tools, command-line scripts, and integrations with clients like Claude DesktopBest for local tools and when clients manage server processes
Streamable HTTPWeb-based deployments, microservices, exposing MCP over a networkRecommended choice for web-based deployments
SSEExisting web-based deployments that rely on SSEDeprecated - prefer Streamable HTTP for new projects

​
STDIO

The STDIO transport is the default and most widely compatible option for local MCP server execution. It is ideal for local tools, command-line integrations, and clients like Claude Desktop. However, it has the disadvantage of having to run the MCP code locally, which can introduce security concerns with third-party servers. STDIO is the default transport, so you don’t need to specify it when calling run(). However, you can specify it explicitly to make your intent clear: 
from FlashMCP import FlashMCP

mcp = FlashMCP()

if __name__ == "__main__":
    mcp.run(transport="stdio")
When using Stdio transport, you will typically not run the server yourself as a separate process. Rather, your clients will spin up a new server process for each session. As such, no additional configuration is required.

​
Streamable HTTP

Streamable HTTP is a modern, efficient transport for exposing your MCP server via HTTP. It is the recommended transport for web-based deployments. To run a server using Streamable HTTP, you can use the run() method with the transport argument set to "streamable-http". This will start a Uvicorn server on the default host (127.0.0.1), port (8000), and path (/mcp). 
from FlashMCP import FlashMCP

mcp = FlashMCP()

if __name__ == "__main__":
    mcp.run(transport="streamable-http")
To customize the host, port, path, or log level, provide appropriate keyword arguments to the run() method. 
from FlashMCP import FlashMCP

mcp = FlashMCP()

if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host="127.0.0.1",
        port=4200,
        path="/my-custom-path",
        log_level="debug",
    )

​
SSE

The SSE transport is deprecated and may be removed in a future version. New applications should use Streamable HTTP transport instead.
Server-Sent Events (SSE) is an HTTP-based protocol for server-to-client streaming. While FlashMCP still supports SSE, it is deprecated and Streamable HTTP is preferred for new projects. To run a server using SSE, you can use the run() method with the transport argument set to "sse". This will start a Uvicorn server on the default host (127.0.0.1), port (8000), and with default SSE path (/sse) and message path (/messages/). 
from FlashMCP import FlashMCP

mcp = FlashMCP()

if __name__ == "__main__":
    mcp.run(transport="sse")
Notice that the client in the above example uses an explicit SSETransport to connect to the server. FlashMCP will attempt to infer the appropriate transport from the provided configuration, but HTTP URLs are assumed to be Streamable HTTP (as of FlashMCP 2.3.0).
To customize the host, port, or log level, provide appropriate keyword arguments to the run() method. You can also adjust the SSE path (which clients should connect to) and the message POST endpoint (which clients use to send subsequent messages). 
from FlashMCP import FlashMCP

mcp = FlashMCP()

if __name__ == "__main__":
    mcp.run(
        transport="sse",
        host="127.0.0.1",
        port=4200,
        log_level="debug",
        path="/my-custom-sse-path",
    )

​
Async Usage

FlashMCP provides both synchronous and asynchronous APIs for running your server. The run() method seen in previous examples is a synchronous method that internally uses anyio.run() to run the asynchronous server. For applications that are already running in an async context, FlashMCP provides the run_async() method. 
from FlashMCP import FlashMCP
import asyncio

mcp = FlashMCP(name="MyServer")

@mcp.tool()
def hello(name: str) -> str:
    return f"Hello, {name}!"

async def main():
    # Use run_async() in async contexts
    await mcp.run_async(transport="streamable-http")

if __name__ == "__main__":
    asyncio.run(main())
The run() method cannot be called from inside an async function because it already creates its own async event loop internally. If you attempt to call run() from inside an async function, you’ll get an error about the event loop already running.Always use run_async() inside async functions and run() in synchronous contexts.
Both run() and run_async() accept the same transport arguments, so all the examples above apply to both methods.

​
Custom Routes

You can also add custom web routes to your FlashMCP server, which will be exposed alongside the MCP endpoint. To do so, use the @custom_route decorator. Note that this is less flexible than using a full ASGI framework, but can be useful for adding simple endpoints like health checks to your standalone server. 
from FlashMCP import FlashMCP
from starlette.requests import Request
from starlette.responses import PlainTextResponse

mcp = FlashMCP("MyServer")

@mcp.custom_route("/health", methods=["GET"])
async def health_check(request: Request) -> PlainTextResponse:
    return PlainTextResponse("OK")

if __name__ == "__main__":
    mcp.run()