Synthetic Web Search Server

A Model Context Protocol (MCP) server that exposes the Synthetic web search API as a tool for use with Claude and other MCP-compatible applications.

npm version

Overview

This server provides a search_web tool that allows MCP clients to perform web searches using the Synthetic API. Search results are returned as formatted JSON containing URL, title, text, and published date fields.

Quick Start with Claude Code

Add the MCP server to Claude Code with a single command:

claude mcp add synthetic-web-search -e SYNTHETIC_API_KEY=your_api_key_here -- npx -y synthetic-web-search-mcp@latest

Replace your_api_key_here with your actual Synthetic API key.

Usage with Claude Desktop

To use this MCP server with Claude Desktop, add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "synthetic-web-search": {
      "command": "npx",
      "args": ["-y", "synthetic-web-search-mcp@latest"],
      "env": {
        "SYNTHETIC_API_KEY": "your_actual_api_key_here"
      }
    }
  }
}

After adding the configuration, restart Claude Desktop. You can then use the web search tool in your conversations.

Usage with opencode

To use this MCP server with opencode, add the following to your opencode configuration:

{
  "mcp": {
    "synthetic-web-search": {
      "type": "local",
      "command": ["npx", "-y", "synthetic-web-search-mcp@latest"],
      "environment": {
        "SYNTHETIC_API_KEY": "your_actual_api_key_here"
      },
      "enabled": true
    }
  }
}

Replace your_actual_api_key_here with your actual Synthetic API key. Restart opencode after adding the configuration.

Local Development & Testing

1. Prerequisites

• Node.js 18+
• A Synthetic API key

2. Install & build

npm install
npm run build

3. Test with MCP Inspector

The fastest way to verify the server interactively without any client configuration:

SYNTHETIC_API_KEY=your_key_here \
  npx @modelcontextprotocol/inspector node dist/index.js

This opens a browser UI where you can invoke search_web directly. Try:

• query only → text is capped at the default 1000 characters.
• query + max_text_length: 200 → tighter truncation to quickly scan results.
• query + max_text_length: 5000 → more content when you need full detail.

4. Test with Claude Code (local build)

claude mcp add synthetic-web-search \
  -e SYNTHETIC_API_KEY=your_key_here \
  -- node /absolute/path/to/synthetic-web-search-mcp/dist/index.js

5. Test with Claude Desktop (local build)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "synthetic-web-search": {
      "command": "node",
      "args": ["/absolute/path/to/synthetic-web-search-mcp/dist/index.js"],
      "env": {
        "SYNTHETIC_API_KEY": "your_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving the file.

Available Tools

search_web

Search the web using the Synthetic API.

Arguments:

• query (string, required): The search query string
• max_text_length (number, optional, default: 1000): Maximum number of characters to include in the text field of each result. Useful for preventing large snippets from flooding the context window. Results exceeding this length are truncated with .... Pass a larger value when you need the full content of a result.

Example:

Search for " TypeScript documentation"

Returns: A JSON array of search results, each containing:

• url: The link to the search result
• title: The title of the page
• text: A snippet or content from the page
• published: Publication date (if available)

API Details

• Endpoint: https://api.synthetic.new/v2/search
• Method: POST
• Authentication: Bearer token via Authorization header
• Request Body: JSON with query field

Project Structure

synthetic-web-search-mcp/
├── package.json
├── tsconfig.json
├── .env.example
├── README.md
├── src/
│   └── index.ts
└── dist/          (generated after build)
    ├── index.js
    └── index.d.ts

License

MIT