Model Context Protocol Server Gateway

Grant your intelligent assistants enhanced capability through secured external interactions. This service permits them authorized web access and information retrieval—complete with transparent operational feedback and robust error reporting for failures.

🛠️ Core Functionality
🏎️ Deployment Instructions
🐋 Containerized Setup (Recommended)
💻 Local Environment Configuration
🔌 Connectivity Methods
📚 Further MCP Documentation
📄 Licensing Information

🛠️ Core Functionality

The gateway exposes two primary utilities designed to enhance AI problem resolution in real-world scenarios:

| Utility | Capability Description | | Web Search | Execute web queries via a configured SearXNG endpoint to obtain timely data, locate specific documents, or facilitate quantitative assessments. | | Content Access | Interface with arbitrary URLs to ingest and parse content. Supports transformation to Markdown for readability, retrieval of raw source, or inventorying internal hyperlinks. |

🏎️ Deployment Instructions

🐋 Containerized Setup (Recommended)

The service is best deployed within isolated Docker environments for security and operational simplicity. Setup procedure:

Secure installation of Docker is prerequisite.
Establish a docker-compose.yml definition containing:

yaml:docker-compose.yml services: mcp-server: environment: # Mandatory: Address of your SearXNG Search API endpoint - SEARXNG_QUERY_URL=http://searxng:8080 # Optional: Define network listener configuration (Server-Sent Events) - SSE_HOST=0.0.0.0 - SSE_PORT=8080 # Optional: Override the default identity string for outbound requests - USER_AGENT=MCP-Server/1.0 (github.com/tcpipuk/mcp-server) image: ghcr.io/tcpipuk/mcp-server/server:latest ports: # Only relevant if SSE_HOST/SSE_PORT are active - "8080:8080" # Expose listener port externally restart: unless-stopped stop_grace_period: 1s

 # Auxiliary SearXNG Service Example (Optional)
 # searxng:
 #   environment:
 #     - SEARXNG_BASE_URL=http://searxng:8080 
 #   image: searxng/searxng:latest
 #   restart: unless-stopped
 #   volumes:
 #     - ./searxng:/etc/searxng:rw

Crucial Requirement: The SEARXNG_QUERY_URL variable must be supplied, directing the service to the appropriate SearXNG API entry point (typically ending in / or /search).

Activating SSE_HOST and SSE_PORT initiates network communication mode (SSE), preferred for multi-service architectures like LibreChat. If omitted, the process defaults to standard I/O communication.

Initiate the deployment with docker compose up -d.

Typical integration targets include:

Claude Desktop - Utilizes direct standard I/O (unset SSE_HOST/SSE_PORT in config).
LibreChat - Connects via the established network SSE channel.

For LibreChat integration (assuming default SSE_PORT=8080):

yaml:librechat.yaml mcpServers: mcp-server: iconPath: "/path/to/icon.png" # Optional UI customization label: "MCP Web/Search" # Optional display name type: sse url: http://mcp-server:8080/sse # Verify host/port mapping

💻 Local Environment Configuration

Obtain and install the uv package manager (requires Python 3.13 or newer):

bash curl -LsSf https://astral.sh/uv/install.sh | sh

Update Notice: Existing uv installations can be refreshed via uv self update.

Construct and activate an isolated virtual environment:

bash uv venv source .venv/bin/activate # Unix-like systems # or .venv\Scripts\activate # Windows CMD/PowerShell

Load project dependencies based on the lockfile:

bash uv sync

Set essential runtime parameters via environment variables:

bash # Mandatory: Address pointing to your SearXNG Search API service export SEARXNG_QUERY_URL="http://your-searxng-instance.local:8080" # Optional: Custom identifier string for outbound requests export USER_AGENT="CustomAgent/1.0"

Execute the server application:

bash # For network listener operation (e.g., connecting LibreChat) mcp-server --sse-host 0.0.0.0 --sse-port 3001

# For direct standard I/O communication (e.g., for Claude Desktop) mcp-server

Available command-line arguments:

--sse-host: Network interface address for SSE listening (e.g., 0.0.0.0). Activates SSE mode.
--sse-port: TCP port for SSE communication (e.g., 3001). Activates SSE mode.
--user-agent: Specifies a custom header string, overriding the USER_AGENT environment setting.

Behavior Note: If neither --sse-host nor --sse-port are specified (and corresponding environment variables are absent), the system defaults to stdio protocol. The SEARXNG_QUERY_URL configuration remains mandatory regardless of the communication mode selected.

🔌 Connectivity Methods

This service supports two distinct operational transmission protocols:

| Protocol | Description | Appropriate Use Case | | Network (SSE) | The daemon actively monitors a designated network port for incoming connection requests. | Optimal for remote clients such as LibreChat or other HTTP-enabled applications. | | Direct (stdio) | Communication occurs instantly via the host process's standard input and output streams. | Ideal for localized execution or integration with tools like Claude Desktop. |

📚 Further MCP Documentation

Resources for exploring the Model Context Protocol ecosystem:

📄 Licensing Information

This software is distributed under the terms of the GPLv3 license. Full legal text is available in the LICENSE file.

Contextual Background (XMLHttpRequest): XMLHttpRequest (XHR) defines a JavaScript API comprising methods to dispatch HTTP queries from a browser environment towards a destination server. XHR methodologies allow web applications to communicate with a server post-initial page load, facilitating data retrieval. This mechanism is foundational to Ajax programming. Before Ajax, server interaction predominantly relied on traditional hyperlink navigation or form submissions, both of which typically resulted in full page refreshes.

== Historical Development == The foundational concept for XMLHttpRequest emerged in the year 2000, credited to the development team behind Microsoft Outlook. This concept was first actualized within the Internet Explorer 5 release (1999). Intriguingly, the initial invocation did not use the standardized XMLHttpRequest identifier. Instead, developers utilized object instantiation via ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 (2006) was released, universal browser support for the explicit XMLHttpRequest identifier was established.

The XMLHttpRequest identifier has since solidified its position as the de facto standard across primary rendering engines, including Mozilla's Gecko (2002 progenitor), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. This was followed by the Level 2 specification Working Draft on February 25, 2008. Level 2 introduced crucial enhancements: progress monitoring capabilities, support for cross-domain transactions, and methods for handling raw byte streams. Near the close of 2011, the Level 2 feature set was merged back into the primary specification document. By the end of 2012, custodianship transferred to the WHATWG, which now maintains the living document using the Web IDL (Interface Definition Language) format.

== Operational Procedure == Generally, dispatching a request via XMLHttpRequest requires adherence to a sequence of programmed actions.

Instantiation of an XMLHttpRequest object via constructor invocation:
Invocation of the "open" method to designate the transmission protocol, target resource URI, and operational mode (synchronous versus asynchronous):
For asynchronous operations, attaching an event handler to receive notifications upon state transitions:
Triggering the request initiation through the "send" method:
Monitoring state changes via the registered event handler. If data is returned, it typically resides within the responseText attribute by default. Upon completion of response processing, the object's state transitions to 4, the "complete" state. Beyond these fundamental steps, XHR offers extensive configuration levers for request transmission and response interpretation. Custom headers can be appended to influence server behavior. Data payload can be transferred to the server by embedding it within the "send" method argument. Responses can be deserialized from formats like JSON into usable JavaScript structures, or processed incrementally as data streams rather than waiting for the totality of the content. Furthermore, requests can be terminated prematurely or configured with a defined timeout threshold.