The FastMCP Client

Programmatic client for interacting with MCP servers through a well-typed, Pythonic interface.

The fastmcp.Client class provides a programmatic interface for interacting with any MCP server. It handles protocol details and connection management automatically, letting you focus on the operations you want to perform.

Use it to add MCP tools to a Python script, web application, or AI agent. Your application chooses which operations to call; the client discovers and executes them on the server.

Creating a Client

You provide a server source and the client automatically infers the appropriate transport mechanism. This example calls an inventory tool from ordinary Python code and uses its result in the application:

import asyncio

from fastmcp import Client, FastMCP

server = FastMCP("Inventory")


@server.tool
def stock_count(sku: str) -> int:
    """Return the available stock for a product."""
    return {"WIDGET": 12}.get(sku, 0)


async def main():
    async with Client(server) as client:
        result = await client.call_tool("stock_count", {"sku": "WIDGET"})
        print(f"Available stock: {result.data}")  # Available stock: 12


asyncio.run(main())

All client operations require using the async with context manager for proper connection lifecycle management.

Use Cases

Applications and Scripts

Call a known tool with call_tool() when your application already knows what work to do, such as checking inventory before preparing an order. Use result.data for Python values, or result.content when you need the MCP content blocks, including text, images, and other media. The same client API works with an in-memory server, a local subprocess, or a remote HTTP server; choose the connection in Transports.

AI Agents and Chat Applications

Use list_tools() to discover each tool’s name, description, and input_schema, then adapt those definitions to your model SDK’s tool format. When the model requests a tool call, pass its name and parsed arguments to call_tool() and return the result to the model in the SDK’s expected format. Your application owns the conversation loop and decides which tools it permits the model to call.

See Calling Tools for discovery, result formats, and error handling. Client Groups let an agent use tools from several independently configured servers through one catalog.

Testing Servers

Pass your server instance to Client(server) in a test to exercise tool discovery and execution without starting a network listener. Assert the returned values just as your application would. The server testing guide shows how to share a client through pytest fixtures.

Discovering and Downloading Skills

An agent can also use the client to retrieve instructions and supporting files from servers that expose skills as resources. The skills client utilities provide list_skills() for discovery, get_skill_manifest() for inspecting files, and download_skill() or sync_skills() for saving them locally.

Choosing a Transport

The client automatically selects a transport based on what you pass to it, but different transports have different characteristics that matter for your use case.

In-memory transport connects directly to a FastMCP server instance within the same Python process. Use this for testing and development where you want to eliminate subprocess and network complexity. The server shares your process’s environment and memory space.

from fastmcp import Client, FastMCP

server = FastMCP("TestServer")
client = Client(server)  # In-memory, no network or subprocess

STDIO transport launches a server as a subprocess and communicates through stdin/stdout pipes. This is the standard mechanism used by desktop clients like Claude Desktop. By default, the subprocess receives the MCP SDK’s default environment; pass an explicit transport when you need to add environment variables, set a working directory, or control process reuse.

from pathlib import Path
from fastmcp import Client
from fastmcp.client.transports import PythonStdioTransport

# Simple inference from file path
client = Client(Path("my_server.py"))

# With explicit environment configuration
transport = PythonStdioTransport(
    "my_server.py",
    env={"API_KEY": "secret"},
)
client = Client(transport)

HTTP transport connects to servers running as web services. Use this for production deployments where the server runs independently and manages its own lifecycle.

from fastmcp import Client

client = Client("https://api.example.com/mcp")

See Transports for detailed configuration options including authentication headers, session persistence, and multi-server configurations.

Configuration-Based Clients

Create clients from MCP configuration dictionaries, which can include multiple servers. While there is no official standard for MCP configuration format, FastMCP follows established conventions used by tools like Claude Desktop.

config = {
    "mcpServers": {
        "weather": {
            "url": "https://weather-api.example.com/mcp"
        },
        "assistant": {
            "command": "python",
            "args": ["./assistant_server.py"]
        }
    }
}

client = Client(config)

async with client:
    # Tools are prefixed with server names
    weather_data = await client.call_tool("weather_get_forecast", {"city": "London"})
    response = await client.call_tool("assistant_answer_question", {"question": "What's the capital of France?"})

    # Resources use prefixed URIs
    icons = await client.read_resource("weather://weather/icons/sunny")

A multi-server configuration presents one aggregate MCP endpoint. Each entry still configures its own transport, headers, and auth, but every backend shares the outer client’s negotiated protocol era, handlers, and client-level policy. To hold several fully independent connections — each with its own protocol mode and handlers — see Client Groups.

Connection Lifecycle

The client uses context managers for connection management. When you enter the context, the client establishes a connection and negotiates the protocol era with the server. Metadata returned by either legacy initialization or modern discovery is exposed through the same client properties.

from fastmcp import Client, FastMCP

mcp = FastMCP(name="MyServer", instructions="Use the greet tool to say hello!")

@mcp.tool
def greet(name: str) -> str:
    """Greet a user by name."""
    return f"Hello, {name}!"

async with Client(mcp) as client:
    # Protocol negotiation already happened automatically
    assert client.server_info is not None
    assert client.server_capabilities is not None
    print(f"Server: {client.server_info.name}")
    print(f"Instructions: {client.instructions}")
    print(f"Capabilities: {client.server_capabilities.tools}")

For advanced scenarios where you need precise control over when initialization happens, disable automatic initialization and call initialize() manually. initialize() is a handshake-era operation, so pin the connection with mode="legacy": the modern protocol has no initialize round trip, and calling it on a modern connection raises.

from pathlib import Path
from fastmcp import Client

client = Client(Path("my_mcp_server.py"), auto_initialize=False, mode="legacy")

async with client:
    # Connection established, but not initialized yet
    print(f"Connected: {client.is_connected()}")
    print(f"Initialized: {client.initialize_result is not None}")  # False

    # Initialize manually with custom timeout
    result = await client.initialize(timeout=10.0)
    print(f"Server: {result.server_info.name}")

    # Now ready for operations
    tools = await client.list_tools()

Protocol negotiation

MCP has two protocol eras: the original legacy era, which begins every connection with an initialize handshake, and the modern era (protocol version 2026-07-28 and later), which a client discovers by probing the server’s server/discover endpoint. The mode parameter controls which era the client negotiates when it connects.

By default, mode="auto". The client probes server/discover and adopts the modern protocol when the server responds; for any server that is not positive evidence of modern support, it falls back to the legacy handshake. This makes the default safe against a mixed fleet of legacy and modern servers.

from fastmcp import Client

# Negotiate the newest era the server supports (the default)
client = Client("https://example.com/mcp", mode="auto")

Set mode="legacy" to force the initialize handshake. This behaves identically to earlier FastMCP versions and is the opt-out if a server misbehaves under discovery or you need the legacy initialize result object.

client = Client("https://example.com/mcp", mode="legacy")

Legacy mode is also what carries the pushed form of a server’s requests. The handshake opens a persistent back-channel down which a server can send a sampling, roots, or elicitation request mid-call, and the modern era removed it. Your handlers are unaffected by that: a sampling, roots, or elicitation handler you register answers a modern server’s input-required rounds from the same registration. Pin mode="legacy" when you connect to a server that pushes, or when your code calls client.ping() or transport.get_session_id(), which need the session the modern era does not open.

Conversely, background tasks are modern-only: the tasks capability is negotiated over 2026-07-28 connections, so mode="legacy" never triggers one and a task-enabled tool just runs synchronously.

A FastMCP server serves both eras, so a default client negotiates the modern one and the session-dependent calls raise an era-specific error there. Pinning the handshake restores them.

You can also pin a specific modern protocol version to adopt it directly, without a discovery probe:

client = Client("https://example.com/mcp", mode="2026-07-28")

Once connected, the negotiated version, server identity, capabilities, and instructions are available as properties. They are populated from either the legacy InitializeResult or modern DiscoverResult, and reset to None when the client disconnects. instructions is also None when the server does not provide any.

When you pin a modern version directly, the client skips discovery and adopts that version with minimal synthesized metadata. In that mode, server_info has an empty name and instructions is None.

async with Client("https://example.com/mcp", mode="auto") as client:
    print(client.protocol_version)      # e.g. "2026-07-28"
    print(client.server_info)           # Implementation | None
    print(client.server_capabilities)   # ServerCapabilities | None
    print(client.instructions)          # str | None

mode="auto" is the default as of FastMCP 4.0. Earlier versions defaulted to "legacy". If a server behaves unexpectedly under discovery, or you depend on the legacy initialize result, pin the old behavior with Client(..., mode="legacy").

The SSE transport is legacy-only — it cannot carry the sessionless modern era — so a client connecting over SSE always negotiates the legacy handshake, even under mode="auto". A multi-server config (MCPConfigTransport with more than one server) negotiates the best era shared by every connected backend: it stays modern when every backend is modern-capable and reconnects every leg under the handshake era when any backend requires legacy. Pinning mode="legacy" or a modern version applies that mode to every backend. All-modern configurations follow normal modern semantics; applications that rely on handshake-era server-initiated sampling or elicitation should pin mode="legacy". To keep each server on its own natively negotiated era instead, use one client per server — Client Groups coordinate several independent clients under one tool catalog.

Response caching

The client can cache the results of list_tools, list_resources, and list_prompts so that repeated calls avoid a network round-trip. Caching is opt-in and honors the server’s own cache hints, so it only takes effect against modern-era servers that advertise them — a cache is inert on a legacy connection.

Enable the default in-memory cache by passing cache=True. It respects the ttlMs and cacheScope hints the server attaches to each response.

from fastmcp import Client

client = Client("https://example.com/mcp", mode="auto", cache=True)

async with client:
    tools = await client.list_tools()   # fetched from the server
    tools = await client.list_tools()   # served from the cache

The default (cache=None) and cache=False both disable caching. For control over the store, TTL, or partitioning, pass a CacheConfig. A custom config requires a target_id, since in-memory FastMCP transports expose no server URL to derive a shared-store identity from.

from fastmcp import Client
from mcp.client.caching import CacheConfig

config = CacheConfig(target_id="weather-api", default_ttl_ms=60_000)
client = Client("https://example.com/mcp", mode="auto", cache=config)

The listing methods use the cache by default when one is configured. To override the behavior for a single call, pass cache_mode: "use" (the default) serves and stores, "refresh" stores a fresh result without serving a cached one, and "bypass" skips the cache entirely. list_tools accepts it directly; the lower-level list_tools_mcp, list_resources_mcp, list_resource_templates_mcp, and list_prompts_mcp variants accept it as well.

async with client:
    fresh = await client.list_tools(cache_mode="refresh")

Sharing a cache across clients

The default cache lives in each client’s process. To share cached responses across a fleet — a set of proxy replicas backed by one Redis, for example — pass a KeyValueResponseCacheStore, FastMCP’s adapter over the same AsyncKeyValue key-value abstraction the event store and OAuth proxy use. It accepts any compatible backend (memory, Redis, and more).

A shared store mingles responses from different principals, so it requires an explicit partition that isolates them. Derive the partition from a verified credential — never from request data or the server URL — and construct a new client when the principal changes. Only responses the server marks "public" are ever served across partitions.

from fastmcp import Client
from fastmcp.client.caching import KeyValueResponseCacheStore
from mcp.client.caching import CacheConfig
from key_value.aio.stores.redis import RedisStore

backend = RedisStore(url="redis://localhost")
store = KeyValueResponseCacheStore(storage=backend)

config = CacheConfig(store=store, partition="tenant-a", target_id="weather-api")
client = Client("https://example.com/mcp", mode="auto", cache=config)

The adapter serializes each result through a type-tagged envelope validated against an allowlist of cacheable result models, so a value naming an unknown type is treated as a cache miss rather than deserialized blindly. Each store instance owns its own collection namespace; clear() affects only that namespace, never another tenant’s entries.

Client extensions

Client extensions (SEP-2133) are the advanced mechanism a client uses to opt into vendor capabilities that live outside the core protocol. An extension is a ClientExtension instance that bundles three things: a capability advertisement the server can read, one or more result claims that let the client parse extra tools/call result shapes, and notification bindings that observe server notifications the core protocol doesn’t define. Pass a sequence of them to extensions=.

from fastmcp import Client
from myproject.extensions import AppsExtension

client = Client("https://example.com/mcp", extensions=[AppsExtension()])

Each extension’s contributions are threaded into the underlying session. FastMCP folds in its own internal extension for background tasks automatically, and your own extensions compose with it rather than replacing it — pass your own tasks extension with the same identifier if you need to override it. When a tool returns a shape an extension claims, client.call_tool() resolves it transparently through the owning claim’s resolver and hands you back an ordinary result. Result claims and their advertisements are honored only on modern-era connections, so they are inert on a legacy handshake.

For the rare case where you need to register additional result claims against an extension that is already advertised, pass them through result_claims=, keyed by the extension’s identifier. Prefer declaring claims on the extension itself; this parameter merges extra claims with an extension’s own.

client = Client(
    "https://example.com/mcp",
    extensions=[AppsExtension()],
    result_claims={"example.com/apps": [extra_claim]},
)

Operations

FastMCP clients interact with three types of server components.

Tools are server-side functions that the client can execute with arguments. Call them with call_tool() and receive structured results.

async with client:
    tools = await client.list_tools()
    result = await client.call_tool("multiply", {"a": 5, "b": 3})
    print(result.data)  # 15

See Tools for detailed documentation including version selection, error handling, and structured output.

Resources are data sources that the client can read, either static or templated. Access them with read_resource() using URIs.

async with client:
    resources = await client.list_resources()
    content = await client.read_resource("file:///config/settings.json")
    print(content[0].text)

See Resources for detailed documentation including templates and binary content.

Prompts are reusable message templates that can accept arguments. Retrieve rendered prompts with get_prompt().

async with client:
    prompts = await client.list_prompts()
    messages = await client.get_prompt("analyze_data", {"data": [1, 2, 3]})
    print(messages.messages)

See Prompts for detailed documentation including argument serialization.

Callback Handlers

The client supports callback handlers for advanced server interactions. These let you respond to server-initiated requests and receive notifications.

Sampling, elicitation, and roots are the requests a server makes of the client. A server reaches your handler by whichever route its era allows — pushed down the open session on the handshake, returned as an input-required result on the modern protocol — and both routes dispatch to the same handler, so one registration covers both. Logging and progress arrive as notifications on the response stream and work in either era.

from pathlib import Path

from fastmcp import Client
from fastmcp.client.logging import LogMessage

async def log_handler(message: LogMessage):
    print(f"Server log: {message.data}")

async def progress_handler(progress: float, total: float | None, message: str | None):
    print(f"Progress: {progress}/{total} - {message}")

async def sampling_handler(messages, params, context):
    # Integrate with your LLM service here
    return "Generated response"

client = Client(
    Path("my_mcp_server.py"),
    log_handler=log_handler,
    progress_handler=progress_handler,
    sampling_handler=sampling_handler,
    timeout=30.0
)

Each handler type has its own documentation:

• Sampling - Respond to server LLM requests
• Elicitation - Handle server requests for user input
• Progress - Monitor long-running operations
• Logging - Handle server log messages
• Roots - Provide local context to servers

The FastMCP Client is designed as a foundational tool. Use it directly for deterministic operations, or build higher-level agentic systems on top of its reliable, type-safe interface.