Client Transports

The FastMCP Client communicates with MCP servers through transport objects that handle the underlying connection mechanics. While the client can automatically select a transport based on what you pass to it, instantiating transports explicitly gives you full control over configuration—environment variables, authentication, session management, and more.

Think of transports as configurable adapters between your client code and MCP servers. Each transport type handles a different communication pattern: subprocesses with pipes, HTTP connections, or direct in-memory calls.

​

Choosing the Right Transport

• Use STDIO Transport when you need to run local MCP servers with full control over their environment and lifecycle
• Use Remote Transports when connecting to production services or shared MCP servers running independently
• Use In-Memory Transport for testing FastMCP servers without subprocess or network overhead
• Use MCP JSON Configuration when you need to connect to multiple servers defined in configuration files

​

STDIO Transport

STDIO (Standard Input/Output) transport communicates with MCP servers through subprocess pipes. This is the standard mechanism used by desktop clients like Claude Desktop and is the primary way to run local MCP servers.

​

The Client Runs the Server

With STDIO transport, your client:

• Starts the server as a subprocess when you connect
• Manages the server’s lifecycle (start, stop, restart)
• Controls the server’s environment and configuration
• Communicates through stdin/stdout pipes

This architecture enables powerful local integrations but requires understanding environment isolation and process management.

​

Environment Isolation

STDIO servers run in isolated environments by default. This is a security feature enforced by the MCP protocol to prevent accidental exposure of sensitive data.

When your client launches an MCP server:

• The server does NOT inherit your shell’s environment variables
• API keys, paths, and other configuration must be explicitly passed
• The working directory and system paths may differ from your shell

To pass environment variables to your server, use the env parameter:

from fastmcp import Client

# If your server needs environment variables (like API keys),
# you must explicitly pass them:
client = Client(
    "my_server.py",
    env={"API_KEY": "secret", "DEBUG": "true"}
)

# This won't work - the server runs in isolation:
# export API_KEY="secret"  # in your shell
# client = Client("my_server.py")  # server can't see API_KEY

​

Basic Usage

To use STDIO transport, you create a transport instance with the command and arguments needed to run your server:

from fastmcp.client.transports import StdioTransport

transport = StdioTransport(
    command="python",
    args=["my_server.py"]
)
client = Client(transport)

You can configure additional settings like environment variables, working directory, or command arguments:

transport = StdioTransport(
    command="python",
    args=["my_server.py", "--verbose"],
    env={"LOG_LEVEL": "DEBUG"},
    cwd="/path/to/server"
)
client = Client(transport)

For convenience, the client can also infer STDIO transport from file paths, but this doesn’t allow configuration:

from fastmcp import Client

client = Client("my_server.py")  # Limited - no configuration options

​

Environment Variables

Since STDIO servers don’t inherit your environment, you need strategies for passing configuration. Here are two common approaches:

Selective forwarding passes only the variables your server actually needs:

import os
from fastmcp.client.transports import StdioTransport

required_vars = ["API_KEY", "DATABASE_URL", "REDIS_HOST"]
env = {
    var: os.environ[var] 
    for var in required_vars 
    if var in os.environ
}

transport = StdioTransport(
    command="python",
    args=["server.py"],
    env=env
)
client = Client(transport)

Loading from .env files keeps configuration separate from code:

from dotenv import dotenv_values
from fastmcp.client.transports import StdioTransport

env = dotenv_values(".env")
transport = StdioTransport(
    command="python",
    args=["server.py"],
    env=env
)
client = Client(transport)

​

Session Persistence

STDIO transports maintain sessions across multiple client contexts by default (keep_alive=True). This improves performance by reusing the same subprocess for multiple connections, but can be controlled when you need isolation.

By default, the subprocess persists between connections:

from fastmcp.client.transports import StdioTransport

transport = StdioTransport(
    command="python",
    args=["server.py"]
)
client = Client(transport)

async def efficient_multiple_operations():
    async with client:
        await client.ping()
    
    async with client:  # Reuses the same subprocess
        await client.call_tool("process_data", {"file": "data.csv"})

For complete isolation between connections, disable session persistence:

transport = StdioTransport(
    command="python",
    args=["server.py"],
    keep_alive=False
)
client = Client(transport)

Use keep_alive=False when you need complete isolation (e.g., in test suites) or when server state could cause issues between connections.

​

Specialized STDIO Transports

FastMCP provides convenience transports that are thin wrappers around StdioTransport with pre-configured commands:

• PythonStdioTransport - Uses python command for .py files
• NodeStdioTransport - Uses node command for .js files
• UvxStdioTransport - Uses uvx for Python packages (uses env_vars parameter)
• NpxStdioTransport - Uses npx for Node packages (uses env_vars parameter)

For most use cases, instantiate StdioTransport directly with your desired command. These specialized transports are primarily useful for client inference shortcuts.

​

Remote Transports

Remote transports connect to MCP servers running as web services. This is a fundamentally different model from STDIO transports—instead of your client launching and managing a server process, you connect to an already-running service that manages its own environment and lifecycle.

​

Streamable HTTP Transport

Streamable HTTP is the recommended transport for production deployments, providing efficient bidirectional streaming over HTTP connections.

• Class: StreamableHttpTransport
• Server compatibility: FastMCP servers running with mcp run --transport http

The transport requires a URL and optionally supports custom headers for authentication and configuration:

from fastmcp.client.transports import StreamableHttpTransport

# Basic connection
transport = StreamableHttpTransport(url="https://api.example.com/mcp")
client = Client(transport)

# With custom headers for authentication
transport = StreamableHttpTransport(
    url="https://api.example.com/mcp",
    headers={
        "Authorization": "Bearer your-token-here",
        "X-Custom-Header": "value"
    }
)
client = Client(transport)

For convenience, FastMCP also provides authentication helpers:

from fastmcp.client.auth import BearerAuth

client = Client(
    "https://api.example.com/mcp",
    auth=BearerAuth("your-token-here")
)

​

SSE Transport (Legacy)

Server-Sent Events transport is maintained for backward compatibility but is superseded by Streamable HTTP for new deployments.

• Class: SSETransport
• Server compatibility: FastMCP servers running with mcp run --transport sse

SSE transport supports the same configuration options as Streamable HTTP:

from fastmcp.client.transports import SSETransport

transport = SSETransport(
    url="https://api.example.com/sse",
    headers={"Authorization": "Bearer token"}
)
client = Client(transport)

Use Streamable HTTP for new deployments unless you have specific infrastructure requirements for SSE.

​

In-Memory Transport

In-memory transport connects directly to a FastMCP server instance within the same Python process. This eliminates both subprocess management and network overhead, making it ideal for testing and development.

• Class: FastMCPTransport

from fastmcp import FastMCP, Client
import os

mcp = FastMCP("TestServer")

@mcp.tool
def greet(name: str) -> str:
    prefix = os.environ.get("GREETING_PREFIX", "Hello")
    return f"{prefix}, {name}!"

client = Client(mcp)

async with client:
    result = await client.call_tool("greet", {"name": "World"})

​

MCP JSON Configuration Transport

This transport supports the emerging MCP JSON configuration standard for defining multiple servers:

• Class: MCPConfigTransport

config = {
    "mcpServers": {
        "weather": {
            "url": "https://weather.example.com/mcp",
            "transport": "http"
        },
        "assistant": {
            "command": "python",
            "args": ["./assistant.py"],
            "env": {"LOG_LEVEL": "INFO"}
        }
    }
}

client = Client(config)

async with client:
    # Tools are namespaced by server
    weather = await client.call_tool("weather_get_forecast", {"city": "NYC"})
    answer = await client.call_tool("assistant_ask", {"question": "What?"})