🔍 syn-search-mcp

An MCP server that adds web search using Synthetic's Search API. Built for OpenCode, works with any MCP client.

Port of the pi-synthetic-search Pi extension to a standalone MCP server.

Features

• synthetic_search tool — automatically available to the LLM alongside built-in tools

• 4-tier payload control to protect your context window:

  • Result count limit — caps at 5 results by default (configurable, max 10)

  • detail_level parameter — LLM chooses its own tradeoff:

    • summary — title + URL + date only (~50 tokens/result)

    • snippet — + 300-char text excerpt (~100 tokens/result)

    • ai-summary — full text sent to AI summarizer with optional focus prompt (~300-500 tokens total)

    • full — complete untruncated text (LLM opts in for deep reads)

  • summary_prompt parameter — when using ai-summary, the LLM can provide conversation context to focus the summarizer on what matters

  • Overall truncation — safety net at 2000 lines / 50KB; full output saved to a temp file the LLM can read

• AI Summarizer — uses Synthetic's chat completions API (syn:small:text) to condense search results into focused, query-relevant summaries

• Graceful error handling — missing key, 401, 429, network failures

• Abort-aware — respects client cancellation (e.g. Esc in OpenCode) during in-flight requests

Related MCP server: Synthetic Search MCP Server

Setup

1. Build

cd syn-search-mcp
npm install
npm run build

Requires Node.js 18+.

2. Get a Synthetic API key

Sign up at synthetic.new and grab your API key (starts with syn_).

3. Add to OpenCode

Global — ~/.config/opencode/opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "syn-search": {
      "type": "local",
      "command": ["node", "/path/to/syn-search-mcp/dist/index.js"],
      "environment": {
        "SYNTHETIC_API_KEY": "{env:SYNTHETIC_API_KEY}"
      },
      "enabled": true
    }
  }
}

Project-local — same object under mcp in an opencode.json at the project root.

The key is read from SYNTHETIC_API_KEY (set in your shell or passed via the environment block). You can also hardcode it there instead of {env:...}.

4. Restart OpenCode

The tool is exposed as syn-search_synthetic_search. Ask it anything that needs search:

Search the web for the latest TypeScript 5.x features

Tool parameters

detail_level guide

ai-summary example

{
  "query": "Docker multi-stage builds",
  "detail_level": "ai-summary",
  "summary_prompt": "User is trying to reduce a Node.js Docker image from 1.2GB to under 200MB. Focus on layer caching, Alpine vs Debian, and COPY vs ADD patterns."
}

The summarizer becomes a lightweight sub-agent — the main LLM delegates research focus via summary_prompt, and only relevant info returns to the context window.

Truncation

When output exceeds 2000 lines or 50KB, it's truncated with a notice; the full output is written to a temp file:

[Output truncated: showing 1210 of 8954 lines (48.8KB of 297.3KB).
 7744 lines (248.5KB) omitted.
 Full output saved to: /tmp/syn-search-mcp-XXXX/search-results.txt
 — use the read tool to view it.]

Environment variables

Error handling

Errors return isError: true tool results so the LLM knows the search failed and can react accordingly.

Testing

# smoke test against the live API (uses SYNTHETIC_API_KEY from your env)
node scripts/smoke-test.mjs summary
node scripts/smoke-test.mjs ai-summary

# interactive MCP inspector
npx @modelcontextprotocol/inspector node dist/index.js

License

MIT