streamable_http_client.py

Overview

streamable_http_client.py is a lightweight asynchronous Python client script designed to demonstrate how to interact with an MCP (Modular Control Protocol) server over HTTP using a streamable HTTP client interface. The script establishes a bidirectional streaming HTTP connection to an MCP server endpoint, creates an MCP client session, initializes it, lists available tools on the server, and calls a specific tool with provided arguments. This file primarily serves as an example or utility script to showcase how to use the streamablehttp_client and ClientSession for remote procedure calls via streaming HTTP.

Detailed Explanation

Imports

• ClientSession from mcp: Core class representing a session with the MCP server, enabling tool listing and tool invocation.

• streamablehttp_client from mcp.client.streamable_http: Context manager that creates a pair of asynchronous read and write streams over HTTP for communication.

• anyio.run: Runs the asynchronous main function in an event loop.

Main Components

Function: main()

An asynchronous entry-point function that performs the following steps:

1. Establishes a streaming HTTP connection to the MCP server at http://localhost:9382/mcp/.

2. Opens a ClientSession over the established streams.

3. Initializes the session.

4. Retrieves and prints the list of tools available on the MCP server.

5. Calls the tool named "ragflow_retrieval" with a set of arguments, including dataset IDs, document IDs, and a question.

6. Prints the response from the tool call.

7. Catches and prints any exceptions that occur during the process.

Parameters

• None

Returns

• None (side effects: prints output to standard output)

Usage Example

import anyio
from streamable_http_client import main

anyio.run(main)

This will connect to the MCP endpoint, list available tools, invoke a specific tool, and print the results.

Script Entry Point

if __name__ == "__main__":
    from anyio import run
    run(main)

This ensures that when the script is run as the main program, it will execute the asynchronous main function within an anyio event loop.

Important Implementation Details

• Streaming HTTP Client: The script uses streamablehttp_client to open an asynchronous streaming HTTP connection. This allows for sending and receiving data in a streaming fashion, which is more efficient and suitable for real-time or large data transfers compared to traditional request-response HTTP models.

• MCP ClientSession: The ClientSession provides a high-level abstraction over the MCP communication protocol, including methods such as initialize(), list_tools(), and call_tool(). This encapsulates the complexity of protocol communication, allowing users to focus on invoking remote tools and handling results.

• Error Handling: The entire client logic is wrapped inside a try-except block to catch any exceptions during connection, session initialization, or tool invocation, printing the error for troubleshooting.

• Hardcoded Endpoint and Tool Arguments: The endpoint URL (http://localhost:9382/mcp/) and the tool call parameters are hardcoded, making this script a quick test or demo client rather than a reusable library component.

Interaction with Other System Components

• MCP Server: This client communicates with an MCP server endpoint over HTTP. The server is expected to accept streaming HTTP connections and speak the MCP protocol.

• mcp Library: Provides the ClientSession for MCP protocol handling.

• mcp.client.streamable_http Module: Provides the streaming HTTP client context manager used to establish the connection.

This file itself acts as a consumer of the MCP services exposed by the server and is likely part of a larger ecosystem where multiple tools and services are managed via the MCP protocol.

Usage Workflow Summary

1. Enter main() coroutine.

2. Open streaming HTTP connection with streamablehttp_client.

3. Create ClientSession over streams.

4. Initialize the session.

5. Fetch available tools.

6. Call a specific tool with parameters.

7. Print results.

8. Handle any errors.

Mermaid Class Diagram

classDiagram
    class streamablehttp_client {
        <<context manager>>
        +__aenter__()
        +__aexit__()
    }

    class ClientSession {
        +__aenter__()
        +__aexit__()
        +initialize()
        +list_tools()
        +call_tool(name: str, arguments: dict)
    }

    class main {
        <<async function>>
        +main()
    }

    main --> streamablehttp_client : uses
    main --> ClientSession : uses

Summary

The streamable_http_client.py script is a concise asynchronous client example demonstrating how to connect to an MCP server via streaming HTTP, initialize a session, list available tools, and perform a tool invocation. It serves as a practical reference for developers working with the MCP protocol and the InfiniFlow ecosystem, showcasing effective use of asynchronous context managers and streaming IO for remote procedure calls.