MCP OpenAI Service Adapter

AI agents are quite remarkable. I envisioned extending my own Claude's capabilities to encompass such features, and now that is realized—it proves both beneficial and entertaining for him. Your Claude counterpart can now leverage this as well!

This MCP server component serves as an intermediary for interfacing with OpenAI's suite of assistant functionalities. It empowers other client applications (such as Claude Desktop) to provision and converse with OpenAI assistants by adhering to the Model Context Protocol.

Core Capabilities

This provision offers a comprehensive set of primitives for overseeing and engaging with OpenAI Assistants. The integration of novel streaming mechanisms dramatically enhances the user experience by delivering real-time feedback.

Exposed Operations

• create_assistant: (Provision OpenAI Assistant) - Instantiate a novel assistant, specifying its identifier name, foundational instructions, and the underlying model.
• list_assistants: (Enumerate OpenAI Assistants) - Retrieve a catalogue of all assistants linked to the configured API credential set.
• retrieve_assistant: (Fetch OpenAI Assistant Details) - Obtain granular data pertaining to a singular, specified assistant entity.
• update_assistant: (Modify OpenAI Assistant) - Revise the attributes of an extant assistant, including its label, operational guidelines, or model selection.
• create_new_assistant_thread: (Establish New Assistant Dialogue Channel) - Generates a durable conversation context, allowing for client-side naming and description for straightforward referencing and resumption. This is the preferred method for initiating dialogue sessions.
• list_threads: (Display Managed Dialogue Channels) - Fetches and presents all conversation contexts persisted locally in the database, detailing their unique ID, assigned name, descriptive label, and last interaction timestamp.
• delete_thread: (Purge Dialogue Channel) - Eradicates a specific conversation context from both the remote OpenAI infrastructure and the local persistence layer.
• ask_assistant_in_thread: (Query Assistant within Channel and Stream Output) - The principal mechanism for dialogue. It transmits user input into the designated thread and relays the resulting output to the client instantly as it is generated.

Given the potential latency in OpenAI assistant responses, this adapter employs a streaming methodology for the primary ask_assistant_in_thread function. This ensures the client receives continuous progress indicators, mitigating the risk of connection timeouts.

The server now incorporates local state management for conversation threads, representing a substantial functional leap. Since the native OpenAI interface lacks a thread listing capability, this adapter takes responsibility for thread bookkeeping by persistently recording IDs and metadata in an embedded SQLite data store. This enables seamless discovery, reuse, and governance of conversational contexts across multiple operational sessions.

Deployment

Smithery Installation Route

To integrate the MCP OpenAI Service Adapter into Claude Desktop automatically using Smithery:

npx -y @smithery/cli install mcp-simple-openai-assistant --client claude

Manual Setup

pip install mcp-simple-openai-assistant

Configuration Directives

The operational server mandates the presence of a valid OpenAI API credential, typically set via an environment variable. For Claude Desktop integration, incorporate the following stanza into its configuration file:

(MacOS environment)

{
  "mcpServers": {
    "openai-assistant": {
      "command": "python",
      "args": ["-m", "mcp_simple_openai_assistant"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

(Windows environment)

"mcpServers": {
  "openai-assistant": {
    "command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\Python\\Python311\\python.exe",
      "args": ["-m", "mcp_simple_openai_assistant"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
  }
}

MS Windows setup is somewhat more intricate, requiring verification of the precise path to the Python interpreter executable. The example path above is common but may require adjustment for your system. Occasionally, simply specifying python.exe suffices. Consult your command prompt (perhaps using where python) to confirm the correct invocation. Furthermore, Windows users might need to explicitly declare the location of site packages via the PYTHONPATH environment variable for full compatibility.

Operational Flow

Once the adapter is configured, utilize the functions enumerated above to manage your assistants and dialogue contexts. The standard sequence of actions is: 1. Invoke create_new_assistant_thread to initiate a new, identifiable conversation session. 2. Employ list_threads to locate the identifier for a thread slated for continuation. 3. Utilize ask_assistant_in_thread to engage the designated assistant within that specific context.

Future Enhancements (To Do List)

• [x] Thread Lifecycle Management: Implement functionality for naming and persistently storing thread identifiers locally, facilitating easier context resumption.
• [ ] Model Inventory Exposure: Add an operation allowing the AI consumer to inspect the repertoire of OpenAI models accessible for assistant deployment.
• [ ] Assistant Parameter Control: Facilitate specification of detailed assistant configuration parameters (e.g., temperature, top_p) as requested by Claude.
• [ ] Complete Dialogue History Retrieval: Introduce the capability to fetch the entire history of a thread without requiring a new message transmission (as identified as a necessity by Claude).
• [ ] Resource Integration Exploration: Integrate support for uploading external data files for use within assistant operations.

Development Setup

To set up the repository for active development:

git clone https://github.com/andybrandt/mcp-simple-openai-assistant
cd mcp-simple-openai-assistant
pip install -e '.[dev]'

WIKIPEDIA: XMLHttpRequest (XHR) constitutes an Application Programming Interface realized as a JavaScript construct engineered to transmit Hypertext Transfer Protocol requests from a web browser environment to a remote web server. Its methods permit a web-based application to dispatch inquiries to the server subsequent to page rendering completion, and subsequently receive data back. XMLHttpRequest is a fundamental element of Ajax programming paradigms. Before Ajax, navigational links and form submissions were the dominant methodologies for server communication, frequently resulting in the complete replacement of the current webpage content.

== Chronology == The underlying concept for XMLHttpRequest was formulated in the year 2000 by the engineering team behind Microsoft Outlook. This conceptual framework was subsequently implemented within the Internet Explorer 5 browser release (1999). Nevertheless, the initial invocation syntax did not employ the explicit XMLHttpRequest moniker. Instead, developers relied upon the instantiation syntax ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (released 2006), ubiquity in browser support for the XMLHttpRequest identifier was achieved. The XMLHttpRequest identifier has since evolved into the conventional standard across all major browser platforms, including Mozilla's Gecko rendering engine (2002), Safari version 1.2 (2004), and Opera version 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) formally published an initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C released the Level 2 specification draft. Level 2 augmented functionality with methods for monitoring event progress, enabling cross-site data transfers, and facilitating the handling of raw byte streams. By the close of 2011, the Level 2 specification features were merged back into the primary specification document. At the conclusion of 2012, stewardship for development transitioned to the WHATWG, which now maintains the living document utilizing Web IDL definitions.

== Application == Ordinarily, dispatching a server request using XMLHttpRequest involves several distinct programmatic stages.

Instantiate an XMLHttpRequest object via a constructor call: Invoke the open methodology to define the request verb (type), specify the target resource address, and select between synchronous or asynchronous execution modes: For asynchronous operations, install an event handler function to be invoked upon changes in the request's status: Commence the transmission by calling the send methodology: Process state transitions within the established event listener. If server data is returned, it is typically accumulated in the responseText attribute by default. When the object finalizes response processing, its status transitions to state 4, the terminal state: Beyond these fundamental procedural steps, XMLHttpRequest offers numerous configuration parameters to govern transmission behavior and response interpretation. Custom header fields can be appended to the request to convey specific server handling instructions, and arbitrary data can be uploaded by supplying it as an argument to the send invocation. The received payload can be automatically parsed from JSON format into an immediately actionable JavaScript object, or it can be processed incrementally as segments arrive, avoiding wait for total reception. The request can be terminated prematurely or configured to fail if not completed within a predetermined time threshold.

== Inter-Domain Requests ==

During the nascent period of the World Wide Web's evolution, limitations were identified regarding the feasibility of brea