WebSharp MCP HTTP Server

WebSharp MCP HTTP Server exposes web search and readable page extraction tools over a streamable HTTP transport. It combines a SearXNG metasearch backend with SmartReader content extraction, enabling fast search results and readable page extraction in a local or containerized setup.

How to use

You interact with the MCP server using an MCP client. The server offers two primary tools you can call to perform search and page reading tasks. Use the web_search tool to query the connected SearXNG backend and receive a readable summary along with structured metadata. Use the web_page_read tool to fetch and parse one or more URLs, returning a readable excerpt and page metadata. When you run multiple requests, the server handles them concurrently and supports cancellation tokens to stop long-running fetches.

To start, ensure the MCP server is reachable at the configured endpoint. If you are running with Docker Compose, the MCP endpoint is accessible at the container’s exposed port, and you can inspect the SearXNG service at its own port. If you run from source, you will start the .NET server and expose it on a local URL for testing. From your MCP client, issue calls to the available tools by their names and provide the required parameters described in the tool definitions.

How to install

Prerequisites you need before installing the MCP server: a compatible .NET runtime and SDK, Docker for container-based runs, and a reachable SearXNG endpoint if you choose the Docker route.

Option A: Run with Docker Compose (recommended for quick local testing)

docker compose -f docker-compose.yaml --project-name websharp up -d

# On first run or when Dockerfiles change, add --build
docker compose -f docker-compose.yaml --project-name websharp up -d --build

# Wait for the MCP container to announce it is listening
# You should see a log line like: Now listening on: http://0.0.0.0:8080

# Access MCP endpoint at http://localhost:8081 (container port 8080 mapped to host)

Option B: Run from source (need .NET 9 SDK)

dotnet run --project src/WebSharp.Mcp.Http/WebSharp.Mcp.Http.csproj --urls http://localhost:8081

# The MCP endpoint will listen at the root path
# If you built in DEBUG, you can inspect endpoints at http://localhost:8081/__routes

Prerequisites before starting from source or with Docker: ensure you have access to a SearXNG backend. If you are not using the bundled Docker service, export the base URL for SearXNG as an environment variable before starting the app.

Additional content

Configuration and runtime notes: the server exposes a streamable HTTP MCP endpoint and is designed to run behind a reverse proxy or VPN when exposed beyond localhost. Timeouts and cancellation tokens are applied to ensure responsive behavior. The HTTP transport does not include built-in authentication, so consider network-level protections in production.

Security and networking: tighten CORS and restrict origins before deploying to shared environments. The server uses ASP.NET Core for the HTTP endpoint and relies on a SearXNG backend for search results and a SmartReader-based reader for page extraction.

Using a different SearXNG instance: update the SearXNG base URL to point to your hosted deployment and ensure the endpoint exposes the required search API and engines. You may adjust the bundled searxng/settings.yml to tune engines, safe search, or rate limits before publishing.

Environment variables you may encounter during setup include ASPNETCORE_URLS (listening address for the HTTP server), Searxng__BaseUrl (base URL of the SearXNG instance), and various Cors settings to control cross-origin requests. These can be supplied via environment variables or appsettings.json files.

Notes on tooling and usage patterns

Two MCP tools are available: web_search for metasearch results and structured content, and web_page_read for extracting readable text from one or more URLs. The server returns a textual summary and a structuredContent payload for web_search, and a per-page result set for web_page_read when multiple URLs are provided.

Available tools

web_search

Queries the SearXNG backend and returns a readable summary plus structured content with results, suggestions, and engine status.

web_page_read

Fetches one or more URLs and returns a readable excerpt, full text per page, and language metadata for each page.