diff --git a/docs/src/pages/docs/desktop/mcp-examples/search/_meta.json b/docs/src/pages/docs/desktop/mcp-examples/search/_meta.json index 649e3e15e1..7ae269618a 100644 --- a/docs/src/pages/docs/desktop/mcp-examples/search/_meta.json +++ b/docs/src/pages/docs/desktop/mcp-examples/search/_meta.json @@ -4,5 +4,8 @@ }, "serper": { "title": "Serper Search" + }, + "serpex": { + "title": "Serpex Search" } } diff --git a/docs/src/pages/docs/desktop/mcp-examples/search/serpex.mdx b/docs/src/pages/docs/desktop/mcp-examples/search/serpex.mdx new file mode 100644 index 0000000000..c5d23249e7 --- /dev/null +++ b/docs/src/pages/docs/desktop/mcp-examples/search/serpex.mdx @@ -0,0 +1,199 @@ +--- + +title: Serpex Search MCP + +description: Connect Jan to multi-engine web search with structured JSON results through Serpex API. + +keywords: + + [ + Jan, + MCP, + Model Context Protocol, + Serpex, + Google search API, + Real-time Search API, + MCP Web search, + SERP API, + multi-engine search, + web search, + real-time search, + tool calling, + Jan v1, + Google search, + Bing search, + DuckDuckGo, + Brave search, + ] + +--- + +import { Callout, Steps } from 'nextra/components' + +# Serpex Search MCP + +[Serpex](https://serpex.dev) provides unified access to multiple search engines (Google, Bing, DuckDuckGo, Brave, Yahoo, Yandex) through a single API, making it perfect for giving AI models access to real-time web information with automatic engine routing and structured JSON results. + +## Available Tools + +- `serpex_search`: Search across multiple engines with automatic routing and time filtering + +## Prerequisites + +- Jan with experimental features enabled +- Serpex API key from [serpex.dev](https://serpex.dev) +- Model with tool calling support (recommended: Jan v1) + + +Serpex offers 200 free credits to get started, with requests starting at just $0.0008 each. The API handles retries, blocking and captchas automatically. + + +## Setup + +### Enable Experimental Features + +1. Go to **Settings** > **General** +2. Toggle **Experimental Features** ON + +![Enable experimental features](../../_assets/enable_mcp.png) + +### Enable MCP + +1. Go to **Settings** > **MCP Servers** +2. Toggle **Allow All MCP Tool Permission** ON + +![Turn on MCP](../../_assets/turn_on_mcp.png) + +### Get Serpex API Key + +1. Visit [serpex.dev](https://serpex.dev) +2. Sign up for an account +3. Navigate to your dashboard +4. Copy your API key + +### Configure MCP Server + +Click `+` in MCP Servers section: + +**Configuration:** +- **Server Name**: `serpex` +- **Command**: `npx` +- **Arguments**: `-y serpex-mcp` +- **Environment Variables**: + - Key: `SERPEX_API_KEY`, Value: `your-api-key` + +![Serper MCP configuration in Jan](../../_assets/serper_janparams.png) + + +Using `npx` means you don't need to install anything - it will automatically download and run the latest version of the Serpex MCP server from npm. + + +### Download Jan v1 + +Jan v1 is optimized for tool calling and works excellently with Serpex: + +1. Go to the **Hub** tab +2. Search for **Jan v1** +3. Choose your preferred quantization +4. Click **Download** + +![Download Jan v1 from Hub](../../_assets/download_janv1.png) + +### Enable Tool Calling + +1. Go to **Settings** > **Model Providers** > **Llama.cpp** +2. Find Jan v1 in your models list +3. Click the edit icon +4. Toggle **Tools** ON + +![Enable tools for Jan v1](../../_assets/toggle_tools.png) + +## Usage + +### Start a New Chat + +With Jan v1 selected and Serpex configured, you'll see the Serpex search tool available. + +### Example Queries + +**Current Information:** +``` +What are the latest developments in quantum computing this week? +``` + +**Multi-Engine Search:** +``` +Search for "best AI models 2025" using different search engines and compare the results. +``` + +**Comparative Analysis:** +``` +What are the main differences between TypeScript and JavaScript? Give me current best practices. +``` + +**Research Tasks:** +``` +Find recent news about SpaceX Starship launches. +``` + +**Time-Filtered Search:** +``` +What are the top tech news stories from the last 24 hours? +``` + +**Local Information:** +``` +Find coffee shops in San Francisco that opened this year. +``` + +## How It Works + +1. **Query Processing**: Jan v1 analyzes your question and determines search parameters +2. **Engine Selection**: Serpex automatically routes to the best available engine (or uses your specified engine) +3. **Web Search**: Calls Serpex API which handles captchas, blocks, and retries automatically +4. **Result Parsing**: Returns clean, structured JSON with titles, URLs, snippets, and metadata +5. **Synthesis**: Jan v1 combines search results into a comprehensive, conversational answer + +## Tips for Best Results + +- **Be specific**: "Tesla Model 3 2024 price in California" works better than "Tesla price" +- **Use auto engine**: Let Serpex choose the best engine automatically with `engine: 'auto'` +- **Request recent info**: Use time_range parameter or add "latest", "recent" to queries +- **Ask follow-ups**: Jan v1 maintains context for deeper research +- **Combine with analysis**: Ask for comparisons, summaries, or insights from search results + +## Troubleshooting + +### Server Won't Start +- Verify `SERPEX_API_KEY` is set correctly in environment variables +- Check that Node.js is installed and accessible +- Ensure all dependencies are installed: `npm install` + +### No Results Returned +- Check your API key is valid at [serpex.dev](https://serpex.dev) +- Verify you have available credits in your Serpex account +- Try with `engine: 'auto'` to let Serpex choose the best engine + +### Tool Not Showing in Jan +- Ensure experimental features are enabled +- Verify MCP is enabled and permissions are granted +- Restart Jan after adding the MCP server +- Check that Jan v1 has tools enabled in model settings + + +Each search query consumes API credits. Monitor usage at serpex.dev dashboard. + + +## API Limits + +Serpex offers flexible pricing: + +- **Free Tier**: Generous limits for testing and personal use +- **Rate Limit**: 300 requests/second +- **Pay-as-you-go**: Only pay for what you use, no subscription + +Visit [serpex.dev/pricing](https://serpex.dev/pricing) for current pricing details. + +## Next Steps + +Serpex MCP enables Jan v1 to access current web information across multiple search engines, making it a powerful research assistant. Combine with other MCP tools for even more capabilities - use Serpex for search, then E2B for data analysis, or Jupyter for visualization.