Overview

Cloudsway SmartSearch MCP Server is an MCP-compatible service that wraps the Cloudsway Smart Search API and returns structured JSON results suitable for downstream processing. It exposes a single MCP tool (SmartSearch) that performs web searches with options for pagination, language, freshness, and host filtering. The server is designed to be plugged into MCP runtimes or agents so LLMs and other MCP clients can request web results programmatically.

This server is useful when you need deterministic, machine-friendly search outputs rather than raw HTML or unstructured snippets. Results include metadata such as publication and crawl dates, site name, thumbnails and a relevance score—helpful for citation, summarization, or automated pipelines that require precise fields.

Features

Web search with pagination (offset + count)
Language selection (recommended 4-letter codes like en-US)
Freshness filtering (Day / Week / Month / date ranges)
Host/site restriction (e.g., github.com)
Structured JSON response with fields for title, URL, snippet, dates, site and score
MCP-compatible server configuration for easy deployment with MCP runtimes
Simple authentication via a single SERVER_KEY environment variable

Input Parameters

Parameter	Type	Required	Default	Description
query	string	yes	—	Search keywords (cannot be empty)
count	int	no	10	Results to return. Allowed: 10, 20, 30, 40, 50 (max 50)
offset	int	no	0	Zero-based pagination offset
setLang	string	no	“en”	Language code (recommended: en-US, fr-FR, etc.)
freshness	string	no	—	Time filter: Day, Week, Month or date range like 2023-02-01..2023-05-30
sites	string	no	—	Restrict results to a host (e.g., github.com)

Response Structure

On success the server returns JSON with a query context and a webPages object. Example:

{
  "queryContext": { "originalQuery": "your search query" },
  "webPages": {
    "value": [
      {
        "name": "Page Title",
        "url": "https://example.com/page",
        "displayUrl": "https://example.com/page",
        "snippet": "Description of the page content...",
        "datePublished": "2025-07-14T00:00:00.0000000",
        "dateLastCrawled": "2025-07-15T02:48:00.0000000Z",
        "siteName": "Example Website",
        "thumbnailUrl": "https://example.com/thumbnail.jpg",
        "score": 0.95
      }
    ]
  }
}

Key fields:

queryContext.originalQuery — submitted query string
webPages.value[] — list of result items containing name, url, snippet, datePublished, dateLastCrawled, siteName, thumbnailUrl, score

Error Handling & Limits

Common HTTP responses:

200 — success
429 — rate limit exceeded (QPS limit reached)

If you encounter rate limits or account-level issues, contact Cloudsway support via the console. Implement exponential backoff for 429 responses and respect pagination to avoid excessive QPS.

Installation / Configuration

Get your Cloudsway search credentials:
- Sign in at https://console.cloudsway.ai
- Obtain Endpoint and AccessKey
- Combine them as: {Endpoint}-{AccessKey}
Set the combined key as SERVER_KEY in your environment:

export SERVER_KEY="endpoint-accesskey"

Example MCP service configuration (JSON) to run the SmartSearch server:

{
  "mcpServers": {
    "smartsearch": {
      "command": "npx",
      "args": [
        "-y",
        "@cloudsway-ai/smartsearch"
      ],
      "env": {
        "SERVER_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Entry point within the package:

src/smartsearch/smartsearch.py

Ensure your deployment environment provides SERVER_KEY to the process before launching.

Available Tools / Resources

GitHub repository: https://github.com/Cloudsway-AI/smartsearch — source, packaging and examples
Tool name available via MCP: SmartSearch — accepts the input parameters listed above and returns the structured JSON response

Use Cases

Research assistants: Fetch recent results for a topic and surface citations with dates and source URLs for LLM summarization.
Monitoring: Query a specific site or host for new articles in a date range and ingest results into a pipeline.
QA / fact-checking: Retrieve multiple pages for a claim and feed the structured snippets and scores to a verifier model.
Summarization pipelines: Use the structured fields (snippet, datePublished, score) to prioritize and summarize authoritative sources.

Example MCP tool call payload (JSON) to request 20 results from the last week in en-US:

{
  "tool": "SmartSearch",
  "input": {
    "query": "latest advances in webassembly",
    "count": 20,
    "offset": 0,
    "setLang": "en-US",
    "freshness": "Week"
  }
}

Example curl (if exposing an HTTP wrapper):

curl -X POST "http://localhost:PORT/search" \
  -H "Content-Type: application/json" \
  -d '{"query":"site:github.com cloudsway smartsearch","count":10}'

Notes

Keep queries concise and prefer language codes like en-US where available to improve relevance.
Use site filtering for targeted scraping of repositories or domains.
Respect usage limits; implement retry/backoff logic for 429 responses.

Cloudsway SmartSearch MCP Server Structured JSON Results