---
name: searchpipe-search
description: Web search, online search, real-time search, internet search, search the web, lookup online, find information, research, Chinese web search. SearchPipe real-time web search API built for AI agents via MCP.
---

# SearchPipe Search Skill (MCP-based)

This skill utilizes the SearchPipe MCP server, providing clean, real-time web search results purpose-built for AI agents.

## MCP Endpoint

| Item | Value |
|------|-------|
| **Transport** | streamable-http (remote MCP) |
| **MCP URL** | `https://searchpipe.tech/mcp/?api_key=sp-YOUR_API_KEY` |
| **Tool name** | `searchpipe_search` |

SearchPipe is a **remote MCP server**: the API key is embedded directly in the MCP URL via
the `api_key` parameter (same pattern as Tavily's `?tavilyApiKey=`). Any client that
supports streamable-http can use it out of the box — no custom request headers required.

## How to Obtain an API Key and MCP Link

**Check the user's prompt first**: if it already contains an **MCP link** (in the form
`https://searchpipe.tech/mcp/?api_key=sp-...`) or an **API key** (starting with `sp-`), use it to
complete the configuration directly. Do not ask the user for credentials again, and do
not ask the user to operate the dashboard manually. Only walk through the steps below
when neither a key nor a link is present in the prompt:

1. Visit `https://searchpipe.tech/dashboard/register` to create an account (free credits included
   upon registration). Once email verification is complete, the system will
   **automatically generate a default API key** — no manual creation needed.
2. After logging in, open the "API Keys" page: `https://searchpipe.tech/dashboard/api-keys` — keys
   are masked by default; click "Show" to reveal the plaintext. The "MCP Configuration"
   card on that page lets you switch keys and copy the MCP link or the
   **one-line setup prompt** (includes the key, ready to paste to your agent).
3. Configure the MCP link in your client (see the examples below).

## MCP Client Configuration Examples

### Claude Code

```bash
claude mcp add --transport http searchpipe "https://searchpipe.tech/mcp/?api_key=sp-YOUR_API_KEY"
```

Or edit `.mcp.json` manually:

```json
{
  "mcpServers": {
    "searchpipe": {
      "type": "http",
      "url": "https://searchpipe.tech/mcp/?api_key=sp-YOUR_API_KEY"
    }
  }
}
```

### Cursor

Add the following in Cursor Settings → MCP:

```json
{
  "mcpServers": {
    "searchpipe": {
      "url": "https://searchpipe.tech/mcp/?api_key=sp-YOUR_API_KEY"
    }
  }
}
```

### Other streamable-http MCP Clients

Generic configuration format (key embedded in URL):

```json
{
  "mcpServers": {
    "searchpipe": {
      "transport": "streamable-http",
      "url": "https://searchpipe.tech/mcp/?api_key=sp-YOUR_API_KEY"
    }
  }
}
```

If the client supports custom request headers, you can also use header-based
authentication (choose one of the two approaches):

```json
{
  "mcpServers": {
    "searchpipe": {
      "url": "https://searchpipe.tech/mcp/",
      "headers": {
        "Authorization": "Bearer sp-YOUR_API_KEY"
      }
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `searchpipe_search` | Web search (aggregates multiple engines → fetches page content → LLM reranking → optional AI answer) |

## Parameters

### searchpipe_search

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `query` | Yes | - | The search query |
| `max_results` | No | 5 | Maximum number of results to return (1–20) |
| `include_answer` | No | false | Whether to generate an AI answer with citations |
| `include_raw_content` | No | false | Whether to return the full fetched page content |
| `search_depth` | No | basic | Search depth: `basic` (costs 1 credit) / `advanced` (costs 2 credits) |

## Output Format

Returns structured results in JSON:

```json
{
  "query": "your search query",
  "answer": "AI-generated answer with citations [0][1]",
  "ai_generated": true,
  "results": [
    {
      "url": "https://example.com",
      "title": "Page title",
      "content": "Content snippet",
      "score": 0.95,
      "raw_content": "Full page content (only when include_raw_content=true)"
    }
  ]
}
```

## Verification

After configuration, send a test instruction to the agent:

> Please use the searchpipe tool to search for "FastAPI deployment best practices".

The agent should successfully call `searchpipe_search` and return structured results.

**The MCP handshake is not authenticated**: `initialize` returns server info for any
request, with or without a valid key. A successful handshake therefore proves nothing
about the credentials — only an actual `tools/call` does. Always finish configuration
by running one real search; never report success based on the handshake alone.

## Troubleshooting

| Symptom | Cause | Solution |
|---------|-------|----------|
| Handshake OK but a search returns `Missing valid sp- API key` | The key was not delivered with the request: the URL lost its `?api_key=` part (a redirect or proxy that drops the query string, e.g. a request to `/mcp` without the trailing slash on some hosts), or the client strips query parameters | Use the exact MCP link from the dashboard (`.../mcp/?api_key=sp-...`, note the trailing slash), or switch to header auth (`Authorization: Bearer sp-...`) which survives redirects |
| "Invalid or revoked API key" | Key does not exist or has been revoked | Create a new API key in the dashboard |
| "Insufficient credits" | Free credits exhausted | Top up at `https://searchpipe.tech/dashboard/billing` |
| "Search backend failure" | SearXNG search backend error | Credits are automatically refunded; safe to retry |
| "Input/Output content violation" | Content moderation triggered | Rephrase the query; output violations are automatically refunded |

---

*SearchPipe — real-time web search built for AI agents · https://searchpipe.tech*