Client: Interacting with Servers
Relevant source files
The following files were used as context for generating this wiki page:
- examples/clients/simple-chatbot/mcp_simple_chatbot/main.py
- examples/snippets/clients/parsing_tool_results.py
- tests/server/fastmcp/test_integration.py
- tests/shared/test_streamable_http.py
- tests/shared/test_ws.py
- examples/clients/simple-auth-client/README.md
- tests/server/fastmcp/auth/test_auth_integration.py
- tests/shared/test_progress_notifications.py
The MCP Python SDK provides a robust client system for interacting with MCP-compliant servers. The client is responsible for establishing a connection, managing the session lifecycle, and invoking server capabilities such as tools, resources, and prompts. It is designed to be transport-agnostic, supporting multiple communication protocols like StreamableHTTP, Server-Sent Events (SSE), and WebSockets.
The core of the client-side implementation is the ClientSession class, which encapsulates the logic for all MCP interactions. Clients are initialized by first creating a transport-specific connection and then wrapping it in a ClientSession instance. This design allows for flexible communication strategies while maintaining a consistent API for interacting with server functionalities.
Core Components
The ClientSession Class
The ClientSession is the primary interface for developers to interact with an MCP server. It manages the state of the connection, sends requests, and handles incoming messages from the server.
Sources: tests/server/fastmcp/test_integration.py:202, tests/shared/test_ws.py:141, tests/shared/test_streamable_http.py:539
Transport Clients
The SDK provides helper functions to establish connections over different transport protocols. Each function returns the necessary streams for the ClientSession to operate.
This diagram illustrates the process of a client selecting a transport to establish a session with an MCP server.
The available transport client functions are:
| Function | Description | Source File |
|---|---|---|
sse_client | Establishes a connection using Server-Sent Events (SSE). | tests/server/fastmcp/test_integration.py:190 |
streamablehttp_client | Establishes a connection using the StreamableHTTP transport. | tests/server/fastmcp/test_integration.py:192 |
websocket_client | Establishes a connection using WebSockets. | tests/shared/test_ws.py:142 |
Session Lifecycle
A client's interaction with a server follows a defined lifecycle, from initialization to termination.
Session Lifecycle Diagram
This sequence diagram shows the typical flow of a client session, including initialization, making requests, and handling server-initiated notifications.
Key ClientSession Methods
| Method | Description | Source File |
|---|---|---|
initialize() | Starts the session by exchanging capabilities with the server. Must be called first. | tests/server/fastmcp/test_integration.py:205 |
list_tools() | Retrieves a list of available tools from the server. | tests/server/fastmcp/test_integration.py:210 |
call_tool() | Executes a specific tool on the server with given arguments. | tests/server/fastmcp/test_integration.py:211 |
read_resource() | Reads the content of a resource specified by a URI. | tests/server/fastmcp/test_integration.py:241 |
list_prompts() | Retrieves a list of available prompts from the server. | tests/server/fastmcp/test_integration.py:273 |
get_prompt() | Renders a specific prompt with given arguments. | tests/server/fastmcp/test_integration.py:277 |
send_progress_notification() | Sends a progress update to the server for a long-running client-side task. | tests/shared/test_progress_notifications.py:123 |
close() | Terminates the session gracefully. | tests/shared/test_streamable_http.py:702-716 |
Authentication
Clients can authenticate with servers that support OAuth 2.0. The SDK client handles the PKCE (Proof Key for Code Exchange) flow automatically.
OAuth Flow for Clients
The client initiates the OAuth flow after discovering the server's authentication requirements.
- Discovery: The client first checks for the resource server's metadata at
/.well-known/oauth-protected-resourceto find the authorization server's URL. If that fails, it falls back to checking for/.well-known/oauth-authorization-serverat the server's root for legacy compatibility. - Authorization Request: The client opens the user's browser to the authorization endpoint.
- Token Exchange: After user authorization, the client receives an authorization code and exchanges it for an access token and a refresh token at the token endpoint.
Sources: examples/clients/simple-auth-client/README.md, examples/servers/simple-auth/README.md
This diagram shows the client-side OAuth 2.0 authentication flow.
Advanced Interactions
The client supports several advanced interaction patterns that are initiated by the server. These are handled via callbacks provided during ClientSession instantiation.
Callbacks for Server-Initiated Requests
| Callback | Parameter Name | Description | Source File |
|---|---|---|---|
| Message Handler | message_handler | A generic callback to process all incoming server messages, especially notifications like ProgressNotification or ResourceListChangedNotification. | tests/server/fastmcp/test_integration.py:321 |
| Progress Callback | progress_callback | A specific callback passed to methods like call_tool to handle progress updates for that specific request. | tests/server/fastmcp/test_integration.py:335 |
| Sampling Callback | sampling_callback | Handles workspace/createMessage requests from the server, typically to ask the client to generate a response from a large language model. | tests/server/fastmcp/test_integration.py:221 |
| Elicitation Callback | elicitation_callback | Handles workspace/elicit requests from the server, used to ask the user for input or confirmation. | tests/server/fastmcp/test_integration.py:231 |
Session Resumption with StreamableHTTP
The StreamableHTTP transport supports session resumption. If a client disconnects, it can reconnect and resume the event stream from where it left off by providing the mcp-session-id and the Last-Event-ID of the last message it received. The server will then replay any missed events.
*Sources: tests/shared/test_streamable_http.py:750-844, examples/servers/simple-streamablehttp/README.md
This diagram illustrates how a client using StreamableHTTP can resume a session after a disconnection.
Summary
The MCP Python SDK client provides a powerful and flexible framework for building applications that communicate with MCP servers. Its key strengths are the transport-agnostic ClientSession class, comprehensive support for the MCP specification including advanced features like progress notifications and elicitation, and robust handling of modern web protocols like StreamableHTTP with session resumption and OAuth 2.0 for secure authentication. This architecture enables developers to focus on application logic while the SDK handles the complexities of server communication.