Overview

This MCP (Model Context Protocol) server provides a simple, centralized way to enforce explicit site inclusions and exclusions for Tavily Search and News API requests. Instead of embedding filtering logic into every client or service, you host a small HTTP endpoint that returns a contextual payload listing allowed and disallowed sites. Tavily components can fetch that payload and apply it to search/news queries, ensuring consistent behavior across environments.

The server is especially useful for teams that must restrict results to a curated set of domains (for compliance, relevance, or brand protection) or that need to block known low-quality or unsafe sources. It supports a lightweight JSON configuration format, can be deployed via Docker or run locally, and exposes a straightforward HTTP API for reading and updating the context.

Features

Serve a Model Context Protocol (MCP) JSON payload with site inclusion/exclusion lists
Separate lists for search and news endpoints
Simple REST endpoints to read or update the context
Load configuration from a JSON or YAML file and override with environment variables
Docker-friendly for quick deployment
Minimal dependencies so it can be integrated into CI/CD or edge setups

Installation / Configuration

Below are common ways to run the MCP server locally or in containers, plus sample config formats.

Run with Docker (recommended for quick start)

docker run -d \
  --name mcp-tavily \
  -p 8080:8080 \
  -v /path/to/mcp-config.json:/app/config/mcp-config.json:ro \
  ghcr.io/ramxx/mcp-tavily:latest

Run locally (Node/Python/Rust binary — example)

# Example generic start (replace with the project's actual start command)
./mcp-tavily --config ./mcp-config.json --port 8080

Environment variables

# Example env vars the server recognizes
MCP_CONFIG_PATH=/app/config/mcp-config.json
MCP_PORT=8080
MCP_ALLOW_UPDATES=true

Sample JSON configuration

{
  "mcp_version": "1.0",
  "search": {
    "site_inclusions": ["example.com", "docs.example.com"],
    "site_exclusions": ["ads.example.com", "malware-site.org"]
  },
  "news": {
    "site_inclusions": ["news.example.com", "trustednews.org"],
    "site_exclusions": ["tabloid.example"]
  }
}

YAML equivalent

mcp_version: "1.0"
search:
  site_inclusions:
    - example.com
    - docs.example.com
  site_exclusions:
    - ads.example.com
    - malware-site.org
news:
  site_inclusions:
    - news.example.com
    - trustednews.org
  site_exclusions:
    - tabloid.example

API examples

Get current MCP payload:
```
curl http://localhost:8080/mcp
```

Update MCP payload (if server allows updates):

curl -X PUT http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d @mcp-config.json

Configuration fields (quick reference)

Field	Type	Description
mcp_version	string	Protocol version identifier
search.site_inclusions	array[string]	Domains to include for search results
search.site_exclusions	array[string]	Domains to exclude from search results
news.site_inclusions	array[string]	Domains to include for news results
news.site_exclusions	array[string]	Domains to exclude from news results

Available Resources

GitHub repository (source and examples): https://github.com/RamXX/mcp-tavily
Example config files included in the repo: mcp-config.json / mcp-config.yaml
Docker image (tags available in the repo container registry)
Postman/HTTP examples directory for testing the endpoints

Use Cases

Restrict search to a corporate intranet
- Configure search.site_inclusions to only internal domains (e.g., intranet.example.com, docs.example.com). Tavily Search fetches the MCP payload and applies these inclusions so external domains never appear in results.
Block low-quality news domains across all clients
- Add known low-quality domains to news.site_exclusions. Any Tavily News API call that consults the MCP server will omit articles from those sources.
Region-specific filtering
- Maintain multiple MCP instances (or dynamically update the payload) per region. For EU users, serve a payload that excludes sources not compliant with local regulations.
Staging vs. Production behavior
- Use different config files or container images per environment. Staging can include test domains; production can restrict results to approved publishers.
Emergency blacklist
- When a domain needs to be blocked quickly (e.g., discovered malicious activity), update the MCP payload (via PUT or replacing the config) so all services pulling the MCP apply the exclusion immediately.

Integration tips

Decide precedence: apply inclusions first (limit set) then apply exclusions to ensure explicit blocks are enforced.
Cache the MCP payload for a short TTL in clients (e.g., 60–300s) to avoid excessive requests while still allowing fast updates.
Validate domain formats in your config to prevent malformed entries. Use domain-only strings (no protocol) to keep rules simple: example.com, sub.example.com.
If you need pattern matching, implement wildcard support on the server side (e.g., *.example.com) and document it for clients.

This MCP server is intended to be a lightweight, centralized control point for site-level filtering used by Tavily Search and News integrations. The server’s simplicity makes it easy to incorporate into continuous deployment and operational workflows.

Tavily Search MCP Server — Site Inclusions & Exclusions