WebSearch

WebSearch allows your Clovis models and agents to access the Web in real time, enriching their responses with up-to-date information.

Concretely, your model can:

• launch web searches,
• extract content from specific pages,
• map and crawl entire websites,
• analyze and synthesize recent content,
• provide reliable and contextualized answers.

WebSearch is exposed as an MCP server that your application, agent, or orchestrator can call directly.

Prerequisites

A valid Clovis API key (Bearer token)

The API key must have access to WebSearch

Network access to the Clovis gateway: https://llm-gateway.clovis-ai.fr

MCP Endpoint

The WebSearch MCP server is available at the following URL:

MCP server URL

https://llm-gateway.clovis-ai.fr/tools/websearch/mcp

All requests must include:

• an Authorization: Bearer <CLOVIS_API_KEY> header
• a Content-Type: application/json header
• an Accept: application/json, text/event-stream header

The server uses the MCP protocol (JSON-RPC 2.0 over HTTP with Server-Sent Events).

Available tools

The MCP server exposes 5 tools covering the entire web exploitation chain: discover, read, map, crawl, and monitor.

websearch-search

Performs a secure web search via the Tavily API, with a sanitization pipeline using ClovisLLM to detect sensitive information.

Parameter	Type	Required	Default	Description
query	string	✔️	—	Search query
search_depth	string		"basic"	Depth: "basic", "advanced", "fast", or "ultra-fast"
max_results	integer		10	Maximum number of results (1-20)
include_domains	array<string>		null	Domains to include only
exclude_domains	array<string>		null	Domains to exclude
topic	string		"general"	Category: "general" or "news"
time_range	string		null	Time filter: "day", "week", "month", or "year"
start_date	string		null	Start date (YYYY-MM-DD). Overrides time_range
end_date	string		null	End date (YYYY-MM-DD). Overrides time_range
include_images	boolean		false	Include images in results
include_image_descriptions	boolean		false	Include image descriptions (include_images required)
include_raw_content	boolean		false	Include raw page content
country	string		null	Country name to bias results (e.g., "france", "united states")
include_favicon	boolean		false	Include favicon URLs
exact_match	boolean		false	Only return exact query matches

websearch-extract

Extracts content from one or more URLs. Returns content in markdown or text format. The advanced mode handles protected or complex pages (LinkedIn, tables, embedded content).

Parameter	Type	Required	Default	Description
urls	array<string>	✔️	—	List of URLs to extract
extract_depth	string		"basic"	"basic" or "advanced" for protected/complex pages
include_images	boolean		false	Include images from pages
format	string		"markdown"	Output format: "markdown" or "text"
include_favicon	boolean		false	Include favicon URLs
query	string		null	Optional query to rerank content chunks by relevance

websearch-crawl

Crawls a website starting from a root URL, following internal links up to a configurable depth and page limit.

Parameter	Type	Required	Default	Description
url	string	✔️	—	Root URL to begin crawling
max_depth	integer		1	Maximum depth from base URL
max_breadth	integer		20	Maximum links to follow per page
limit	integer		50	Total pages to process
instructions	string		null	Natural language instructions for filtering pages
select_paths	array<string>		null	Regex patterns to filter URL paths (e.g., "/docs/.*")
select_domains	array<string>		null	Regex patterns to restrict to specific domains
allow_external	boolean		true	Follow external links
extract_depth	string		"basic"	"basic" or "advanced" for tables/embedded content
format	string		"markdown"	Output format: "markdown" or "text"
include_favicon	boolean		false	Include favicon URLs

websearch-map

Maps a website's structure. Returns a list of discovered URLs without extracting text content.

Parameter	Type	Required	Default	Description
url	string	✔️	—	Root URL to begin mapping
max_depth	integer		1	Maximum exploration depth
max_breadth	integer		20	Maximum links per page
limit	integer		50	Total pages to process
instructions	string		null	Natural language instructions for filtering pages
select_paths	array<string>		null	Regex patterns to filter URL paths
select_domains	array<string>		null	Regex patterns for domain filtering
allow_external	boolean		true	Include external links

websearch-search_status

Checks the server status and dependent services (Tavily health, guardrail and sanitization state).

Code examples

Initialize the MCP connection

curl

Initialize — curl

curl -X POST https://llm-gateway.clovis-ai.fr/tools/websearch/mcp \
-H "Authorization: Bearer $CLOVIS_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "my-app", "version": "1.0.0" }
  }
}'

Python

Initialize — Python

import requests

CLOVIS_API_KEY = "sk-xxxx"
MCP_URL = "https://llm-gateway.clovis-ai.fr/tools/websearch/mcp"

headers = {
  "Authorization": f"Bearer {CLOVIS_API_KEY}",
  "Content-Type": "application/json",
  "Accept": "application/json, text/event-stream",
}

resp = requests.post(MCP_URL, headers=headers, json={
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "my-app", "version": "1.0.0"},
  },
})
print(resp.text)

List available tools

curl

tools/list — curl

curl -X POST https://llm-gateway.clovis-ai.fr/tools/websearch/mcp \
-H "Authorization: Bearer $CLOVIS_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}'

Python

tools/list — Python

resp = requests.post(MCP_URL, headers=headers, json={
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {},
})
print(resp.text)

Perform a web search

curl

websearch-search — curl

curl -X POST https://llm-gateway.clovis-ai.fr/tools/websearch/mcp \
-H "Authorization: Bearer $CLOVIS_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "websearch-search",
    "arguments": {
      "query": "Latest AI news in France",
      "max_results": 5,
      "search_depth": "advanced",
      "topic": "news",
      "country": "france"
    }
  }
}'

Python

websearch-search — Python

resp = requests.post(MCP_URL, headers=headers, json={
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
      "name": "websearch-search",
      "arguments": {
          "query": "Latest AI news in France",
          "max_results": 5,
          "search_depth": "advanced",
          "topic": "news",
          "country": "france",
      },
  },
})
print(resp.text)

Extract content from a URL

curl

websearch-extract — curl

curl -X POST https://llm-gateway.clovis-ai.fr/tools/websearch/mcp \
-H "Authorization: Bearer $CLOVIS_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "websearch-extract",
    "arguments": {
      "urls": ["https://www.clovis-ai.fr"],
      "format": "markdown",
      "extract_depth": "basic"
    }
  }
}'

Python

websearch-extract — Python

resp = requests.post(MCP_URL, headers=headers, json={
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
      "name": "websearch-extract",
      "arguments": {
          "urls": ["https://www.clovis-ai.fr"],
          "format": "markdown",
          "extract_depth": "basic",
      },
  },
})
print(resp.text)

Example response

Response

{
"jsonrpc": "2.0",
"id": 4,
"result": {
  "content": [
    {
      "type": "text",
      "text": "{\"success\":true,\"data\":{\"results\":[{\"url\":\"https://www.clovis-ai.fr\",\"title\":\"Clovis - IA de confiance\",\"raw_content\":\"# Clovis, l'IA de confiance.\n\nYour 100% French AI platform...\"
      }]}}"
    }
  ],
  "isError": false
}
}

Map a website

curl

websearch-map — curl

curl -X POST https://llm-gateway.clovis-ai.fr/tools/websearch/mcp \
-H "Authorization: Bearer $CLOVIS_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "websearch-map",
    "arguments": {
      "url": "https://www.clovis-ai.fr",
      "max_depth": 1,
      "limit": 10
    }
  }
}'

Python

websearch-map — Python

resp = requests.post(MCP_URL, headers=headers, json={
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
      "name": "websearch-map",
      "arguments": {
          "url": "https://www.clovis-ai.fr",
          "max_depth": 1,
          "limit": 10,
      },
  },
})
print(resp.text)

Crawl a website

curl

websearch-crawl — curl

curl -X POST https://llm-gateway.clovis-ai.fr/tools/websearch/mcp \
-H "Authorization: Bearer $CLOVIS_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "websearch-crawl",
    "arguments": {
      "url": "https://www.clovis-ai.fr",
      "max_depth": 1,
      "limit": 10,
      "format": "markdown"
    }
  }
}'

Python

websearch-crawl — Python

resp = requests.post(MCP_URL, headers=headers, json={
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
      "name": "websearch-crawl",
      "arguments": {
          "url": "https://www.clovis-ai.fr",
          "max_depth": 1,
          "limit": 10,
          "format": "markdown",
      },
  },
})
print(resp.text)

Check service status

curl

websearch-search_status — curl

curl -X POST https://llm-gateway.clovis-ai.fr/tools/websearch/mcp \
-H "Authorization: Bearer $CLOVIS_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "websearch-search_status",
    "arguments": {}
  }
}'

Python

websearch-search_status — Python

resp = requests.post(MCP_URL, headers=headers, json={
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
      "name": "websearch-search_status",
      "arguments": {},
  },
})
print(resp.text)

Example response

Response

{
"jsonrpc": "2.0",
"id": 7,
"result": {
  "content": [
    {
      "type": "text",
      "text": "{\"success\":true,\"data\":{\"server_version\":\"0.2.0\",\"tavily\":{\"healthy\":true,\"error\":null},\"guardrail\":{\"enabled\":true,\"status\":\"healthy\",\"endpoint\":\"https://llm-gateway.clovis-ai.fr/\",\"model\":\"ClovisLLM/gpt-oss-120b\"},\"sanitization\":{\"requests\":true,\"responses\":true}}}"
    }
  ],
  "isError": false
}
}