🔍 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

Setup

1. Build

cd syn-search-mcp
npm install
npm run build

Requires Node.js 18+.

2. Get a Synthetic API key

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

Parameter	Type	Default	Description
`query`	string	(required)	Search terms
`detail_level`	`"summary"` \| `"snippet"` \| `"ai-summary"` \| `"full"`	`"snippet"`	Result detail level
`summary_prompt`	string	(none)	Context/instructions for the AI summarizer (only used with `ai-summary`)
`max_results`	number	`5`	Max results to return (1–10)

detail_level guide

Mode	Output size	Tokens (est.)	Use case
`summary`	~500B	~150	Quick scan — "does anything relevant exist?"
`snippet`	~2KB	~550	Relevance check — "is this worth digging into?"
`ai-summary`	~1-3KB	~300-500	Real questions — focused, context-aware extraction
`full`	Up to 300KB+	~66K+	Deep dive — only when raw content is needed

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

Variable	Default	Description
`SYNTHETIC_API_KEY`	(required)	Synthetic API key (`syn_...`)
`SYN_SEARCH_SUMMARIZER_MODEL`	`syn:small:text`	Chat model used for `ai-summary`
`SYN_SEARCH_MAX_LINES`	`2000`	Truncation line limit
`SYN_SEARCH_MAX_BYTES`	`51200`	Truncation byte limit
`SYN_SEARCH_DEBUG`	(unset)	Set to `1` to log to stderr

Error handling

Scenario	Behavior
`SYNTHETIC_API_KEY` not set	isError result with setup instructions
Invalid API key (401)	isError result with key-check guidance
Rate limited (429)	isError result with retry advice
Network failure	isError result with connection guidance
Empty results	Informational message (not an error)
Request cancelled (Esc)	`"Synthetic API request was cancelled."`
Summarizer returns empty content	isError result suggesting `detail_level='full'`

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

syn-search-mcp