Client SDK Overview
Relevant source files
The following files were used as context for generating this wiki page:The MCP Python Client SDK provides the necessary components for a client application to communicate with an MCP-compliant server. It is designed to be transport-agnostic, with a core ClientSession class that handles the MCP message-level protocol, and separate transport implementations (StreamableHTTP, SSE, WebSocket) that manage the underlying connection.
The primary goal of the SDK is to abstract the complexities of the MCP protocol, allowing developers to focus on application logic such as calling tools, reading resources, and handling server-initiated events like notifications and sampling requests. The SDK supports features like session management, authentication, progress reporting, and session resumption.
Core Architecture
The client architecture is centered around the ClientSession class, which orchestrates all communication with the server. This session is fed by a transport-specific context manager (streamablehttp_client, sse_client, or websocket_client) that provides abstract read and write streams.
Sources: src/mcp/client/session.py, tests/shared/test_streamable_http.py:1003-1014, tests/server/fastmcp/test_integration.py:175-184
Component Diagram
This diagram shows the relationship between the main client components.
ClientSession
The ClientSession is the main entry point for interacting with an MCP server. It manages the session lifecycle, sends requests, and dispatches incoming messages from the server.
Sources: src/mcp/client/session.py:40
Key ClientSession Methods
| Method | Description |
|---|---|
initialize() | Establishes and initializes the session with the server. Must be called first. |
list_tools() | Retrieves the list of available tools from the server. |
call_tool() | Invokes a specific tool on the server with given arguments. |
list_resources() | Retrieves the list of available static resources. |
read_resource() | Reads the content of a specific resource URI. |
list_prompts() | Retrieves the list of available prompts. |
get_prompt() | Renders a specific prompt with given arguments. |
send_ping() | Sends a ping request to check the connection health. |
Sources: src/mcp/client/session.py:139-301
Session Initialization and Lifecycle
A client session begins with an initialize request and ends when the session is closed, either by the client or server. The StreamableHTTP transport also supports explicit session termination via a DELETE request.
This sequence diagram illustrates the typical lifecycle of a client session.
Handling Server-Initiated Events
The ClientSession can be configured with callbacks to handle events initiated by the server.
sampling_callback: Invoked when the server requests the client to generate a message, typically via an LLM.elicitation_callback: Invoked when the server needs to elicit information or confirmation from the user.message_handler: A generic handler for all incoming server notifications (e.g.,log_message,progress,resource_updated).
Sources: src/mcp/client/session.py:47-53, tests/server/fastmcp/test_integration.py:200-213, tests/shared/test_streamable_http.py:1329-1348
Transports
The SDK provides multiple transport implementations. The choice of transport depends on the server's capabilities.
StreamableHTTP Transport
This is the most advanced transport, using standard HTTP methods (POST, GET, DELETE) to manage the session. It supports both streaming responses (via Server-Sent Events) and simple JSON responses.
Sources: mcp/client/streamable_http.py, tests/shared/test_streamable_http.py
Key Features
- Session Management: A session is created with the initial
POSTrequest. The server returns anmcp-session-idheader, which must be included in all subsequent requests. - Server Notifications: A long-lived
GETrequest is established to receive server-initiated notifications in an SSE stream. - Session Termination: A
DELETErequest to the/mcpendpoint terminates the session on the server. - Session Resumption: If a connection is lost, a client can reconnect and resume the event stream by providing the
Last-Event-IDheader. This requires the server to use anEventStore. - Protocol Versioning: After initialization, the client sends the negotiated
mcp-protocol-versionheader in subsequent requests to ensure compatibility.
Sources: tests/shared/test_streamable_http.py:49-53, 61-64, 608-615, 715-738, 1205-1262, examples/servers/simple-streamablehttp/README.md
StreamableHTTP Flow
This diagram shows the flow of requests in the StreamableHTTP transport.
SSE and WebSocket Transports
- SSE (
sse_client): A simpler transport that uses a single long-livedPOSTrequest to an/sseendpoint. All communication, including the initial handshake and subsequent messages, occurs over this single Server-Sent Events stream. - WebSocket (
websocket_client): Establishes a WebSocket connection to a/wsendpoint. All JSON-RPC messages are sent and received as WebSocket messages over this persistent connection.
Sources: tests/server/fastmcp/test_integration.py:175-184, tests/shared/test_ws.py:117-126
Authentication
The client is responsible for handling authentication. For OAuth 2.0, the client must perform the authorization flow to obtain an access token. This token is then typically passed as a Bearer token in the Authorization header of the transport requests.
The streamablehttp_client and other transport clients accept a headers dictionary, which can be used to pass the necessary authentication credentials.
Sources: examples/clients/simple-auth-client/README.md, tests/server/fastmcp/auth/test_auth_integration.py:1003-1012
OAuth Flow Example
The following sequence diagram outlines the client's role in an OAuth 2.0 flow with an MCP server.
Summary
The Python Client SDK provides a robust and flexible way to build applications that interact with MCP servers. Its core ClientSession handles the protocol logic, while swappable transport layers manage the underlying connection details. The StreamableHTTP transport is particularly powerful, offering features like session resumption and a dedicated channel for server-sent events, making it suitable for complex, long-running interactions. By providing clear interfaces for tools, resources, and server-initiated events, the SDK allows developers to build sophisticated client applications with relative ease.