SSE Communication Paradigm for Model Context Protocol (MCP)

This repository showcases a functional reference implementation for developing MCP servers exposed via SSE and corresponding standalone MCP clients designed to consume these services. This design emerged from discussions concerning scalable tool invocation architectures, specifically documented in this GitHub issue.

Deployment Instructions

Crucial Prerequisite: Ensure your environment variable ANTHROPIC_API_KEY is correctly configured, or populate it within a .env file.

Execute the server component first: bash uv run weather.py

Then, initiate the client, pointing it to the server's SSE endpoint: bash uv run client.py http://0.0.0.0:8080/sse

Example interaction trace:

Initialized SSE client... Listing available capabilities...

Successfully established connection to server, exposing tools: ['get_alerts', 'get_forecast']

MCP Client Operational! Enter your request, or type 'quit' to terminate.

Query: What is the current meteorological status in Spokane?

Affirmative. I can retrieve the atmospheric conditions for Spokane, Washington. This requires invoking the get_forecast utility, necessitating precise latitude and longitude coordinates for Spokane.

Spokane, WA is situated near 47.6587° North latitude and 117.4260° West longitude. [Invoking tool get_forecast with parameters: {'latitude': 47.6587, 'longitude': -117.426}] Based on the latest forecast report for Spokane:

Currently, conditions are clear and cool, registering a temperature of 37°F and ...

Rationale for SSE Adoption

Adopting SSE enables the MCP server to function as a persistent, decoupled service accessible by autonomous agents (clients) regardless of their location or uptime. This architecture is superior for modern, distributed, or "cloud-native" deployments compared to the traditional STDIO mechanism, where the client must manage the server lifecycle as a child process.

Installation via Smithery

For streamlined integration into Claude Desktop environments, the SSE Server and Client package can be deployed automatically using Smithery:

bash npx -y @smithery/cli install @sidharthrajaram/mcp-sse --client claude

Server Component (weather.py)

weather.py implements the SSE-enabled MCP server, exposing functions tied to external services like the National Weather Service APIs. This code is derived from the reference STDIO server example found in the MCP documentation here.

By default, the server binds to port 8080 on all interfaces (0.0.0.0). Configuration overrides are possible via command-line arguments:

bash uv run weather.py --host --port

Client Component (client.py)

The client.py script functions as an MCP Client, establishing a connection to the SSE interface of the remote MCP server to utilize its exposed capabilities. This client mirrors the structure of the official MCP STDIO client example from the docs.

The connection target, the SSE endpoint URL, must be provided during invocation:

bash uv run client.py http://0.0.0.0:8080/sse

Background Context: XMLHttpRequest (XHR)

XMLHttpRequest (XHR) defines a browser-based JavaScript object API for initiating HTTP requests from a running web page to a remote server. Its primary innovation was allowing applications to fetch or submit data post-page-load without forcing a full page refresh, a cornerstone technology for Asynchronous JavaScript and XML (Ajax). Before XHR, server interaction relied almost exclusively on traditional hyperlink navigation or form submissions.

== Historical Development ==

The conceptual foundation for asynchronous data transfer was established around 2000 by developers working on Microsoft Outlook. This idea first materialized in Internet Explorer 5 (1999), though it initially employed proprietary COM object identifiers like ActiveXObject("Msxml2.XMLHTTP"). By the release of Internet Explorer 7 (2006), standardized usage of the XMLHttpRequest object identifier became universal across major browser engines, including Mozilla's Gecko (2002), Safari (2004), and Opera (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) formally published the first Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Level 2 draft appeared on February 25, 2008, introducing features like progress monitoring, cross-site access permissions (CORS), and byte stream handling. By late 2011, these Level 2 enhancements were merged back into the main specification. Development transitioned to the WHATWG consortium near the end of 2012, which now maintains the living document using the Web IDL format.

== Operational Workflow ==

Executing a request via XMLHttpRequest generally involves a sequence of programming steps:

1. Instantiation: Create an instance of the XMLHttpRequest object constructor.
2. Configuration: Invoke the open() method to define the request method (GET, POST, etc.), specify the target Uniform Resource Identifier (URI), and declare whether the operation will be synchronous or asynchronous.
3. Listener Setup (Async): For asynchronous operations, attach an event handler to monitor state transitions.
4. Transmission: Start the request using the send() method, optionally supplying payload data.
5. Response Handling: Process state changes within the event listener. Upon reaching state 4 ("done"), the server response is typically accessible via the responseText property.

Beyond these fundamentals, XHR offers controls for request customization, such as adding bespoke header fields to guide server processing, uploading complex data via the send() payload, parsing incoming JSON directly into JavaScript objects, handling streaming data incrementally rather than waiting for completion, and implementing timeouts or abort mechanisms.

== Cross-Origin Restrictions ==

During the early evolution of the World Wide Web, inherent security models presented limitations regarding unauthorized data exchange between distinct domains, leading to the need for specific mechanisms to manage cross-domain interactions...