The FastMCP Client
Programmatic client for interacting with MCP servers through a well-typed, Pythonic interface.
New in version: 2.0.0
The central piece of MCP client applications is the fastmcp.Client
class. This class provides a programmatic interface for interacting with any Model Context Protocol (MCP) server, handling protocol details and connection management automatically.
The FastMCP Client is designed for deterministic, controlled interactions rather than autonomous behavior, making it ideal for:
- Testing MCP servers during development
- Building deterministic applications that need reliable MCP interactions
- Creating the foundation for agentic or LLM-based clients with structured, type-safe operations
All client operations require using the async with
context manager for proper connection lifecycle management.
This is not an agentic client - it requires explicit function calls and provides direct control over all MCP operations. Use it as a building block for higher-level systems.
Creating a Client
Creating a client is straightforward. You provide a server source and the client automatically infers the appropriate transport mechanism.
Client-Transport Architecture
The FastMCP Client separates concerns between protocol and connection:
Client
: Handles MCP protocol operations (tools, resources, prompts) and manages callbacksTransport
: Establishes and maintains the connection (WebSockets, HTTP, Stdio, in-memory)
Transport Inference
The client automatically infers the appropriate transport based on the input:
FastMCP
instance → In-memory transport (perfect for testing)- File path ending in
.py
→ Python Stdio transport - File path ending in
.js
→ Node.js Stdio transport - URL starting with
http://
orhttps://
→ HTTP transport MCPConfig
dictionary → Multi-server client
For testing and development, always prefer the in-memory transport by passing a FastMCP
server directly to the client. This eliminates network complexity and separate processes.
Configuration-Based Clients
New in version: 2.4.0
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.
Configuration Format
Multi-Server Example
Connection Lifecycle
The client operates asynchronously and uses context managers for connection management:
Operations
FastMCP clients can interact with several types of server components:
Tools
Tools are server-side functions that the client can execute with arguments.
See Tools for detailed documentation.
Resources
Resources are data sources that the client can read, either static or templated.
See Resources for detailed documentation.
Prompts
Prompts are reusable message templates that can accept arguments.
See Prompts for detailed documentation.
Server Connectivity
Use ping()
to verify the server is reachable:
Client Configuration
Clients can be configured with additional handlers and settings for specialized use cases.
Callback Handlers
The client supports several callback handlers for advanced server interactions:
The Client
constructor accepts several configuration options:
transport
: Transport instance or source for automatic inferencelog_handler
: Handle server log messagesprogress_handler
: Monitor long-running operationssampling_handler
: Respond to server LLM requestsroots
: Provide local context to serverstimeout
: Default timeout for requests (in seconds)
Transport Configuration
For detailed transport configuration (headers, authentication, environment variables), see the Transports documentation.
Next Steps
Explore the detailed documentation for each operation type:
Core Operations
- Tools - Execute server-side functions and handle results
- Resources - Access static and templated resources
- Prompts - Work with message templates and argument serialization
Advanced Features
- Logging - Handle server log messages
- Progress - Monitor long-running operations
- Sampling - Respond to server LLM requests
- Roots - Provide local context to servers
Connection Details
- Transports - Configure connection methods and parameters
- Authentication - Set up OAuth and bearer token authentication
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.